openapi: 3.1.0
info:
  title: API Reference subpackage_bulkSync subpackage_bulkSync.subpackage_bulkSync/schemas API
  version: 1.0.0
servers:
- url: https://app.polytomic.com
tags:
- name: subpackage_bulkSync.subpackage_bulkSync/schemas
paths:
  /api/bulk/syncs/{id}/schemas:
    get:
      operationId: list
      summary: Get Bulk Sync Schemas
      description: 'Lists the schemas (tables, objects) configured for a bulk sync.


        This endpoint returns the schemas that have been added to and configured on this

        specific bulk sync — not the full set of schemas available from the source

        connection. To discover what the source connection exposes, use the source

        schemas endpoint for the relevant connection type.


        Each schema in the response includes its sync mode, field selections, and any

        custom configuration applied via

        [`PATCH /api/bulk/syncs/{id}/schemas`](../../../../../api-reference/bulk-sync/schemas/patch)

        or

        [`PUT /api/bulk/syncs/{id}/schemas/{schema_id}`](../../../../../api-reference/bulk-sync/schemas/update).'
      tags:
      - subpackage_bulkSync.subpackage_bulkSync/schemas
      parameters:
      - name: id
        in: path
        description: Unique identifier of the bulk sync.
        required: true
        schema:
          type: string
          format: uuid
      - name: filters
        in: query
        description: Optional filters applied to the returned schemas. Supports enabled=true to return only enabled schemas and enabled=false to return only disabled schemas.
        required: false
        schema:
          type: object
          additionalProperties:
            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/ListBulkSchemaEnvelope'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    patch:
      operationId: patch
      summary: Update Bulk Sync Schemas
      description: 'Patches one or more schemas on a bulk sync at once.


        Only schemas explicitly included in the request body are modified; schemas

        omitted from the request are left unchanged. This makes PATCH the right choice

        when you want to update a subset of tables without affecting the rest of the

        sync''s schema configuration.


        Within each provided schema, omitting `fields` enables all available fields on

        that schema. To control which fields are enabled, include the `fields` array

        with explicit `enabled` values for each field.


        > 📘 To replace a single schema''s configuration in full (clearing any fields you

        > omit), use

        > [`PUT /api/bulk/syncs/{id}/schemas/{schema_id}`](../../../../../api-reference/bulk-sync/schemas/update)

        > instead.'
      tags:
      - subpackage_bulkSync.subpackage_bulkSync/schemas
      parameters:
      - name: id
        in: path
        description: Unique identifier of the bulk sync.
        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/UpdateBulkSyncSchemasEnvelope'
        '400':
          description: Bad Request
          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'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBulkSyncSchemasRequest'
  /api/bulk/syncs/{id}/schemas/{schema_id}:
    get:
      operationId: get
      summary: Get Bulk Sync Schema
      description: 'Returns the configuration of a single schema on a bulk sync.


        Returns the sync mode, field selections, and any other configuration applied to

        this schema on the bulk sync.


        To modify the configuration, use

        [`PATCH /api/bulk/syncs/{id}/schemas`](../../../../../../api-reference/bulk-sync/schemas/patch)

        for a partial update across multiple schemas, or

        [`PUT /api/bulk/syncs/{id}/schemas/{schema_id}`](../../../../../../api-reference/bulk-sync/schemas/update)

        to fully replace this schema''s configuration.'
      tags:
      - subpackage_bulkSync.subpackage_bulkSync/schemas
      parameters:
      - name: id
        in: path
        description: Unique identifier of the bulk sync.
        required: true
        schema:
          type: string
          format: uuid
      - name: schema_id
        in: path
        description: Source-side schema identifier.
        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/BulkSchemaEnvelope'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    put:
      operationId: update
      summary: Update Bulk Sync Schema
      description: 'Replaces the configuration of a single schema on a bulk sync.


        This is a full replacement: every field in the request body is written to the

        schema, and any field you omit is cleared or reset to its default. Fetch the

        current configuration with

        [`GET /api/bulk/syncs/{id}/schemas/{schema_id}`](../../../../../../api-reference/bulk-sync/schemas/get)

        first if you want to preserve existing settings while changing only a subset.


        Omitting `fields` enables all available fields on the schema. To control which

        fields are enabled, include the `fields` array with explicit `enabled` values.


        > 📘 To update multiple schemas in a single request without affecting others,

        > use the partial-update endpoint

        > [`PATCH /api/bulk/syncs/{id}/schemas`](../../../../../../api-reference/bulk-sync/schemas/patch)

        > instead.'
      tags:
      - subpackage_bulkSync.subpackage_bulkSync/schemas
      parameters:
      - name: id
        in: path
        description: Unique identifier of the bulk sync.
        required: true
        schema:
          type: string
          format: uuid
      - name: schema_id
        in: path
        description: Source-side schema identifier.
        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/BulkSchemaEnvelope'
        '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/UpdateBulkSchema'
  /api/bulk/syncs/{id}/schemas/{schema_id}/cancel:
    post:
      operationId: cancel
      summary: Cancel Bulk Sync Schema
      description: 'Requests cancellation of any running executions for a specific schema on a bulk sync.


        Cancellation is asynchronous. A successful response means the cancellation

        signal for this schema has been queued; the schema''s in-flight work continues

        until the signal is processed. Poll

        `GET /api/bulk/syncs/{id}/schemas/{schema_id}` and the parent execution via

        `GET /api/bulk/syncs/{id}/status` to confirm the schema has reached a terminal

        state.'
      tags:
      - subpackage_bulkSync.subpackage_bulkSync/schemas
      parameters:
      - name: id
        in: path
        description: The bulk sync ID.
        required: true
        schema:
          type: string
          format: uuid
      - name: schema_id
        in: path
        description: The schema ID to cancel for the bulk sync.
        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/CancelBulkSyncResponseEnvelope'
        '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'
