Polytomic subpackage_connections API

openapi: 3.1.0
info:
  title: API Reference subpackage_bulkSync subpackage_connections API
  version: 1.0.0
servers:
- url: https://app.polytomic.com
tags:
- name: subpackage_connections
paths:
  /api/connection_types:
    get:
      operationId: get-types
      summary: Get Connection Types
      description: 'Lists all connection types supported by this deployment.


        Each entry includes per-type metadata:


        - The available operations the connection type supports.

        - Its category.

        - Whether the connection type is enabled for the caller''s organization.

        - Which modes (source, destination, enrichment) it can act as.'
      tags:
      - subpackage_connections
      parameters:
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionTypeResponseEnvelope'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/connection_types/{id}:
    get:
      operationId: get-connection-type-schema
      summary: Get Connection Type
      description: 'Returns the JSON schema for a connection type.


        This schema is intended for building forms or validating configuration payloads

        client-side. It describes the structure Polytomic expects when you create or

        update a connection of the given type.


        The response is metadata about the shape of the configuration, not a live

        connection instance and not a set of current credential values.'
      tags:
      - subpackage_connections
      parameters:
      - name: id
        in: path
        description: Connection type identifier (e.g. postgresql, salesforce, hubspot).
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer user API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonschemaSchema'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/connection_types/{type}/parameter_values:
    post:
      operationId: get-type-parameter-values
      summary: Connection Type Parameter Values
      description: 'Returns completion values for parameter fields on a connection type.


        This endpoint is useful during connection setup, before a connection exists or

        before you want to persist it. The supplied `parameters` are applied to a

        temporary in-memory connection shape and used to resolve dependent options.


        When an endpoint requires upstream authorization before it can return values,

        Polytomic returns an error instead of guessing. In that case, complete the

        authorization flow first and call the endpoint again.'
      tags:
      - subpackage_connections
      parameters:
      - name: type
        in: path
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer user API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionParameterValuesResponseEnvelope'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetConnectionTypeParameterValuesRequestSchema'
  /api/connections:
    get:
      operationId: list
      summary: List Connections
      description: 'Lists every connection in the caller''s organization, with sensitive fields redacted.


        Sensitive configuration values — passwords, API tokens, private keys — are

        redacted from all responses. To understand which fields a connection type

        exposes, consult the parameter schema returned by

        [`GET /api/connection_types`](../../api-reference/connections/get-types).


        To inspect the data objects available on a specific connection, use

        [`POST /api/connections/{id}/schemas/refresh`](../../api-reference/schemas/refresh)

        followed by [`GET /api/connections/{id}/schemas/status`](../../api-reference/schemas/get-status).'
      tags:
      - subpackage_connections
      parameters:
      - name: Authorization
        in: header
        description: Bearer user API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionListResponseEnvelope'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    post:
      operationId: create
      summary: Create Connection
      description: 'Creates a new connection of the specified type.


        Use [`GET /api/connection_types`](../../api-reference/connections/get-types) to retrieve the

        list of available types and their parameter schemas. The `configuration`

        object is type-specific; consult the [integration

        guides](../../guides/configuring-your-connections/overview)

        for the required and optional fields for each type.


        > 📘 Polytomic validates the connection against the upstream service

        > immediately on creation. The request will fail if the credentials or

        > endpoint cannot be reached.'
      tags:
      - subpackage_connections
      parameters:
      - name: Authorization
        in: header
        description: Bearer user API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateConnectionResponseEnvelope'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConnectionRequestSchema'
  /api/connections/connect/:
    post:
      operationId: connect
      summary: Connect
      description: 'Creates a Polytomic Connect session and returns a redirect URL that embeds the Connect modal.


        See also:


        - [Embedding authentication](../../../guides/embedding-authentication), a guide to using Polytomic Connect.'
      tags:
      - subpackage_connections
      parameters:
      - name: Authorization
        in: header
        description: Bearer user API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectCardResponseEnvelope'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectCardRequest'
  /api/connections/test:
    post:
      operationId: test-connection
      summary: Test Connection
      description: 'Tests a connection configuration.


        This endpoint is useful for setup flows that want to verify credentials before

        persisting them.


        If you provide `connection_id`, Polytomic starts from the saved configuration

        for that connection and then applies the request''s `configuration` values on

        top. This lets callers test a partial change without resending every existing

        field.


        The request does not persist any configuration changes even when validation

        succeeds.'
      tags:
      - subpackage_connections
      parameters:
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestConnectionRequest'
  /api/connections/{id}:
    get:
      operationId: get
      summary: Get Connection
      description: 'Returns a single connection by ID, with sensitive fields redacted.


        To inspect the schemas available on this connection, trigger a refresh with

        [`POST /api/connections/{id}/schemas/refresh`](../../../api-reference/schemas/refresh) and

        track progress via

        [`GET /api/connections/{id}/schemas/status`](../../../api-reference/schemas/get-status).'
      tags:
      - subpackage_connections
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: Bearer user API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionResponseEnvelope'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    put:
      operationId: update
      summary: Update Connection
      description: 'Updates a connection''s configuration.


        Updating a connection is a **full replacement** of its configuration. Any

        `configuration` field you omit is cleared. To make a partial change, fetch

        the current connection with

        [`GET /api/connections/{id}`](../../../api-reference/connections/get), apply your edits, and send the

        complete object back.


        > 📘 The connection is re-validated against the upstream service after every

        > update. The request will fail if the new credentials or endpoint cannot be

        > reached.


        Syncs that are already running when the update is submitted are not

        interrupted; the updated configuration takes effect on their next execution.'
      tags:
      - subpackage_connections
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: Bearer user API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateConnectionResponseEnvelope'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConnectionRequestSchema'
    delete:
      operationId: delete
      summary: Delete Connection
      description: 'Deletes a connection.


        > 🚧 Deleting a connection that is referenced by fieldsets, syncs, bulk

        > syncs, or schedules returns `422 connection in use` unless you pass

        > `force=true`. With `force=true`, the API deletes those dependent

        > resources before removing the connection.'
      tags:
      - subpackage_connections
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: force
        in: query
        required: false
        schema:
          type: boolean
      - name: Authorization
        in: header
        description: Bearer user API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/connections/{id}/parameter_values:
    get:
      operationId: get-parameter-values
      summary: Connection Parameter Values
      description: 'Returns completion values for parameter fields on a persisted connection.


        Use this endpoint when the available options for one parameter depend on the

        connection''s saved credentials or previously selected settings. For example,

        after a connection is authorized, the upstream service may be able to return

        lists of databases, schemas, or similar selectable values.


        For new setup flows, prefer

        [`POST /api/connection_types/{type}/parameter_values`](../../../../api-reference/connections/get-type-parameter-values),

        which lets you resolve completions before the connection has been created.'
      tags:
      - subpackage_connections
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: Bearer user API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionParameterValuesResponseEnvelope'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/connections/{id}/proxy:
    post:
      operationId: execute-proxy
      summary: Execute Connection Proxy
      description: "Proxies an HTTP request to a connection's underlying API using the connection's stored credentials, subject to per-connection rate limits and size caps.\n\nThis endpoint is intended for controlled passthrough use, not as a general\nreplacement for Polytomic's modeled endpoints. The request is executed with the\nconnection's stored credentials and inherited base URL, headers, and query\nparameters.\n\nBefore building requests dynamically, call\n[`GET /api/connections/{id}/proxy/info`](../../../../api-reference/connections/get-proxy-info)\nto inspect the inherited base URL, blocked headers, accepted body types, and\nsize and rate limits.\n\n## Important behavior\n\n- `request.path` must be relative and start with `/`.\n- Use either `request.query` or `request.rawQuery`, not both.\n- Caller-supplied headers are merged with inherited headers, but inherited auth\n  headers cannot be overridden.\n- The proxy strips a fixed set of request and response headers for safety.\n- Response bodies larger than the configured maximum are truncated, and\n  `truncated` is set to `true`.\n\nThe response includes `proxyCallId`, which you can use to correlate the call\nwith audit logs."
      tags:
      - subpackage_connections
      parameters:
      - name: id
        in: path
        description: Unique identifier of the connection to proxy the request through.
        required: true
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: Bearer user API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecuteConnectionProxyEnvelope'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecuteConnectionProxyRequest'
  /api/connections/{id}/proxy/info:
    get:
      operationId: get-proxy-info
      summary: Get Connection Proxy Info
      description: 'Returns the proxy contract for a connection.


        Use this endpoint before calling

        [`POST /api/connections/{id}/proxy`](../../../../../api-reference/connections/execute-proxy)

        when you need to build requests programmatically. The response shows:


        - the inherited base URL that all proxied requests are sent to

        - locked headers and query parameters that are attached automatically

        - blocked request and response headers

        - allowed HTTP methods and body shapes

        - timeout, rate-limit, and payload-size limits


        Sensitive inherited header and query values are redacted in the response. The

        contract is still useful for discovering which keys are fixed by the

        connection, even though their raw values are not exposed.'
      tags:
      - subpackage_connections
      parameters:
      - name: id
        in: path
        description: Unique identifier of the connection whose proxy contract should be returned.
        required: true
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: Bearer user API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetConnectionProxyInfoEnvelope'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/connections/{id}/shared:
    get:
      operationId: list-shared-connections
      summary: List Current Org Shared Connections
      description: 'Lists shared copies of a connection that the caller''s organization owns.


        The returned connections are the child copies, not the parent connection

        itself. This is useful when a partner workflow needs to confirm which

        downstream organizations have already received a shared copy.


        Creating a new shared copy is a separate operation. Use

        [`POST /api/organizations/{org_id}/connections/{connection_id}/share`](../../../../api-reference/connections/create-shared-connection)

        for the v5 partner-scoped flow.'
      tags:
      - subpackage_connections
      parameters:
      - name: id
        in: path
        description: Unique identifier of the parent connection whose shared copies should be listed.
        required: true
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: Bearer user API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionListResponseEnvelope'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /api/organizations/{org_id}/connections/{connection_id}/shared:
    get:
      operationId: list-shared-connections-for-partner
      summary: List Partner Shared Connections
      description: 'Lists shared copies of a connection owned by a specific organization in the partner account.


        The `org_id` must match the organization that owns the parent connection. If it

        does not, the endpoint returns `404` rather than exposing information about the

        parent connection.


        This endpoint is useful in partner workflows where the parent connection is in

        the partner owner organization and the caller needs to audit which child

        organizations already have a shared copy.'
      tags:
      - subpackage_connections
      parameters:
      - name: org_id
        in: path
        description: Unique identifier of the organization that owns the parent connection.
        required: true
        schema:
          type: string
          format: uuid
      - name: connection_id
        in: path
        description: Unique identifier of the parent connection whose shared copies should be listed.
        required: true
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: Bearer partner API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionListResponseEnvelope'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    post:
      operationId: create-shared-connection
      summary: Create Partner Shared Connection
      description: Shares a connection with another organization in the caller's partner account.
      tags:
      - subpackage_connections
      parameters:
      - name: org_id
        in: path
        description: Unique identifier of the organization that owns the parent connection.
        required: true
        schema:
          type: string
          format: uuid
      - name: connection_id
        in: path
        description: Unique identifier of the parent connection to share.
        required: true
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: Bearer partner API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSharedConnectionResponseEnvelope'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerCreateSharedConnectionRequestSchema'
components:
  schemas:
    ConnectionResponseEnvelope:
      type: object
      prop

# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/polytomic/refs/heads/main/openapi/polytomic-subpackage-connections-api-openapi.yml