components:
  schemas:
    UpdateBulkSyncSchemasRequest:
      type: object
      properties:
        schemas:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/BulkSchema'
          description: Schemas to patch. Schemas are matched by id; only schemas present in this list are updated.
      title: UpdateBulkSyncSchemasRequest
    UpdateBulkSchema:
      type: object
      properties:
        data_cutoff_timestamp:
          type:
          - string
          - 'null'
          format: date-time
          description: Per-schema cutoff. Records older than this timestamp are excluded from sync runs.
        disable_data_cutoff:
          type: boolean
          description: When true, the sync ignores any configured data_cutoff_timestamp for this schema.
        enabled:
          type: boolean
          description: Whether this schema is included in sync runs.
        fields:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/UpdateBulkField'
          description: Field-level configuration. Supplying an empty list enables every field discovered on the source.
        filters:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/BulkFilter'
          description: Row-level filters applied when reading from the source.
        partition_key:
          type: string
          description: Source field used to partition rows when writing to the destination.
        tracking_field:
          type: string
          description: Source field used to detect changes between incremental sync runs.
        user_output_name:
          type: string
      title: UpdateBulkSchema
    ListBulkSchemaEnvelope:
      type: object
      properties:
        data:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/BulkSchemaListItem'
      title: ListBulkSchemaEnvelope
    FilterFunction:
      type: string
      enum:
      - Equality
      - Inequality
      - IsNull
      - IsNotNull
      - 'True'
      - 'False'
      - OnOrAfter
      - OnOrBefore
      - GreaterThan
      - GreaterThanEqual
      - LessThan
      - LessThanEqual
      - StringContains
      - StringStartsWith
      - StringEndsWith
      - StringDoesNotContain
      - StringDoesNotStartWith
      - StringDoesNotEndWith
      - StringOneOf
      - StringNotOneOf
      - Between
      - ArrayContains
      - ArrayDoesNotContain
      - InTheLast
      - RelativeOnOrBefore
      - RelativeOnOrAfter
      - StringLike
      - StringNotLike
      - StringMatchesTrimmed
      title: FilterFunction
    BulkField:
      type: object
      properties:
        enabled:
          type: boolean
        id:
          type: string
        obfuscated:
          type: boolean
        output_name:
          type: string
        user_output_name:
          type: string
      title: BulkField
    CancelBulkSyncResponseEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/CancelBulkSyncResponse'
      title: CancelBulkSyncResponseEnvelope
    UpdateBulkField:
      type: object
      properties:
        enabled:
          type: boolean
        id:
          type: string
        obfuscated:
          type: boolean
        user_output_name:
          type: string
      title: UpdateBulkField
    BulkSchemaListItem:
      type: object
      properties:
        data_cutoff_timestamp:
          type:
          - string
          - 'null'
          format: date-time
          description: Per-schema cutoff. Records older than this timestamp are excluded from sync runs.
        disable_data_cutoff:
          type: boolean
          description: When true, the sync ignores any configured data_cutoff_timestamp and syncs the full history of this schema.
        enabled:
          type: boolean
          description: Whether this schema is included in sync runs.
        id:
          type: string
          description: Source-side schema identifier (e.g. object name for SaaS sources, schema.table for databases).
        output_name:
          type: string
          description: Effective name of the object written to the destination after any configured naming rules are applied.
        partition_key:
          type: string
          description: Source field used to partition rows when writing to the destination. Empty if the destination does not require one.
        tracking_field:
          type: string
          description: Source field used to detect changes between incremental sync runs. Empty if the schema performs full resyncs.
        user_output_name:
          type: string
          description: User-specified override for the destination object name. When empty, output_name is used.
      title: BulkSchemaListItem
    BulkFilter:
      type: object
      properties:
        field_id:
          type: string
          description: Schema field ID to filter on.
        function:
          $ref: '#/components/schemas/FilterFunction'
        value:
          description: Any type
      required:
      - function
      title: BulkFilter
    BulkSchema:
      type: object
      properties:
        data_cutoff_timestamp:
          type:
          - string
          - 'null'
          format: date-time
        disable_data_cutoff:
          type: boolean
        enabled:
          type: boolean
        fields:
          type: array
          items:
            $ref: '#/components/schemas/BulkField'
          description: fields is not populated on the list endpoint and will be removed in a future version; retrieve individual schemas for fields.
        filters:
          type: array
          items:
            $ref: '#/components/schemas/BulkFilter'
          description: filters is not populated on the list endpoint and will be removed in a future version; retrieve individual schemas for filters.
        id:
          type: string
        output_name:
          type: string
        partition_key:
          type: string
        tracking_field:
          type: string
        user_output_name:
          type: string
      title: BulkSchema
    UpdateBulkSyncSchemasEnvelope:
      type: object
      properties:
        data:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/BulkSchema'
      title: UpdateBulkSyncSchemasEnvelope
    ApiError:
      type: object
      properties:
        key:
          type: string
        message:
          type: string
        metadata:
          type: object
          additionalProperties:
            description: Any type
        status:
          type: integer
      title: ApiError
    BulkSchemaEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/BulkSchema'
      title: BulkSchemaEnvelope
    CancelBulkSyncResponse:
      type: object
      properties:
        message:
          type: string
      title: CancelBulkSyncResponse
  securitySchemes:
    bearerUserAPIKey:
      type: http
      scheme: bearer
      description: Bearer user API key
    orgScopedAPIKey:
      type: http
      scheme: basic
      description: Basic organization-scoped API key
    bearerPartnerKey:
      type: http
      scheme: bearer
      description: Bearer partner API key