@celigo/api-specs 0.2.1

package/dist/sync.yml

@@ -0,0 +1,4857 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: Syncs
+  description: API for building and running Celigo syncs and monitoring their jobs, datasets, events, and errors.
+servers:
+  - url: https://api.integrator.io
+    description: Production (US / default region)
+  - url: https://api.eu.integrator.io
+    description: Production (EU region)
+  - url: https://api.au.integrator.io
+    description: Production (AU region)
+  - url: https://api.ca.integrator.io
+    description: Production (CA region)
+security:
+  - bearerAuth: []
+tags:
+  - name: Syncs
+    description: |-
+      Syncs continuously replicate data from source applications into a data warehouse.
+      A sync belongs to an integration and pairs a source connection with a destination
+      database/schema; its **datasets** choose which tables and columns to replicate and
+      how records are loaded. Use these endpoints to create and configure syncs and
+      their datasets, discover the supported source and destination applications and
+      their tables, review change history and schema-drift events, and track usage.
+
+      ## Sync and dataset schemas
+
+      {% openapi-schemas spec="sync" schemas="Sync,Dataset" grouped="true" %}
+  - name: Sync Jobs
+    description: |-
+      Every sync run produces a read-only sync job that tracks extraction, loading, and
+      error counts across the sync's tables. Use these endpoints to trigger runs,
+      monitor job progress and per-table families, retrieve run errors, and cancel
+      in-flight jobs.
+
+      ## Sync job schema
+
+      {% openapi-schemas spec="sync" schemas="SyncJob" grouped="true" %}
+paths:
+  /v1/syncs:
+    get:
+      x-internal: false
+      summary: List syncs
+      description: |-
+        Returns all syncs in the account, sorted by name. Filter to one integration with
+        the `_integrationId` query parameter (equivalent to
+        `GET /v1/integrations/{_integrationId}/syncs`).
+      operationId: listSyncs
+      tags:
+        - Syncs
+      parameters:
+        - name: _integrationId
+          in: query
+          required: false
+          description: Only return syncs that belong to this integration.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 69f4ffd395ec28be9cb8c12e
+        - name: limit
+          in: query
+          required: false
+          description: Maximum number of syncs to return per page.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            default: 1000
+            examples:
+              - 100
+        - name: after
+          in: query
+          required: false
+          description: |-
+            Opaque pagination cursor for the next page. Take it from the `after` value in
+            the `Link` response header's `rel="next"` URL rather than constructing it.
+          schema:
+            type: string
+            examples:
+              - WyIiLCI2OTdiZDAwNDFhMWJiMDdhZWY4NmRmNDciXQ
+        - $ref: '#/components/parameters/Include'
+        - $ref: '#/components/parameters/Exclude'
+      responses:
+        '200':
+          description: Array of sync objects.
+          headers:
+            Link:
+              description: |-
+                RFC 5988 pagination links. When more pages remain, includes a
+                `<...>; rel="next"` entry with an `after` cursor; absent on the
+                final page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Sync'
+              examples:
+                default:
+                  value:
+                    - _id: 6a4b8bfb731a7a5cae9bd364
+                      _userId: 68c821306f5d848c881da205
+                      _integrationId: 69f4ffd395ec28be9cb8c12e
+                      name: Salesforce Demo Sync
+                      disabled: false
+                      schedule: '? 0 */8 * * *'
+                      timezone: Asia/Calcutta
+                      historicDateTime: '2022-07-04T18:30:00.000Z'
+                      source:
+                        _connectionId: 6a2a95909e994395f3c2a4e6
+                      destination:
+                        _connectionId: 68d02dbe0839a514623c1d6d
+                        database: ANALYTICS_DB
+                        schema: salesforce_raw
+                      driftPolicy:
+                        dataset:
+                          added: automate
+                          removed: automate
+                        element:
+                          added: automate
+                          objectAdded: preserve
+                          arrayAdded: preserve
+                          removed: automate
+                          reduced: automate
+                          expanded: automate
+                    - _id: 6966b5bd344490b470099978
+                      _userId: 68c821306f5d848c881da205
+                      _integrationId: 6966b587dfb77eaae13110c7
+                      name: Order Analytics
+                      disabled: true
+                      historicDateTime: '1970-01-01T00:00:00.000Z'
+                      source:
+                        _connectionId: 68db4afe97bf4f4942a3b92c
+                      destination: {}
+                      driftPolicy:
+                        dataset: {}
+                        element: {}
+        '204':
+          description: No syncs exist in the account.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    post:
+      x-internal: false
+      summary: Create a sync
+      description: |-
+        Creates a sync inside an integration. Only `_integrationId` and
+        `source._connectionId` are required — new syncs start as disabled drafts, so the
+        destination, datasets, and schedule can be configured with later requests. Creating
+        a sync also registers its connections for the platform's replication runtime.
+      operationId: createSync
+      tags:
+        - Syncs
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              draft:
+                summary: Minimal draft sync
+                value:
+                  _integrationId: 6966b587dfb77eaae13110c7
+                  source:
+                    _connectionId: 6a2a95909e994395f3c2a4e6
+              configured:
+                summary: Fully configured sync
+                value:
+                  _integrationId: 6966b587dfb77eaae13110c7
+                  name: Salesforce Demo Sync
+                  schedule: '? 0 */6 * * *'
+                  timezone: America/New_York
+                  historicDateTime: '2022-07-04T18:30:00.000Z'
+                  source:
+                    _connectionId: 6a2a95909e994395f3c2a4e6
+                  destination:
+                    _connectionId: 68d02dbe0839a514623c1d6d
+                    database: ANALYTICS_DB
+                    schema: salesforce_raw
+                  driftPolicy:
+                    dataset:
+                      added: automate
+                      removed: automate
+                    element:
+                      added: automate
+                      objectAdded: preserve
+                      arrayAdded: preserve
+                      removed: automate
+                      reduced: automate
+                      expanded: automate
+      responses:
+        '201':
+          description: Created sync.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Sync'
+              examples:
+                draft:
+                  summary: Created draft sync
+                  value:
+                    _id: 6a559b5185efa7502eefd439
+                    _userId: 68c821306f5d848c881da205
+                    _integrationId: 6966b587dfb77eaae13110c7
+                    name: ''
+                    disabled: true
+                    source:
+                      _connectionId: 6a2a95909e994395f3c2a4e6
+                    destination: {}
+                    driftPolicy:
+                      dataset: {}
+                      element: {}
+        '400':
+          description: |-
+            Bad request. `_integrationId` is missing (`missing_integration_id`), the body
+            contains `_id` or `_userId` (`id_and_userId_in_request`), or a connection
+            reference is not a valid id.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                missing_integration_id:
+                  summary: Missing _integrationId
+                  value:
+                    errors:
+                      - code: missing_integration_id
+                        message: To create sync integration id is required. Not provided in request body.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          description: |-
+            Validation failed. `source._connectionId` is missing
+            (`missing_source_connection`), the destination duplicates another sync
+            (`duplicate_destination_host`), the destination connector rejected the
+            sync configuration (`invalid_destination_sync_config`), two enabled
+            datasets resolve to the same destination table
+            (`conflicting_table_name`), a field exceeds its size limit
+            (`size_limit_exceeded`), or the drift policy is inconsistent
+            (`drift_policy_invalid_setup`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                missing_source_connection:
+                  summary: Missing source connection
+                  value:
+                    errors:
+                      - code: missing_source_connection
+                        message: Source connection is missing in the request
+  /v1/syncs/{_id}:
+    get:
+      x-internal: false
+      summary: Get a sync
+      description: Returns a single sync by ID.
+      operationId: getSync
+      tags:
+        - Syncs
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Sync id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: syncs
+            examples:
+              - 6a4b8bfb731a7a5cae9bd364
+      responses:
+        '200':
+          description: Sync object.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Sync'
+              examples:
+                configured:
+                  summary: Configured, enabled sync
+                  value:
+                    _id: 6a4b8bfb731a7a5cae9bd364
+                    _userId: 68c821306f5d848c881da205
+                    _integrationId: 69f4ffd395ec28be9cb8c12e
+                    name: Salesforce Demo Sync
+                    disabled: false
+                    schedule: '? 0 */8 * * *'
+                    timezone: Asia/Calcutta
+                    historicDateTime: '2022-07-04T18:30:00.000Z'
+                    source:
+                      _connectionId: 6a2a95909e994395f3c2a4e6
+                    destination:
+                      _connectionId: 68d02dbe0839a514623c1d6d
+                      database: ANALYTICS_DB
+                      schema: salesforce_raw
+                    driftPolicy:
+                      dataset:
+                        added: automate
+                        removed: automate
+                      element:
+                        added: automate
+                        objectAdded: preserve
+                        arrayAdded: preserve
+                        removed: automate
+                        reduced: automate
+                        expanded: automate
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    put:
+      x-internal: false
+      summary: Update a sync
+      description: |-
+        Replaces a sync's configuration. Send the complete desired state: omitted optional
+        fields (`schedule`, `timezone`, destination details, `driftPolicy`) are cleared, not
+        preserved. `_integrationId` cannot be sent — the integration is fixed at creation.
+
+        Set `disabled: false` to enable the sync once its source, destination, datasets, and
+        `historicDateTime` are configured; enabling an incomplete sync fails with
+        `422 sync_not_enabled`.
+      operationId: updateSync
+      tags:
+        - Syncs
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Sync id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: syncs
+            examples:
+              - 6a4b8bfb731a7a5cae9bd364
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              configure:
+                summary: Name the sync and set its destination
+                value:
+                  name: Salesforce Demo Sync
+                  schedule: '? 0 */6 * * *'
+                  timezone: America/New_York
+                  historicDateTime: '2022-07-04T18:30:00.000Z'
+                  source:
+                    _connectionId: 6a2a95909e994395f3c2a4e6
+                  destination:
+                    _connectionId: 68d02dbe0839a514623c1d6d
+                    database: ANALYTICS_DB
+                    schema: salesforce_raw
+                  driftPolicy:
+                    dataset:
+                      added: automate
+                      removed: automate
+                    element:
+                      added: automate
+                      objectAdded: preserve
+                      arrayAdded: preserve
+                      removed: automate
+                      reduced: automate
+                      expanded: automate
+      responses:
+        '200':
+          description: Updated sync.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Sync'
+              examples:
+                configured:
+                  summary: Updated sync
+                  value:
+                    _id: 6a4b8bfb731a7a5cae9bd364
+                    _userId: 68c821306f5d848c881da205
+                    _integrationId: 69f4ffd395ec28be9cb8c12e
+                    name: Salesforce Demo Sync
+                    disabled: true
+                    schedule: '? 0 */6 * * *'
+                    timezone: America/New_York
+                    historicDateTime: '2022-07-04T18:30:00.000Z'
+                    source:
+                      _connectionId: 6a2a95909e994395f3c2a4e6
+                    destination:
+                      _connectionId: 68d02dbe0839a514623c1d6d
+                      database: ANALYTICS_DB
+                      schema: salesforce_raw
+                    driftPolicy:
+                      dataset:
+                        added: automate
+                        removed: automate
+                      element:
+                        added: automate
+                        objectAdded: preserve
+                        arrayAdded: preserve
+                        removed: automate
+                        reduced: automate
+                        expanded: automate
+        '400':
+          description: |-
+            Bad request. The body contains `_integrationId` (`sync_integration_id_update`)
+            or `_id`/`_userId` (`id_and_userId_in_request`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                integration_locked:
+                  summary: Attempt to change the integration
+                  value:
+                    errors:
+                      - code: sync_integration_id_update
+                        message: Integration Id cannot be updated in sync once assigned.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          description: |-
+            Validation failed. `source._connectionId` is missing
+            (`missing_source_connection`), the sync is not ready to enable
+            (`sync_not_enabled`), the destination duplicates another sync
+            (`duplicate_destination_host`), the destination connector rejected the
+            sync configuration (`invalid_destination_sync_config`), two enabled
+            datasets resolve to the same destination table
+            (`conflicting_table_name`), a field exceeds its size limit
+            (`size_limit_exceeded`), or the drift policy is inconsistent
+            (`drift_policy_invalid_setup`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not_ready_to_enable:
+                  summary: Enabling an incomplete sync
+                  value:
+                    errors:
+                      - field: disabled
+                        code: sync_not_enabled
+                        message: Sync can be enabled only when source, destinations are properly defined.
+    delete:
+      x-internal: false
+      summary: Delete a sync
+      description: |-
+        Deletes a sync and tears down its replication resources, including its datasets.
+        The sync must be disabled first — deleting an enabled sync fails with
+        `400 sync_delete_not_allowed`. Syncs are not recoverable through the recycle bin.
+      operationId: deleteSync
+      tags:
+        - Syncs
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Sync id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: syncs
+            examples:
+              - 6a559b5185efa7502eefd439
+      responses:
+        '204':
+          description: Sync deleted.
+        '400':
+          description: |-
+            The sync is still enabled.
+            Error code: `sync_delete_not_allowed`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                enabled:
+                  summary: Sync still enabled
+                  value:
+                    errors:
+                      - code: sync_delete_not_allowed
+                        message: Cannot delete an enabled sync. Please disable the sync before deletion.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_integrationId}/syncs:
+    get:
+      x-internal: false
+      summary: List syncs in an integration
+      description: |-
+        Returns the syncs that belong to one integration, sorted by name. Equivalent to
+        `GET /v1/syncs?_integrationId={_integrationId}`.
+      operationId: listSyncsForIntegration
+      tags:
+        - Syncs
+      parameters:
+        - name: _integrationId
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6966b587dfb77eaae13110c7
+        - name: limit
+          in: query
+          required: false
+          description: Maximum number of syncs to return per page.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            default: 1000
+            examples:
+              - 100
+        - name: after
+          in: query
+          required: false
+          description: |-
+            Opaque pagination cursor for the next page. Take it from the `after` value in
+            the `Link` response header's `rel="next"` URL rather than constructing it.
+          schema:
+            type: string
+            examples:
+              - WyIiLCI2OTdiZDAwNDFhMWJiMDdhZWY4NmRmNDciXQ
+        - $ref: '#/components/parameters/Include'
+        - $ref: '#/components/parameters/Exclude'
+      responses:
+        '200':
+          description: Array of sync objects.
+          headers:
+            Link:
+              description: |-
+                RFC 5988 pagination links. When more pages remain, includes a
+                `<...>; rel="next"` entry with an `after` cursor; absent on the
+                final page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Sync'
+              examples:
+                default:
+                  value:
+                    - _id: 6966b5bd344490b470099978
+                      _userId: 68c821306f5d848c881da205
+                      _integrationId: 6966b587dfb77eaae13110c7
+                      name: Order Analytics
+                      disabled: true
+                      schedule: '? 0 */1 * * *'
+                      timezone: America/New_York
+                      historicDateTime: '1970-01-01T00:00:00.000Z'
+                      source:
+                        _connectionId: 68db4afe97bf4f4942a3b92c
+                      destination:
+                        _connectionId: 68d02dbe0839a514623c1d6d
+                        database: ANALYTICS_DB
+                        schema: orders_raw
+                      driftPolicy:
+                        dataset: {}
+                        element: {}
+        '204':
+          description: The integration has no syncs, or the integration does not exist.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/syncs/{_syncId}/datasets:
+    get:
+      x-internal: false
+      summary: List datasets for a sync
+      description: |-
+        Returns the datasets configured on a sync — the tables/objects it replicates —
+        sorted by name. Export-backed datasets whose export no longer uses the sync's
+        source connection carry `mismatchSyncConnection: true`.
+      operationId: listDatasetsForSync
+      tags:
+        - Syncs
+      parameters:
+        - name: _syncId
+          in: path
+          required: true
+          description: Sync id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: syncs
+            examples:
+              - 6a55970bdb54be366c858bc9
+        - name: limit
+          in: query
+          required: false
+          description: Maximum number of datasets to return per page.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            default: 1000
+            examples:
+              - 100
+        - name: after
+          in: query
+          required: false
+          description: |-
+            Opaque pagination cursor for the next page. Take it from the `after` value in
+            the `Link` response header's `rel="next"` URL rather than constructing it.
+          schema:
+            type: string
+            examples:
+              - WyJBY2NvdW50IiwiNmE1NTk3MGM1Zjk0OThhMTc1OGEwYWQzIl0
+        - $ref: '#/components/parameters/Include'
+        - $ref: '#/components/parameters/Exclude'
+      responses:
+        '200':
+          description: Array of dataset objects.
+          headers:
+            Link:
+              description: |-
+                RFC 5988 pagination links. When more pages remain, includes a
+                `<...>; rel="next"` entry with an `after` cursor; absent on the
+                final page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Dataset'
+              examples:
+                default:
+                  value:
+                    - _id: 6a559b547885d8f93921c2ba
+                      _userId: 68c821306f5d848c881da205
+                      _syncId: 6a55970bdb54be366c858bc9
+                      name: Account
+                      externalId: Account
+                      enable: true
+                      enableAllDataElements: false
+                      ingestionMode: merge
+                      userActionRequired: false
+                      exportProperties:
+                        type: delta
+                        delta: {}
+                      driftPolicy:
+                        element: {}
+                      dataElements:
+                        - name: Id
+                          enable: true
+                          mask: false
+                          isPrimaryKey: true
+                          children: []
+                        - name: Name
+                          enable: true
+                          mask: false
+                          children: []
+                    - _id: 6a55974edb54be366c858d26
+                      _userId: 68c821306f5d848c881da205
+                      _syncId: 6a55970bdb54be366c858bc9
+                      name: Pull Salesforce Records
+                      externalId: 6a3e7c54c2387aaa87881b80
+                      enable: true
+                      enableAllDataElements: false
+                      ingestionMode: merge
+                      tableName: pull_salesforce_records
+                      isExport: true
+                      userActionRequired: false
+                      exportProperties:
+                        delta: {}
+                      driftPolicy:
+                        element: {}
+                      dataElements:
+                        - name: Id
+                          enable: true
+                          mask: false
+                          isPrimaryKey: true
+                          children: []
+                      mismatchSyncConnection: true
+        '204':
+          description: The sync has no datasets, or the sync does not exist.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    put:
+      x-internal: false
+      summary: Create or update datasets for a sync
+      description: |-
+        Creates and updates a sync's datasets in one batch. Each array item either creates
+        a dataset (identified by `externalId`) or updates one (identified by `_id`); a
+        single request can mix both. Updates fully replace each dataset's writable fields.
+        The response body is empty — read back the saved datasets with
+        `GET /v1/syncs/{_syncId}/datasets`.
+      operationId: upsertDatasetsForSync
+      tags:
+        - Syncs
+      parameters:
+        - name: _syncId
+          in: path
+          required: true
+          description: Sync id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: syncs
+            examples:
+              - 6a55970bdb54be366c858bc9
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: array
+              minItems: 1
+              items:
+                $ref: '#/components/schemas/DatasetUpsertItem'
+            examples:
+              create:
+                summary: Create two datasets
+                value:
+                  - name: Account
+                    externalId: Account
+                    enable: true
+                    ingestionMode: merge
+                    exportProperties:
+                      type: all
+                    dataElements:
+                      - name: Id
+                        enable: true
+                        mask: false
+                        isPrimaryKey: true
+                      - name: Name
+                        enable: true
+                        mask: false
+                  - name: Contact
+                    externalId: Contact
+                    enable: false
+                    ingestionMode: merge
+                    exportProperties:
+                      type: delta
+              update:
+                summary: Switch an existing dataset to append mode
+                value:
+                  - _id: 6a559b547885d8f93921c2ba
+                    name: Account
+                    enable: true
+                    ingestionMode: append
+                    dataElements:
+                      - name: Id
+                        enable: true
+                        isPrimaryKey: true
+                      - name: Name
+                        enable: true
+      responses:
+        '201':
+          description: Datasets created/updated. The response has no body.
+        '400':
+          description: |-
+            Bad request. The body is not a non-empty array (`INVALID_REQUEST_BODY` /
+            `EMPTY_REQUEST_BODY`), an item has both or neither of `_id`/`externalId`
+            (`dataset_externalId_id_required`), an `externalId` already exists or an `_id`
+            does not belong to the sync, `tableName` values collide
+            (`duplicate_dataset_table_names`), or an export dataset's export uses a
+            different connection than the sync (`connection_mismatch`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                both_ids:
+                  summary: Item with both _id and externalId
+                  value:
+                    errors:
+                      - code: dataset_externalId_id_required
+                        message: For creation externalId should be provide and for update dataset id should be provided but not both.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          description: |-
+            Validation failed. An enabled dataset is missing `ingestionMode`
+            (`ingestion_mode_required_for_enabled_datasets`), a `merge` dataset has no
+            primary key, a `tableName` is already taken, two source columns sanitize to
+            the same destination column name (`duplicate_sanitized_column_names` — rename
+            or disable the conflicting source columns), or a data-element combination is
+            invalid (e.g. `transformMode` without children, or `isPrimaryKey` with `mask`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                missing_ingestion_mode:
+                  summary: Enabled dataset without ingestionMode
+                  value:
+                    errors:
+                      - field: ingestionMode
+                        code: ingestion_mode_required_for_enabled_datasets
+                        message: ingestionMode field is required for enabled datasets.
+  /v1/syncs/{_syncId}/datasets/{_id}:
+    get:
+      x-internal: false
+      summary: Get a dataset
+      description: Returns a single dataset of a sync by ID.
+      operationId: getDataset
+      tags:
+        - Syncs
+      parameters:
+        - name: _syncId
+          in: path
+          required: true
+          description: Sync id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: syncs
+            examples:
+              - 6a55970bdb54be366c858bc9
+        - name: _id
+          in: path
+          required: true
+          description: Dataset id.
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 6a559b547885d8f93921c2ba
+      responses:
+        '200':
+          description: Dataset object.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Dataset'
+              examples:
+                selectedColumns:
+                  summary: Dataset with an explicit column selection
+                  value:
+                    _id: 6a559b547885d8f93921c2ba
+                    _userId: 68c821306f5d848c881da205
+                    _syncId: 6a55970bdb54be366c858bc9
+                    name: Account
+                    externalId: Account
+                    enable: true
+                    enableAllDataElements: false
+                    ingestionMode: merge
+                    userActionRequired: false
+                    exportProperties:
+                      type: delta
+                      delta: {}
+                    driftPolicy:
+                      element: {}
+                    dataElements:
+                      - name: Id
+                        enable: true
+                        mask: false
+                        isPrimaryKey: true
+                        children: []
+                      - name: Name
+                        enable: true
+                        mask: false
+                        children: []
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/syncs/{_syncId}/run:
+    post:
+      x-internal: false
+      operationId: runSync
+      tags:
+        - Sync Jobs
+      summary: Trigger a sync run
+      description: |-
+        Queues an on-demand run of a sync and returns identifiers for the new sync job. The
+        run is **asynchronous**: the response returns as soon as the job is queued. Use
+        `GET /v1/syncJobs/{_syncJobId}` or `GET /v1/syncs/{_syncId}/syncJobs` to poll for terminal status.
+
+        By default the run type is `"normal"` (incremental delta). Pass `runType: "resync"` to force a
+        full re-extraction from the source, which drops the delta checkpoint and reloads all data.
+
+        Preconditions enforced by the platform:
+        - The sync must not be disabled (`422 invalid_sync`).
+        - There must not be a job already queued for this sync (`409 sync_job_already_queued`).
+
+        The returned `flowExecutionGroupId` is a correlation key across jobs and errors. For
+        multi-table syncs, a single run creates one parent job with per-table children visible via
+        `GET /v1/syncJobs/{_syncJobId}/family`.
+      parameters:
+        - name: _syncId
+          in: path
+          required: true
+          description: Sync id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: syncs
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SyncRunRequest'
+            examples:
+              default:
+                summary: Default incremental run
+                value: {}
+              resync:
+                summary: Full resync from source
+                value:
+                  runType: resync
+      responses:
+        '200':
+          description: Sync run accepted and queued.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SyncRunResponse'
+              examples:
+                default:
+                  summary: Successful run trigger
+                  value:
+                    syncId: 682094fa7eb7fc3e7ab7a4a0
+                    flowExecutionGroupId: 6821c01c39db7c2b9cdc0e29
+        '400':
+          description: |-
+            Bad request. Invalid `runType` value.
+            Error code: `invalid_parameter`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_run_type:
+                  summary: Invalid runType parameter
+                  value:
+                    errors:
+                      - code: invalid_parameter
+                        message: Invalid value for runType.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            Sync not found.
+            Error code: `invalid_ref`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                sync_not_found:
+                  summary: Sync does not exist
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Sync not found.
+        '409':
+          description: |-
+            A sync job is already queued or running for this sync.
+            Error code: `sync_job_already_queued`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                already_queued:
+                  summary: Job already in progress
+                  value:
+                    errors:
+                      - code: sync_job_already_queued
+                        message: A sync job is already queued for this sync.
+        '422':
+          description: |-
+            The sync is disabled and cannot be run.
+            Error code: `invalid_sync`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                disabled:
+                  summary: Sync is disabled
+                  value:
+                    errors:
+                      - code: invalid_sync
+                        message: The sync is disabled.
+  /v1/syncs/{_syncId}/syncJobs:
+    get:
+      x-internal: false
+      operationId: listSyncJobs
+      tags:
+        - Sync Jobs
+      summary: List sync jobs for a sync
+      description: |-
+        Returns all sync job records for the given sync, ordered by creation time (most recent first).
+        The response wraps the array in a `data` field alongside a `totalCount`.
+
+        Note: although the response shape suggests pagination (`totalCount`), the `limit`, `offset`,
+        and `status` query parameters are silently ignored by the server as of this writing. The
+        endpoint always returns the complete list of jobs.
+      parameters:
+        - name: _syncId
+          in: path
+          required: true
+          description: Sync id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: syncs
+      responses:
+        '200':
+          description: List of sync jobs.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SyncJobsResponse'
+              examples:
+                with_jobs:
+                  summary: Sync with two completed jobs
+                  value:
+                    data:
+                      - _id: 6821c01c39db7c2b9cdc0e30
+                        flowExecutionGroupId: 6821c01c39db7c2b9cdc0e29
+                        _integrationId: 67d7b6e69e4b1371e5d1e2a1
+                        _syncId: 682094fa7eb7fc3e7ab7a4a0
+                        createdAt: '2026-04-28T14:30:00.000Z'
+                        startedAt: '2026-04-28T14:30:01.123Z'
+                        endedAt: '2026-04-28T14:35:12.456Z'
+                        purgeAt: '2026-07-28T14:35:12.456Z'
+                        status: completed
+                        numErrors: 0
+                        numLoadedRecords: 12450
+                        numExtractedRecords: 12450
+                        numTablesSynced: 3
+                        triggeredBy: user:tyler.lamparter@celigo.com
+                        runType: normal
+                      - _id: 6821b00a39db7c2b9cdc0d10
+                        flowExecutionGroupId: 6821b00a39db7c2b9cdc0d09
+                        _integrationId: 67d7b6e69e4b1371e5d1e2a1
+                        _syncId: 682094fa7eb7fc3e7ab7a4a0
+                        createdAt: '2026-04-27T08:00:00.000Z'
+                        startedAt: '2026-04-27T08:00:02.000Z'
+                        endedAt: '2026-04-27T08:12:45.000Z'
+                        purgeAt: '2026-07-27T08:12:45.000Z'
+                        status: completed
+                        numErrors: 2
+                        numLoadedRecords: 11980
+                        numExtractedRecords: 11982
+                        numTablesSynced: 3
+                        triggeredBy: schedule
+                        runType: normal
+                    totalCount: 2
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            Sync not found.
+            Error code: `invalid_ref`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not_found:
+                  summary: Invalid sync id
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Sync not found.
+  /v1/syncs/{_syncId}/syncJobs/cancel:
+    put:
+      x-internal: false
+      operationId: cancelSyncJobs
+      tags:
+        - Sync Jobs
+      summary: Cancel all running sync jobs for a sync
+      description: |-
+        Cancels all currently running or queued sync jobs for the given sync. This is a bulk cancel
+        that affects every in-progress job associated with the sync.
+
+        If there are no cancellable jobs (all jobs are already in a terminal state), the request
+        is rejected. To cancel a single specific job instead, use
+        `PUT /v1/syncJobs/{_syncJobId}/cancel`.
+      parameters:
+        - name: _syncId
+          in: path
+          required: true
+          description: Sync id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: syncs
+      responses:
+        '204':
+          description: All running sync jobs have been canceled. No response body.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            No cancellable jobs found for this sync.
+            Error code: `sync_jobs_not_found`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                no_jobs:
+                  summary: No running jobs to cancel
+                  value:
+                    errors:
+                      - code: sync_jobs_not_found
+                        message: No cancellable sync jobs found.
+  /v1/syncJobs/{_syncJobId}:
+    get:
+      x-internal: false
+      operationId: getSyncJobById
+      tags:
+        - Sync Jobs
+      summary: Get a sync job
+      description: |-
+        Returns a single sync job record. Sync jobs are read-only records created by the platform when
+        a sync run is triggered. The record includes status, timing, record counts, and error counts.
+        A gap between `numExtractedRecords` and `numLoadedRecords` indicates records that failed
+        during loading -- see `numErrors`.
+      parameters:
+        - name: _syncJobId
+          in: path
+          required: true
+          description: Sync job id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: syncJobs
+      responses:
+        '200':
+          description: The sync job record.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SyncJob'
+              examples:
+                completed:
+                  summary: A completed sync job
+                  value:
+                    _id: 6821c01c39db7c2b9cdc0e30
+                    flowExecutionGroupId: 6821c01c39db7c2b9cdc0e29
+                    _integrationId: 67d7b6e69e4b1371e5d1e2a1
+                    _syncId: 682094fa7eb7fc3e7ab7a4a0
+                    createdAt: '2026-04-28T14:30:00.000Z'
+                    startedAt: '2026-04-28T14:30:01.123Z'
+                    endedAt: '2026-04-28T14:35:12.456Z'
+                    purgeAt: '2026-07-28T14:35:12.456Z'
+                    status: completed
+                    numErrors: 0
+                    numLoadedRecords: 12450
+                    numExtractedRecords: 12450
+                    numTablesSynced: 3
+                    triggeredBy: user:tyler.lamparter@celigo.com
+                    runType: normal
+                running:
+                  summary: A currently running sync job
+                  value:
+                    _id: 6821d11d39db7c2b9cdc0f40
+                    flowExecutionGroupId: 6821d11d39db7c2b9cdc0f39
+                    _integrationId: 67d7b6e69e4b1371e5d1e2a1
+                    _syncId: 682094fa7eb7fc3e7ab7a4a0
+                    createdAt: '2026-04-30T09:00:00.000Z'
+                    startedAt: '2026-04-30T09:00:01.500Z'
+                    purgeAt: '2026-07-30T09:00:00.000Z'
+                    status: running
+                    numErrors: 0
+                    numLoadedRecords: 3200
+                    numExtractedRecords: 5100
+                    numTablesSynced: 2
+                    triggeredBy: schedule
+                    runType: normal
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/syncJobs/{_syncJobId}/family:
+    get:
+      x-internal: false
+      operationId: getSyncJobFamily
+      tags:
+        - Sync Jobs
+      summary: Get a sync job and its table-level children
+      description: |-
+        Returns the parent sync job with all of its per-table child jobs inlined under a `tables` array.
+        Each table entry contains its own status, record counts, error counts, and timing.
+
+        A sync job family maps to one sync execution: the parent is the overall sync job and the children
+        represent each table that was synced as part of that run. Parent-level counters are the
+        authoritative totals; `tables[]` provides the per-table breakdown. `tables` may be empty if
+        the job was canceled before any table work started.
+      parameters:
+        - name: _syncJobId
+          in: path
+          required: true
+          description: Sync job id (parent job).
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: syncJobs
+      responses:
+        '200':
+          description: Sync job family (parent with per-table children).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SyncJobFamily'
+              examples:
+                completed_family:
+                  summary: Completed sync with two tables
+                  value:
+                    _id: 6821c01c39db7c2b9cdc0e30
+                    flowExecutionGroupId: 6821c01c39db7c2b9cdc0e29
+                    _integrationId: 67d7b6e69e4b1371e5d1e2a1
+                    _syncId: 682094fa7eb7fc3e7ab7a4a0
+                    createdAt: '2026-04-28T14:30:00.000Z'
+                    startedAt: '2026-04-28T14:30:01.123Z'
+                    endedAt: '2026-04-28T14:35:12.456Z'
+                    purgeAt: '2026-07-28T14:35:12.456Z'
+                    status: completed
+                    numErrors: 0
+                    numLoadedRecords: 12450
+                    numExtractedRecords: 12450
+                    numTablesSynced: 2
+                    triggeredBy: schedule
+                    runType: normal
+                    tables:
+                      - _id: 6821c01c39db7c2b9cdc0e31
+                        tableName: contacts
+                        createdAt: '2026-04-28T14:30:01.200Z'
+                        status: completed
+                        numErrors: 0
+                        numLoadedRecords: 8200
+                        numExtractedRecords: 8200
+                        startedAt: '2026-04-28T14:30:01.300Z'
+                        endedAt: '2026-04-28T14:33:45.100Z'
+                      - _id: 6821c01c39db7c2b9cdc0e32
+                        tableName: accounts
+                        createdAt: '2026-04-28T14:30:01.250Z'
+                        status: completed
+                        numErrors: 0
+                        numLoadedRecords: 4250
+                        numExtractedRecords: 4250
+                        startedAt: '2026-04-28T14:30:01.350Z'
+                        endedAt: '2026-04-28T14:35:12.400Z'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/syncJobs/{_parentJobId}/errors:
+    get:
+      x-internal: false
+      operationId: listSyncJobErrors
+      tags:
+        - Sync Jobs
+      summary: List errors for a sync job
+      description: |-
+        Returns an array of error records for the given parent sync job. Errors are produced during
+        extraction or loading and are scoped to individual tables.
+
+        The response includes an `x-total-count` header with the total number of errors (useful when
+        filtering by child job).
+
+        Use the `_childJobId` query parameter to filter errors to a single table's child job. Without
+        it, errors across all tables in the run are returned. To find a child job id, call
+        `GET /v1/syncJobs/{_syncJobId}/family` and read `tables[]._id`. Each error also carries a
+        `tableName` field for client-side grouping. The response is a bare array, not wrapped in a
+        `data` envelope.
+      parameters:
+        - name: _parentJobId
+          in: path
+          required: true
+          description: Parent sync job id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: syncJobs
+        - name: _childJobId
+          in: query
+          required: false
+          description: |-
+            Optional child (table-level) job id to filter errors to a single table.
+            Obtain this from the `tables[]._id` field in the job family response.
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 6821c01c39db7c2b9cdc0e31
+      responses:
+        '200':
+          description: Array of sync error records.
+          headers:
+            x-total-count:
+              description: Total number of errors matching the query.
+              schema:
+                type: integer
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/SyncError'
+              examples:
+                with_errors:
+                  summary: Two errors from different tables
+                  value:
+                    - scope: extract
+                      source: salesforce
+                      code: INVALID_FIELD
+                      message: No such column 'Custom_Field__c' on entity 'Account'.
+                      _datasetId: 6821c01c39db7c2b9cdc0e35
+                      _syncId: 682094fa7eb7fc3e7ab7a4a0
+                      _parentSyncJobId: 6821c01c39db7c2b9cdc0e30
+                      _childSyncJobId: 6821c01c39db7c2b9cdc0e31
+                      flowExecutionGroupId: 6821c01c39db7c2b9cdc0e29
+                      stage: extraction
+                      datasetName: Salesforce Accounts
+                      tableName: accounts
+                      occurredAt: '2026-04-28T14:31:22.789Z'
+                    - scope: load
+                      source: snowflake
+                      code: DUPLICATE_KEY
+                      message: Duplicate key value violates unique constraint on 'contacts.email'.
+                      _datasetId: 6821c01c39db7c2b9cdc0e36
+                      _syncId: 682094fa7eb7fc3e7ab7a4a0
+                      _parentSyncJobId: 6821c01c39db7c2b9cdc0e30
+                      _childSyncJobId: 6821c01c39db7c2b9cdc0e32
+                      flowExecutionGroupId: 6821c01c39db7c2b9cdc0e29
+                      stage: loading
+                      datasetName: Salesforce Contacts
+                      tableName: contacts
+                      occurredAt: '2026-04-28T14:32:05.123Z'
+                empty:
+                  summary: No errors
+                  value: []
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/syncJobs/{_syncJobId}/cancel:
+    put:
+      x-internal: false
+      operationId: cancelSyncJob
+      tags:
+        - Sync Jobs
+      summary: Cancel a single sync job
+      description: |-
+        Cancels a specific sync job by id.
+
+        Only jobs that are still in progress (`running`) can be canceled. Jobs already in a terminal
+        state (`completed`, `failed`, `canceled`) cannot be canceled. To cancel all running jobs for
+        a sync at once, use `PUT /v1/syncs/{_syncId}/syncJobs/cancel` instead.
+      parameters:
+        - name: _syncJobId
+          in: path
+          required: true
+          description: Sync job id to cancel.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: syncJobs
+      responses:
+        '204':
+          description: Sync job canceled successfully. No response body.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: |-
+            The sync job is already in a terminal state and cannot be canceled.
+            Error code: `sync_job_not_cancellable`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not_cancellable:
+                  summary: Job already completed
+                  value:
+                    errors:
+                      - code: sync_job_not_cancellable
+                        message: The sync job is not in a cancellable state.
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_integrationId}/syncJobs/latest:
+    get:
+      x-internal: false
+      operationId: getLatestSyncJobsForIntegration
+      tags:
+        - Sync Jobs
+      summary: Get the latest sync job for each sync in an integration
+      description: |-
+        Returns the most recent sync job for each sync resource belonging to the given integration.
+        The response is a bare JSON array with one `SyncJob` entry per sync.
+
+        Returns an empty response when no sync jobs exist for any sync in the integration. Each entry
+        in the array represents the latest run of a different sync; use `_syncId` on each returned job
+        to correlate back to the sync resource. The response is a bare array, not wrapped in a `data`
+        envelope.
+      parameters:
+        - name: _integrationId
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+      responses:
+        '200':
+          description: Array of latest sync jobs (one per sync in the integration).
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/SyncJob'
+              examples:
+                two_syncs:
+                  summary: Integration with two syncs
+                  value:
+                    - _id: 6821c01c39db7c2b9cdc0e30
+                      flowExecutionGroupId: 6821c01c39db7c2b9cdc0e29
+                      _integrationId: 67d7b6e69e4b1371e5d1e2a1
+                      _syncId: 682094fa7eb7fc3e7ab7a4a0
+                      createdAt: '2026-04-28T14:30:00.000Z'
+                      startedAt: '2026-04-28T14:30:01.123Z'
+                      endedAt: '2026-04-28T14:35:12.456Z'
+                      purgeAt: '2026-07-28T14:35:12.456Z'
+                      status: completed
+                      numErrors: 0
+                      numLoadedRecords: 12450
+                      numExtractedRecords: 12450
+                      numTablesSynced: 3
+                      triggeredBy: schedule
+                      runType: normal
+                    - _id: 6821d22e39db7c2b9cdc1050
+                      flowExecutionGroupId: 6821d22e39db7c2b9cdc1049
+                      _integrationId: 67d7b6e69e4b1371e5d1e2a1
+                      _syncId: 682094fb7eb7fc3e7ab7a4b1
+                      createdAt: '2026-04-29T02:00:00.000Z'
+                      startedAt: '2026-04-29T02:00:01.000Z'
+                      endedAt: '2026-04-29T02:08:33.000Z'
+                      purgeAt: '2026-07-29T02:08:33.000Z'
+                      status: completed
+                      numErrors: 1
+                      numLoadedRecords: 5600
+                      numExtractedRecords: 5601
+                      numTablesSynced: 2
+                      triggeredBy: schedule
+                      runType: normal
+        '204':
+          description: No sync jobs exist for any sync in this integration.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            Integration not found or not sync-enabled.
+            Error codes: `sync_job_invalid_integration_id` (integration exists but has no syncs),
+            `sync_job_missing_integration` (integration does not exist).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not_sync_enabled:
+                  summary: Integration has no syncs
+                  value:
+                    errors:
+                      - code: sync_job_invalid_integration_id
+                        message: The integration is not sync-enabled.
+                missing:
+                  summary: Integration does not exist
+                  value:
+                    errors:
+                      - code: sync_job_missing_integration
+                        message: Integration not found.
+  /v1/syncs/{_syncId}/audit:
+    get:
+      x-internal: false
+      summary: Get audit log for a sync
+      description: |-
+        Returns the change history for a sync. Entries cover the sync itself **and** the related
+        resources it depends on — its datasets (the tables being replicated) and the source and
+        destination connections it uses — so a single response interleaves `sync`, `dataset`, and
+        `connection` events. Read `resourceType` on each entry to tell them apart.
+      tags:
+        - Syncs
+      operationId: getSyncAudit
+      parameters:
+        - name: _syncId
+          in: path
+          description: Sync id.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: syncs
+            examples:
+              - 6a1889b0c7b977adc441bc0d
+        - name: limit
+          in: query
+          description: Maximum number of audit entries to return per page.
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            default: 1000
+            examples:
+              - 100
+        - name: after
+          in: query
+          required: false
+          description: |-
+            Opaque pagination cursor for the next page. Take it from the `after` value in the `Link`
+            response header's `rel="next"` URL rather than constructing it.
+          schema:
+            type: string
+            examples:
+              - W3siJGRhdGUiOiIyMDI2LTA1LTAxVDAwOjAwOjAwLjAwMFoifSwiNjAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwIl0
+        - name: from
+          in: query
+          required: false
+          description: Only return entries at or after this timestamp.
+          schema:
+            type: string
+            format: date-time
+            examples:
+              - '2026-05-01T00:00:00.000Z'
+        - name: to
+          in: query
+          required: false
+          description: Only return entries at or before this timestamp.
+          schema:
+            type: string
+            format: date-time
+            examples:
+              - '2026-05-31T23:59:59.999Z'
+        - name: action
+          in: query
+          required: false
+          description: Filter by the change type. Maps to the `event` field on each entry.
+          schema:
+            type: string
+            enum:
+              - create
+              - update
+              - delete
+              - view
+              - restore
+              - purge
+              - signin
+              - signout
+              - purgelogs
+            examples:
+              - update
+            x-enumDescriptions:
+              create: A resource was created.
+              update: A resource was modified.
+              delete: A resource was deleted (moved to recycle bin).
+              view: A resource was viewed or accessed.
+              restore: A resource was restored from the recycle bin.
+              purge: A resource was permanently purged from the recycle bin.
+              signin: A user signed in to the account.
+              signout: A user signed out of the account.
+              purgelogs: Execution logs were purged for a resource.
+        - name: source
+          in: query
+          required: false
+          description: Filter by how the change was initiated.
+          schema:
+            type: string
+            enum:
+              - ui
+              - api
+              - system
+              - connector
+              - script
+              - sso
+            examples:
+              - ui
+            x-enumDescriptions:
+              ui: Change made through the Celigo web UI.
+              api: Change made via the REST API.
+              system: Change made automatically by the platform.
+              connector: Change made by an Integration App (connector) process.
+              script: Change made by a custom script execution.
+              sso: Change triggered by an SSO authentication event.
+        - name: _byUserId
+          in: query
+          required: false
+          description: Filter to changes performed by a single user.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: users
+            examples:
+              - 624cb0346309dc3a543733a2
+        - name: resourceType
+          in: query
+          required: false
+          description: |-
+            Narrow the aggregated results to a single resource kind — e.g. `sync` for only the sync's
+            own changes, excluding its datasets and connections.
+          schema:
+            type: string
+            enum:
+              - sync
+              - dataset
+              - connection
+            examples:
+              - sync
+            x-enumDescriptions:
+              sync: Only changes to the sync resource itself.
+              dataset: Only changes to the sync's datasets.
+              connection: Only changes to the sync's source or destination connections.
+        - name: _resourceId
+          in: query
+          required: false
+          description: |-
+            Filter to a single resource's entries. Must be sent together with `resourceType`;
+            sending it alone returns `400 invalid_id`.
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 682094fa7eb7fc3e7ab7a4a0
+      responses:
+        '200':
+          description: Array of audit entries, newest first.
+          headers:
+            Link:
+              description: |-
+                RFC 5988 pagination link. Includes `<...>; rel="next"` with an
+                `after` cursor when more entries exist; absent on the final page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  description: A single change recorded against the sync or one of its related resources.
+                  properties:
+                    _id:
+                      type: string
+                      format: objectId
+                      description: Unique identifier for this audit entry.
+                      examples:
+                        - 6a1889e4c7b977adc441cb3f
+                    resourceType:
+                      type: string
+                      description: |-
+                        Which resource the entry describes. The endpoint aggregates the sync and the
+                        resources it references, so a single response mixes all three values.
+                      enum:
+                        - sync
+                        - dataset
+                        - connection
+                      examples:
+                        - sync
+                      x-enumDescriptions:
+                        sync: A change to the sync resource itself (name, schedule, drift policy, etc.).
+                        dataset: A change to one of the sync's datasets (the tables being replicated).
+                        connection: A change to a source or destination connection the sync uses.
+                    _resourceId:
+                      type: string
+                      format: objectId
+                      description: ID of the resource this entry belongs to. Matches `resourceType`.
+                      examples:
+                        - 682094fa7eb7fc3e7ab7a4a0
+                    event:
+                      type: string
+                      description: Type of change that occurred.
+                      enum:
+                        - create
+                        - update
+                        - delete
+                      examples:
+                        - update
+                      x-enumDescriptions:
+                        create: Resource was created.
+                        update: Resource was modified.
+                        delete: Resource was soft-deleted (moved to recycle bin).
+                    source:
+                      type: string
+                      description: How the change was initiated.
+                      enum:
+                        - ui
+                        - system
+                      examples:
+                        - ui
+                      x-enumDescriptions:
+                        ui: Change made through the Celigo UI.
+                        system: Change made by an automated platform process.
+                    time:
+                      type: string
+                      format: date-time
+                      description: When the change occurred.
+                      examples:
+                        - '2026-05-28T18:31:00.861Z'
+                    byUser:
+                      type: object
+                      description: |-
+                        User the change is attributed to; always present. For `ui` changes this is the
+                        user who made it; for `system` changes it is the account owner the automated
+                        process ran as.
+                      properties:
+                        _id:
+                          type: string
+                          format: objectId
+                          x-celigo-refModel: users
+                          description: User ID.
+                          examples:
+                            - 624cb0346309dc3a543733a2
+                        email:
+                          type: string
+                          format: email
+                          description: User email address.
+                          examples:
+                            - user@example.com
+                        name:
+                          type: string
+                          description: User display name.
+                          examples:
+                            - Tyler Lamparter
+                    fieldChanges:
+                      type: array
+                      description: Fields that were modified. Dot-notation paths reach into nested objects.
+                      items:
+                        type: object
+                        description: One modified field, with its values before and after the change.
+                        properties:
+                          fieldPath:
+                            type: string
+                            description: Dot-notation path of the changed field.
+                            examples:
+                              - schedule
+                          oldValue:
+                            description: The field's value before the change. Absent on `create` events. Type matches the changed field.
+                          newValue:
+                            description: The field's value after the change. Absent on `delete` events. Type matches the changed field.
+                    deletedInfo:
+                      type: object
+                      description: Metadata about the deleted resource. Present on `delete` events.
+                      properties:
+                        name:
+                          type: string
+                          description: Name of the resource at the time of deletion.
+                          examples:
+                            - Order Analytics
+                        _integrationId:
+                          type: string
+                          format: objectId
+                          x-celigo-refModel: integrations
+                          description: Integration the deleted resource belonged to.
+                          examples:
+                            - 6985ccd4dab90f9cbe9080dd
+              examples:
+                default:
+                  summary: A sync update and a connection update
+                  value:
+                    - _id: 6a1889e4c7b977adc441cb3f
+                      resourceType: sync
+                      _resourceId: 682094fa7eb7fc3e7ab7a4a0
+                      source: ui
+                      event: update
+                      time: '2026-05-28T18:31:00.861Z'
+                      byUser:
+                        _id: 624cb0346309dc3a543733a2
+                        email: user@example.com
+                        name: Tyler Lamparter
+                      fieldChanges:
+                        - fieldPath: name
+                          oldValue: ''
+                          newValue: Order Analytics
+                        - fieldPath: schedule
+                          newValue: '? 0 */1 * * *'
+                        - fieldPath: timezone
+                          newValue: Etc/UTC
+                    - _id: 6a1889c9c7b977adc441c27a
+                      resourceType: connection
+                      _resourceId: 68c8213f8ece256d4c9fa351
+                      source: system
+                      event: update
+                      time: '2026-05-28T18:30:32.891Z'
+                      byUser:
+                        _id: 624cb0346309dc3a543733a2
+                        email: user@example.com
+                        name: Tyler Lamparter
+                      fieldChanges:
+                        - fieldPath: salesforce.refreshToken
+                          newValue: '********'
+        '204':
+          description: No audit entries match the query.
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/di/resource/syncs/{_syncId}/events:
+    get:
+      x-internal: false
+      summary: List events for a sync
+      description: |-
+        Returns the events recorded for a sync across all of its runs — schema drift the
+        platform detected or applied, and data-catalog activity — newest first. Events are
+        retained per the account's data retention period; a `time_lte` older than the
+        retention window returns an empty list.
+      operationId: listSyncEvents
+      tags:
+        - Syncs
+      parameters:
+        - name: _syncId
+          in: path
+          required: true
+          description: Sync id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: syncs
+            examples:
+              - 6a4b8bfb731a7a5cae9bd364
+        - name: limit
+          in: query
+          required: false
+          description: Maximum number of events to return per page.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            default: 100
+            examples:
+              - 25
+        - name: page
+          in: query
+          required: false
+          description: 1-based page number. Combine with `limit` to page through results.
+          schema:
+            type: integer
+            minimum: 1
+            default: 1
+            examples:
+              - 2
+        - name: time_lte
+          in: query
+          required: false
+          description: Only return events recorded at or before this timestamp.
+          schema:
+            type: string
+            format: date-time
+            examples:
+              - '2026-07-14T00:00:00.000Z'
+        - name: time_gt
+          in: query
+          required: false
+          description: |-
+            Only return events recorded after this timestamp. Must not be in the future
+            (`422 future_time_gt_not_allowed`).
+          schema:
+            type: string
+            format: date-time
+            examples:
+              - '2026-07-07T00:00:00.000Z'
+        - name: type
+          in: query
+          required: false
+          description: Only return events of one category.
+          schema:
+            type: string
+            enum:
+              - Schema Drift
+              - Data Catalog
+            examples:
+              - Schema Drift
+            x-enumDescriptions:
+              Schema Drift: Changes to the source schema that were detected or applied.
+              Data Catalog: Dataset metadata activity recorded while cataloging the source.
+        - name: resourceName
+          in: query
+          required: false
+          description: Only return events for one source table/object.
+          schema:
+            type: string
+            examples:
+              - Account
+        - name: flowExecutionGroupId
+          in: query
+          required: false
+          description: |-
+            Only return events from one run. Use the `flowExecutionGroupId` returned by
+            `POST /v1/syncs/{_syncId}/run`.
+          schema:
+            type: string
+            examples:
+              - d0f875a575bd4b8c944533da773f350a
+      responses:
+        '200':
+          description: Events matching the filters, newest first.
+          headers:
+            Link:
+              description: |-
+                RFC 5988 pagination links with page-based navigation: `rel="first"`,
+                `rel="last"`, and — where applicable — `rel="prev"` and `rel="next"`.
+              schema:
+                type: string
+            X-Total-Count:
+              description: Total number of events matching the current filters.
+              schema:
+                type: string
+                examples:
+                  - '18'
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - events
+                properties:
+                  events:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/SyncEvent'
+              examples:
+                drift:
+                  summary: Schema drift recorded during extraction
+                  value:
+                    events:
+                      - id: 80ba31fe-b66d-4777-9b12-3177c55aab13
+                        _syncId: 6a4b8bfb731a7a5cae9bd364
+                        _userId: 68c821306f5d848c881da205
+                        flowExecutionGroupId: d0f875a575bd4b8c944533da773f350a
+                        resourceName: RelatedListDefinition
+                        severity: INFO
+                        eventTime: '2026-07-13T12:36:06.225Z'
+                        type: Schema Drift
+                        stage: Extract
+                        metadata:
+                          action: Table removed
+                          resourceType: Table
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: The sync belongs to a different account owner.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: |-
+            Sync not found.
+            Error code: `invalid_ref`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                sync_not_found:
+                  summary: Sync does not exist
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Sync doc not found for the given id '000000000000000000000000'.
+        '422':
+          description: |-
+            Invalid filter. A timestamp value cannot be parsed, or `time_gt` is in the
+            future (`future_time_gt_not_allowed`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                future_time_gt:
+                  summary: time_gt in the future
+                  value:
+                    errors:
+                      - code: future_time_gt_not_allowed
+                        message: time_gt cannot be in the future
+  /v1/syncs/usage:
+    get:
+      x-internal: false
+      summary: Get per-sync usage for the current month
+      description: |-
+        Returns the number of records each sync loaded during the current calendar month
+        (UTC), for the current environment. Only syncs that ran this month appear.
+        Requires account-administration permission (the same level that manages account
+        users); accounts without a Data Ingestion entitlement get an empty `usage` array.
+      operationId: getSyncUsage
+      tags:
+        - Syncs
+      responses:
+        '200':
+          description: Per-sync loaded-record volumes for the current month.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - usage
+                properties:
+                  usage:
+                    type: array
+                    items:
+                      type: object
+                      description: One sync's loaded-record volume this month.
+                      properties:
+                        _id:
+                          type: string
+                          format: objectId
+                          x-celigo-refModel: syncs
+                          description: Sync the volume belongs to.
+                          examples:
+                            - 6a4b8bfb731a7a5cae9bd364
+                        name:
+                          type:
+                            - string
+                            - 'null'
+                          description: Sync display name. Null when the sync has since been deleted.
+                          examples:
+                            - Salesforce Demo Sync
+                        source:
+                          type:
+                            - object
+                            - 'null'
+                          description: |-
+                            The sync's source connection. Null when the sync no longer
+                            resolves to a source.
+                          properties:
+                            _id:
+                              type: string
+                              format: objectId
+                              x-celigo-refModel: connections
+                              description: Source connection id.
+                              examples:
+                                - 6a2a95909e994395f3c2a4e6
+                            name:
+                              type:
+                                - string
+                                - 'null'
+                              description: Source connection display name.
+                              examples:
+                                - Salesforce Production
+                        destination:
+                          type:
+                            - object
+                            - 'null'
+                          description: |-
+                            The sync's destination connection. Null when the sync has no
+                            destination configured.
+                          properties:
+                            _id:
+                              type: string
+                              format: objectId
+                              x-celigo-refModel: connections
+                              description: Destination connection id.
+                              examples:
+                                - 68d02dbe0839a514623c1d6d
+                            name:
+                              type:
+                                - string
+                                - 'null'
+                              description: Destination connection display name.
+                              examples:
+                                - Snowflake
+                        volume:
+                          type: number
+                          description: Records the sync loaded this month.
+                          examples:
+                            - 1458
+              examples:
+                default:
+                  value:
+                    usage:
+                      - _id: 6a4b8bfb731a7a5cae9bd364
+                        name: Salesforce Demo Sync
+                        source:
+                          _id: 6a2a95909e994395f3c2a4e6
+                          name: Salesforce Production
+                        destination:
+                          _id: 68d02dbe0839a514623c1d6d
+                          name: Snowflake
+                        volume: 1458
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/syncs/usage/summary:
+    get:
+      x-internal: false
+      summary: Get monthly sync usage history
+      description: |-
+        Returns account-wide sync usage by calendar month, newest first — the records
+        loaded across all syncs and environments, alongside the account's Data Ingestion
+        entitlement for each month. History reaches back at most 14 months. Requires
+        account-administration permission (the same level that manages account users);
+        accounts without a Data Ingestion entitlement get an empty array.
+      operationId: getSyncUsageSummary
+      tags:
+        - Syncs
+      parameters:
+        - name: from
+          in: query
+          required: false
+          description: |-
+            First month to include, as `YYYY-MM`. Cannot be more than 14 months back
+            (`400 invalid_date_range`). Defaults to 14 months before the current month.
+          schema:
+            type: string
+            pattern: ^\d{4}-(0[1-9]|1[0-2])$
+            examples:
+              - 2026-05
+        - name: to
+          in: query
+          required: false
+          description: |-
+            Last month to include, as `YYYY-MM`. Cannot be in the future. Defaults to the
+            current month.
+          schema:
+            type: string
+            pattern: ^\d{4}-(0[1-9]|1[0-2])$
+            examples:
+              - 2026-07
+      responses:
+        '200':
+          description: Monthly usage totals, newest month first.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  description: One month's account-wide sync usage.
+                  required:
+                    - year
+                    - month
+                    - volume
+                    - entitlement
+                  properties:
+                    year:
+                      type: integer
+                      description: Calendar year of the usage month.
+                      examples:
+                        - 2026
+                    month:
+                      type: integer
+                      minimum: 1
+                      maximum: 12
+                      description: Calendar month (1-12) of the usage.
+                      examples:
+                        - 7
+                    volume:
+                      type: string
+                      description: |-
+                        Records loaded across all syncs that month, serialized as a string
+                        to avoid precision loss at high volumes.
+                      examples:
+                        - '292460'
+                    entitlement:
+                      type: string
+                      description: |-
+                        Records per month the account's Data Ingestion license allows,
+                        serialized as a string.
+                      examples:
+                        - '100000000'
+              examples:
+                default:
+                  value:
+                    - year: 2026
+                      month: 7
+                      volume: '1537'
+                      entitlement: '100000000'
+                    - year: 2026
+                      month: 6
+                      volume: '292460'
+                      entitlement: '100000000'
+                    - year: 2026
+                      month: 5
+                      volume: '127448244'
+                      entitlement: '100000000'
+        '400':
+          description: |-
+            Invalid date range. `from`/`to` is malformed (`invalid_date_format`), or the
+            range is older than 14 months, in the future, or reversed
+            (`invalid_date_range`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                bad_format:
+                  summary: Malformed month value
+                  value:
+                    errors:
+                      - code: invalid_date_format
+                        message: Invalid date format. Expected YYYY-MM.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/syncs/usage/environments:
+    get:
+      x-internal: false
+      summary: Get sync usage by environment
+      description: |-
+        Returns the records loaded by syncs during the current calendar month (UTC), broken
+        down by environment — production plus every additional environment in the account.
+        Environments with no runs this month report a volume of 0. Requires
+        account-administration permission (the same level that manages account users);
+        accounts without a Data Ingestion entitlement get an empty `usage` array.
+      operationId: getSyncUsageByEnvironment
+      tags:
+        - Syncs
+      responses:
+        '200':
+          description: Per-environment loaded-record volumes for the current month.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - usage
+                properties:
+                  usage:
+                    type: array
+                    items:
+                      type: object
+                      description: One environment's loaded-record volume this month.
+                      required:
+                        - environment
+                        - volume
+                      properties:
+                        environment:
+                          type: object
+                          description: Environment the volume belongs to.
+                          properties:
+                            _id:
+                              type: string
+                              format: objectId
+                              description: |-
+                                Environment id. For the production entry this is the
+                                account owner's user id rather than an environment
+                                resource id.
+                              examples:
+                                - 69cc38111c25db1bb3468a62
+                            name:
+                              type: string
+                              description: Environment display name.
+                              examples:
+                                - Sandbox
+                        volume:
+                          type: number
+                          description: Records loaded in this environment this month.
+                          examples:
+                            - 1537
+              examples:
+                default:
+                  value:
+                    usage:
+                      - environment:
+                          _id: 68c821306f5d848c881da205
+                          name: Production
+                        volume: 1537
+                      - environment:
+                          _id: 69cc38111c25db1bb3468a62
+                          name: Sandbox
+                        volume: 0
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/di/metadata/sources:
+    get:
+      x-internal: false
+      summary: List supported sync source applications
+      description: |-
+        Returns the catalog of applications that can be used as the **source** of a sync — the system
+        a sync extracts records from. Use the returned `id` as the source application when building a
+        sync, and `category` to group the options in a picker.
+      tags:
+        - Syncs
+      operationId: listSyncSources
+      responses:
+        '200':
+          description: Array of supported source applications.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  description: A supported source application.
+                  required:
+                    - id
+                  properties:
+                    id:
+                      type: string
+                      description: Application identifier to use as the sync source.
+                      examples:
+                        - salesforce
+                    category:
+                      type: string
+                      description: |-
+                        Display grouping for the application in selection UIs.
+                        HTTP-connector-backed sources use the category
+                        `HTTP Connector`.
+                      examples:
+                        - Sales & Marketing
+                    displayName:
+                      type: string
+                      description: |-
+                        Human-readable application name. Present on
+                        HTTP-connector-backed sources.
+                      examples:
+                        - Stripe
+                    source:
+                      type: string
+                      description: |-
+                        Where the source's metadata comes from. Present on
+                        HTTP-connector-backed sources with the value
+                        `httpConnectorMetadata`.
+                      examples:
+                        - httpConnectorMetadata
+                    httpConnector:
+                      type: object
+                      description: |-
+                        Identifies the HTTP connector serving this source's
+                        metadata. Present only on HTTP-connector-backed sources.
+                      properties:
+                        _id:
+                          type: string
+                          format: objectId
+                          x-celigo-refModel: httpconnectors
+                          description: HTTP connector id.
+                          examples:
+                            - 63987132784a39b73aae63cd
+                        _apiId:
+                          type:
+                            - string
+                            - 'null'
+                          format: objectId
+                          description: API group id within the connector. Null for single-API connectors.
+                        _versionId:
+                          type: string
+                          format: objectId
+                          description: Connector version id used for metadata resolution.
+              examples:
+                default:
+                  value:
+                    - id: salesforce
+                      category: Sales & Marketing
+                    - id: netsuite
+                      category: Sales & Marketing
+                    - id: stripe
+                      category: HTTP Connector
+                      displayName: Stripe
+                      source: httpConnectorMetadata
+                      httpConnector:
+                        _id: 63987132784a39b73aae63cd
+                        _apiId: null
+                        _versionId: 63987132784a39b73aae63ce
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/di/metadata/destinations:
+    get:
+      x-internal: false
+      summary: List supported sync destination applications
+      description: |-
+        Returns the catalog of applications that can be used as the **destination** of a sync — the
+        data warehouse a sync loads records into. Use the returned `id` as the destination application
+        when building a sync. Identifiers include `snowflake` (Snowflake), `nsaw` (NetSuite
+        Analytics Warehouse), and `bigquery` (Google BigQuery).
+      tags:
+        - Syncs
+      operationId: listSyncDestinations
+      responses:
+        '200':
+          description: Array of supported destination applications.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  description: A supported destination application.
+                  required:
+                    - id
+                  properties:
+                    id:
+                      type: string
+                      description: Application identifier to use as the sync destination.
+                      examples:
+                        - snowflake
+              examples:
+                default:
+                  value:
+                    - id: snowflake
+                    - id: nsaw
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/di/metadata/connections/{_connectionId}/datasets:
+    get:
+      x-internal: false
+      summary: List datasets available on a connection
+      description: |-
+        Returns the catalog of tables/objects a connection's application exposes for
+        syncing, plus the connection's existing export resources that can back
+        export-based datasets. Use the returned `name` values as `externalId` when
+        creating datasets via `PUT /v1/syncs/{_syncId}/datasets`.
+      operationId: listConnectionDatasets
+      tags:
+        - Syncs
+      parameters:
+        - name: _connectionId
+          in: path
+          required: true
+          description: Source connection id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: connections
+            examples:
+              - 6a2a95909e994395f3c2a4e6
+        - name: type
+          in: query
+          required: false
+          description: |-
+            Restrict the response to one catalog. With `datasets`, only source
+            tables/objects are returned; with `exports`, only export resources.
+          schema:
+            type: string
+            enum:
+              - datasets
+              - exports
+              - all
+            default: all
+            examples:
+              - datasets
+            x-enumDescriptions:
+              datasets: Only the source application's tables/objects.
+              exports: Only the connection's export resources usable as export-backed datasets.
+              all: Both catalogs.
+        - name: refreshCache
+          in: query
+          required: false
+          description: |-
+            When `true`, re-reads the catalog from the source application instead of
+            serving the platform's cached copy. Slower; use after making schema changes
+            in the source.
+          schema:
+            type: string
+            enum:
+              - 'true'
+              - 'false'
+            x-enumDescriptions:
+              'true': Re-read the catalog from the source application.
+              'false': Serve the platform's cached copy.
+            examples:
+              - 'true'
+      responses:
+        '200':
+          description: Dataset and/or export catalogs, keyed by type.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  datasets:
+                    type: array
+                    description: Tables/objects the source application exposes. Present unless `type` is `exports`.
+                    items:
+                      type: object
+                      description: One syncable table/object in the source application.
+                      required:
+                        - name
+                      properties:
+                        name:
+                          type: string
+                          description: |-
+                            Identifier of the table/object in the source system. Use as the
+                            dataset `externalId`.
+                          examples:
+                            - Account
+                        displayName:
+                          type: string
+                          description: Human-readable label for the table/object.
+                          examples:
+                            - Account
+                  exports:
+                    type: array
+                    description: |-
+                      Export resources on the connection, usable as export-backed datasets
+                      (`isExport: true`). Present unless `type` is `datasets`.
+                    items:
+                      type: object
+                      description: One export resource usable as a sync dataset.
+                      properties:
+                        _id:
+                          type: string
+                          format: objectId
+                          x-celigo-refModel: exports
+                          description: |-
+                            Export id. Use as the dataset `externalId` when creating an
+                            export-backed dataset.
+                          examples:
+                            - 6a3e7c54c2387aaa87881b80
+                        name:
+                          type: string
+                          description: Export display name.
+                          examples:
+                            - Pull Salesforce Records
+                        type:
+                          type: string
+                          description: Export extraction type (e.g. `delta`, `all`, `once`).
+                          examples:
+                            - delta
+                        adaptorType:
+                          type: string
+                          description: Adaptor the export runs on (e.g. `SalesforceExport`).
+                          examples:
+                            - SalesforceExport
+              examples:
+                default:
+                  value:
+                    datasets:
+                      - name: Account
+                        displayName: Account
+                      - name: Contact
+                        displayName: Contact
+                    exports:
+                      - name: Pull Salesforce Records
+                        _id: 6a3e7c54c2387aaa87881b80
+                        type: delta
+                        adaptorType: SalesforceExport
+        '400':
+          description: |-
+            Bad request. The connection id is not a valid id, or `type` is not one of the
+            allowed values.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_type:
+                  summary: Invalid type value
+                  value:
+                    errors:
+                      - source: DI-MANAGEMENT-SERVICE
+                        code: invalid_request
+                        message: '"query.type" must be one of [datasets, exports, all]'
+                        resolved: false
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          description: |-
+            The catalog could not be fetched from the source application — e.g. the
+            connection is offline or rejects the request.
+            Error code: `di_fetch_datasets_failure`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /v1/di/metadata/connections/{_connectionId}/datasets/{datasetName}/details:
+    get:
+      x-internal: false
+      summary: Get column details for a dataset on a connection
+      description: |-
+        Returns the full column/field catalog for one table/object on a connection, as read
+        from the source application. Use it to build the `dataElements` selection before
+        saving a dataset via `PUT /v1/syncs/{_syncId}/datasets` — each element's `name` here
+        is the `name` to reference there.
+      operationId: getConnectionDatasetDetails
+      tags:
+        - Syncs
+      parameters:
+        - name: _connectionId
+          in: path
+          required: true
+          description: Source connection id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: connections
+            examples:
+              - 6a2a95909e994395f3c2a4e6
+        - name: datasetName
+          in: path
+          required: true
+          description: |-
+            Table/object name from `GET /v1/di/metadata/connections/{_connectionId}/datasets`.
+            When `isExport` is `true`, pass the export id instead.
+          schema:
+            type: string
+            examples:
+              - Account
+        - name: isExport
+          in: query
+          required: false
+          description: |-
+            Set to `true` when `datasetName` is an export id, to read the export's record
+            structure instead of a source table.
+          schema:
+            type: string
+            enum:
+              - 'true'
+              - 'false'
+            x-enumDescriptions:
+              'true': Treat `datasetName` as an export id and read the export's record structure.
+              'false': Treat `datasetName` as a source table/object name.
+            examples:
+              - 'false'
+        - name: refreshCache
+          in: query
+          required: false
+          description: |-
+            When `true`, re-reads the columns from the source application instead of the
+            platform's cached copy. Use after making schema changes in the source.
+          schema:
+            type: string
+            enum:
+              - 'true'
+              - 'false'
+            x-enumDescriptions:
+              'true': Re-read the columns from the source application.
+              'false': Serve the platform's cached copy.
+            examples:
+              - 'true'
+        - name: recordType
+          in: query
+          required: false
+          description: |-
+            NetSuite record type backing the dataset, for saved-search datasets. Omit for
+            other sources.
+          schema:
+            type: string
+            examples:
+              - salesorder
+        - name: displayName
+          in: query
+          required: false
+          description: NetSuite saved-search display name, sent together with `recordType`.
+          schema:
+            type: string
+            examples:
+              - Sales Orders
+      responses:
+        '200':
+          description: The dataset's column catalog.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - dataset
+                properties:
+                  dataset:
+                    type: object
+                    description: Source-side description of one table/object and its columns.
+                    properties:
+                      name:
+                        type: string
+                        description: Identifier of the table/object in the source system.
+                        examples:
+                          - Account
+                      displayName:
+                        type: string
+                        description: Human-readable label for the table/object.
+                        examples:
+                          - Account
+                      platform:
+                        type: string
+                        description: Source application the metadata was read from.
+                        examples:
+                          - salesforce
+                      dataSetType:
+                        type: string
+                        description: Source-specific dataset classification (e.g. `Regular`).
+                        examples:
+                          - Regular
+                      href:
+                        type: string
+                        description: Source API path the metadata was read from.
+                        examples:
+                          - /services/data/v61.0/sobjects/Account
+                      nativeTerminology:
+                        type: object
+                        description: |-
+                          What the source application calls datasets and their columns, for
+                          display purposes (e.g. Salesforce "Object" / "Fields").
+                        properties:
+                          dataset:
+                            type: string
+                            description: Source term for a dataset.
+                            examples:
+                              - Object
+                          dataElements:
+                            type: string
+                            description: Source term for a dataset's columns.
+                            examples:
+                              - Fields
+                          description:
+                            type: string
+                            description: Source field that supplies column descriptions.
+                            examples:
+                              - inlineHelpText
+                      deltaFields:
+                        type: array
+                        description: |-
+                          Column names usable as the incremental-extraction cursor
+                          (`exportProperties.delta.dateField`).
+                        items:
+                          type: string
+                        examples:
+                          - - LastModifiedDate
+                            - SystemModstamp
+                      datasetConstraints:
+                        type: array
+                        description: Table-level constraints reported by the source.
+                        items:
+                          type: object
+                          properties:
+                            constraintType:
+                              type: string
+                              description: Constraint kind (e.g. `PRIMARY_KEY`).
+                              examples:
+                                - PRIMARY_KEY
+                            columns:
+                              type: array
+                              description: Columns the constraint spans.
+                              items:
+                                type: string
+                              examples:
+                                - - Id
+                      dataElements:
+                        type: array
+                        description: Every column/field the source exposes on this dataset.
+                        items:
+                          type: object
+                          description: One source column/field.
+                          properties:
+                            name:
+                              type: string
+                              description: Column/field identifier in the source system.
+                              examples:
+                                - Id
+                            displayName:
+                              type: string
+                              description: Human-readable label for the column.
+                              examples:
+                                - Account ID
+                            dataType:
+                              type: string
+                              description: Normalized platform data type.
+                              examples:
+                                - String
+                            nativeDataType:
+                              type: string
+                              description: Data type as reported by the source application.
+                              examples:
+                                - id
+                            dataLength:
+                              type: integer
+                              description: Maximum length for string-like columns; 0 when not applicable.
+                              examples:
+                                - 18
+                            precision:
+                              type: integer
+                              description: Numeric precision; 0 when not applicable.
+                              examples:
+                                - 0
+                            scale:
+                              type: integer
+                              description: Numeric scale; 0 when not applicable.
+                              examples:
+                                - 0
+                            constraint:
+                              type: string
+                              description: |-
+                                Column-level constraint reported by the source (e.g.
+                                `PRIMARY_KEY`, `FOREIGN_KEY`). Absent for unconstrained
+                                columns.
+                              examples:
+                                - PRIMARY_KEY
+                            isPrimaryKey:
+                              type: boolean
+                              description: Only present (as `true`) on the source's key column(s).
+                              examples:
+                                - true
+                            description:
+                              type:
+                                - string
+                                - 'null'
+                              description: Column help text from the source; null when the source has none.
+                            fullyQualifiedName:
+                              type: string
+                              description: Globally unique column identifier in the platform's data catalog.
+                              examples:
+                                - salesforce.00D30000000LHK8EAO.Account.Id
+                            appSpecificProperties:
+                              type: object
+                              description: Source-specific column attributes (e.g. Salesforce `calculated`).
+                              additionalProperties: true
+                            children:
+                              type:
+                                - array
+                                - 'null'
+                              description: Nested fields for object/array columns; null for scalar columns.
+                              items:
+                                type: object
+                                additionalProperties: true
+              examples:
+                account:
+                  summary: Salesforce Account (truncated)
+                  value:
+                    dataset:
+                      name: Account
+                      displayName: Account
+                      platform: salesforce
+                      dataSetType: Regular
+                      href: /services/data/v61.0/sobjects/Account
+                      nativeTerminology:
+                        dataset: Object
+                        dataElements: Fields
+                        description: inlineHelpText
+                      dataElements:
+                        - name: Id
+                          displayName: Account ID
+                          dataType: String
+                          nativeDataType: id
+                          dataLength: 18
+                          precision: 0
+                          scale: 0
+                          constraint: PRIMARY_KEY
+                          isPrimaryKey: true
+                          fullyQualifiedName: salesforce.00D30000000LHK8EAO.Account.Id
+                          appSpecificProperties:
+                            calculated: false
+                          children: null
+                        - name: Name
+                          displayName: Account Name
+                          dataType: String
+                          nativeDataType: string
+                          dataLength: 255
+                          precision: 0
+                          scale: 0
+                          fullyQualifiedName: salesforce.00D30000000LHK8EAO.Account.Name
+                          appSpecificProperties:
+                            calculated: false
+                          children: null
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          description: |-
+            The columns could not be fetched from the source application — e.g. the
+            table/object does not exist or the connection rejects the request.
+            Error code: `di_fetch_data_elements_failure`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                unknown_dataset:
+                  summary: Table does not exist in the source
+                  value:
+                    errors:
+                      - source: application
+                        code: di_fetch_data_elements_failure
+                        message: 'Failed to fetch metadata for ''NoSuchObject123'' because: The requested resource does not exist'
+                        resolved: false
+  /v1/di/metadata/sync/{_syncId}/connections/{_connectionId}/datasets:
+    get:
+      x-internal: false
+      summary: List a connection's datasets merged with a sync's configuration
+      description: |-
+        Returns the connection's full dataset catalog with the sync's saved configuration
+        merged in: catalog entries the sync already replicates carry their stored dataset
+        fields (`_id`, `enable`, `ingestionMode`, …) plus computed `totalFieldCount` and
+        `selectedFieldCount`, while unsaved entries appear with catalog fields only.
+        `dataElements` arrays are stripped from every item to keep the payload small — read
+        one item's columns with the sync-scoped details endpoint.
+
+        Use this to render or reconcile a sync's dataset selection; for just the saved
+        datasets, `GET /v1/syncs/{_syncId}/datasets` is lighter.
+      operationId: listSyncConnectionDatasets
+      tags:
+        - Syncs
+      parameters:
+        - name: _syncId
+          in: path
+          required: true
+          description: Sync id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: syncs
+            examples:
+              - 6a55970bdb54be366c858bc9
+        - name: _connectionId
+          in: path
+          required: true
+          description: The sync's source connection id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: connections
+            examples:
+              - 6a2a95909e994395f3c2a4e6
+        - name: type
+          in: query
+          required: false
+          description: |-
+            Restrict the response to one catalog. With `datasets`, only source
+            tables/objects are returned; with `exports`, only export-backed entries.
+          schema:
+            type: string
+            enum:
+              - datasets
+              - exports
+              - all
+            default: all
+            examples:
+              - datasets
+            x-enumDescriptions:
+              datasets: Only the source application's tables/objects.
+              exports: Only export-backed entries.
+              all: Both catalogs.
+        - name: refreshCache
+          in: query
+          required: false
+          description: |-
+            When `true`, re-reads the catalog from the source application instead of the
+            platform's cached copy.
+          schema:
+            type: string
+            enum:
+              - 'true'
+              - 'false'
+            x-enumDescriptions:
+              'true': Re-read the catalog from the source application.
+              'false': Serve the platform's cached copy.
+            examples:
+              - 'true'
+      responses:
+        '200':
+          description: Merged dataset and/or export lists, keyed by type.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  datasets:
+                    type: array
+                    description: |-
+                      Source tables/objects merged with the sync's saved datasets. Present
+                      unless `type` is `exports`.
+                    items:
+                      type: object
+                      description: |-
+                        One table/object. Catalog-only entries carry `name`/`displayName`
+                        (and default `exportProperties`); entries the sync has saved also
+                        carry the stored dataset fields and field counts.
+                      required:
+                        - name
+                      properties:
+                        name:
+                          type: string
+                          description: Display name of the table/object.
+                          examples:
+                            - Account
+                        displayName:
+                          type: string
+                          description: Human-readable label for the table/object.
+                          examples:
+                            - Account
+                        externalId:
+                          type: string
+                          description: Identifier of the table/object in the source system.
+                          examples:
+                            - Account
+                        _id:
+                          type: string
+                          format: objectId
+                          description: |-
+                            Only present when the sync has saved this dataset. Use with
+                            `GET /v1/syncs/{_syncId}/datasets/{_id}`.
+                          examples:
+                            - 6a55970c5f9498a1758a0ad3
+                        enable:
+                          type: boolean
+                          description: When true, the sync replicates this dataset.
+                          examples:
+                            - true
+                        enableAllDataElements:
+                          type: boolean
+                          description: When true, every column is replicated (no explicit selection saved).
+                          examples:
+                            - false
+                        ingestionMode:
+                          type: string
+                          enum:
+                            - append
+                            - replace
+                            - merge
+                          description: How extracted records are written into the destination table.
+                          x-enumDescriptions:
+                            append: Add extracted records to the destination table, keeping prior rows.
+                            replace: Drop and reload the destination table with each run's records.
+                            merge: Upsert records into the destination table by primary key.
+                          examples:
+                            - merge
+                        exportProperties:
+                          type: object
+                          description: |-
+                            Extraction behavior. Catalog-only entries carry the source's
+                            default (e.g. `{type: delta}`).
+                          properties:
+                            type:
+                              type: string
+                              enum:
+                                - delta
+                                - all
+                              description: Extraction strategy for each run.
+                              x-enumDescriptions:
+                                delta: Extract only records changed since the previous run.
+                                all: Extract every record on every run.
+                              examples:
+                                - delta
+                        userActionRequired:
+                          type: boolean
+                          description: |-
+                            When true, unhandled schema drift needs a user decision before
+                            the dataset can be modified or replicated again.
+                          examples:
+                            - false
+                        totalFieldCount:
+                          type: integer
+                          description: |-
+                            Total number of columns in the dataset, counted recursively
+                            through nested children. 0 for saved datasets that replicate
+                            all columns without an explicit selection.
+                          examples:
+                            - 49
+                        selectedFieldCount:
+                          type: integer
+                          description: |-
+                            Number of enabled columns, counted recursively through nested
+                            children.
+                          examples:
+                            - 35
+                  exports:
+                    type: array
+                    description: |-
+                      Export-backed entries merged with the sync's saved export datasets.
+                      Present unless `type` is `datasets`.
+                    items:
+                      type: object
+                      description: One export usable as (or already saved as) an export-backed dataset.
+                      properties:
+                        name:
+                          type: string
+                          description: Export display name.
+                          examples:
+                            - Pull Salesforce Records
+                        externalId:
+                          type: string
+                          description: Export id backing this entry.
+                          examples:
+                            - 6a3e7c54c2387aaa87881b80
+                        _id:
+                          type: string
+                          format: objectId
+                          description: Only present when the sync has saved this export as a dataset.
+                          examples:
+                            - 6a55974edb54be366c858d26
+                        type:
+                          type: string
+                          description: Export extraction type (e.g. `delta`).
+                          examples:
+                            - delta
+                        adaptorType:
+                          type: string
+                          description: Adaptor the export runs on (e.g. `SalesforceExport`).
+                          examples:
+                            - SalesforceExport
+                        tableName:
+                          type: string
+                          description: Destination table the export dataset loads into.
+                          examples:
+                            - pull_salesforce_records
+                        enable:
+                          type: boolean
+                          description: When true, the sync replicates this export dataset.
+                          examples:
+                            - true
+                        ingestionMode:
+                          type: string
+                          enum:
+                            - append
+                            - replace
+                            - merge
+                          description: How extracted records are written into the destination table.
+                          x-enumDescriptions:
+                            append: Add extracted records to the destination table, keeping prior rows.
+                            replace: Drop and reload the destination table with each run's records.
+                            merge: Upsert records into the destination table by primary key.
+                          examples:
+                            - merge
+                        isExport:
+                          type: boolean
+                          description: Always true for entries in this list.
+                          examples:
+                            - true
+                        userActionRequired:
+                          type: boolean
+                          description: |-
+                            When true, unhandled schema drift needs a user decision before
+                            the dataset can be modified or replicated again.
+                          examples:
+                            - false
+                        mismatchSyncConnection:
+                          type: boolean
+                          description: |-
+                            Only present (as `true`) when the export no longer uses the
+                            sync's source connection.
+                          examples:
+                            - true
+                        totalFieldCount:
+                          type: integer
+                          description: Total number of fields in the export's record structure.
+                          examples:
+                            - 16
+                        selectedFieldCount:
+                          type: integer
+                          description: Number of enabled fields.
+                          examples:
+                            - 16
+              examples:
+                merged:
+                  summary: Saved and unsaved entries side by side
+                  value:
+                    datasets:
+                      - name: Account
+                        displayName: Account
+                        externalId: Account
+                        _id: 6a55970c5f9498a1758a0ad3
+                        enable: true
+                        enableAllDataElements: false
+                        ingestionMode: append
+                        exportProperties:
+                          type: all
+                        userActionRequired: false
+                        totalFieldCount: 49
+                        selectedFieldCount: 35
+                      - name: Contact
+                        displayName: Contact
+                        exportProperties:
+                          type: delta
+                    exports:
+                      - name: Pull Salesforce Records
+                        externalId: 6a3e7c54c2387aaa87881b80
+                        _id: 6a55974edb54be366c858d26
+                        type: delta
+                        adaptorType: SalesforceExport
+                        tableName: pull_salesforce_records
+                        enable: true
+                        ingestionMode: merge
+                        isExport: true
+                        userActionRequired: false
+                        totalFieldCount: 16
+                        selectedFieldCount: 16
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: The sync or connection belongs to a different account owner.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '422':
+          description: |-
+            The catalog could not be fetched or merged — e.g. the connection is offline or
+            the sync/connection pair does not match.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /v1/di/metadata/sync/{_syncId}/connections/{_connectionId}/datasets/{datasetName}/details:
+    get:
+      x-internal: false
+      summary: Get column details for a dataset in a sync's context
+      description: |-
+        Returns one table/object's full column catalog from the source, merged with the
+        sync's saved dataset state — enablement, `ingestionMode`, `exportProperties`, drift
+        policy, and per-column selections. Use it to edit a dataset's `dataElements` with
+        the current source schema and saved selections in one payload.
+      operationId: getSyncConnectionDatasetDetails
+      tags:
+        - Syncs
+      parameters:
+        - name: _syncId
+          in: path
+          required: true
+          description: Sync id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: syncs
+            examples:
+              - 6a55970bdb54be366c858bc9
+        - name: _connectionId
+          in: path
+          required: true
+          description: The sync's source connection id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: connections
+            examples:
+              - 6a2a95909e994395f3c2a4e6
+        - name: datasetName
+          in: path
+          required: true
+          description: |-
+            Table/object name from the merged catalog. When `isExport` is `true`, pass the
+            saved dataset's `_id` instead.
+          schema:
+            type: string
+            examples:
+              - Account
+        - name: isExport
+          in: query
+          required: false
+          description: |-
+            Set to `true` when `datasetName` identifies an export-backed dataset, to read
+            the export's record structure instead of a source table.
+          schema:
+            type: string
+            enum:
+              - 'true'
+              - 'false'
+            x-enumDescriptions:
+              'true': Treat `datasetName` as an export-backed dataset and read the export's record structure.
+              'false': Treat `datasetName` as a source table/object name.
+            examples:
+              - 'false'
+        - name: refreshCache
+          in: query
+          required: false
+          description: |-
+            When `true`, re-reads the columns from the source application instead of the
+            platform's cached copy.
+          schema:
+            type: string
+            enum:
+              - 'true'
+              - 'false'
+            x-enumDescriptions:
+              'true': Re-read the columns from the source application.
+              'false': Serve the platform's cached copy.
+            examples:
+              - 'true'
+        - name: recordType
+          in: query
+          required: false
+          description: |-
+            NetSuite record type backing the dataset, for saved-search datasets. Omit for
+            other sources.
+          schema:
+            type: string
+            examples:
+              - salesorder
+        - name: displayName
+          in: query
+          required: false
+          description: NetSuite saved-search display name, sent together with `recordType`.
+          schema:
+            type: string
+            examples:
+              - Sales Orders
+      responses:
+        '200':
+          description: The dataset's column catalog merged with the sync's saved state.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - dataset
+                properties:
+                  dataset:
+                    type: object
+                    description: |-
+                      The source column catalog (same shape as
+                      `GET /v1/di/metadata/connections/{_connectionId}/datasets/{datasetName}/details`)
+                      extended with the sync's saved dataset state when one exists: `_id`,
+                      `enable`, `isExport`, `ingestionMode`, `exportProperties`,
+                      `driftPolicy`, `tableName`, and per-element `enable`/`mask`/
+                      `isPrimaryKey`/`transformMode` selections merged into `dataElements`.
+                    additionalProperties: true
+              examples:
+                merged:
+                  summary: Account merged with saved selections (truncated)
+                  value:
+                    dataset:
+                      _id: 6a55970c5f9498a1758a0ad3
+                      name: Account
+                      displayName: Account
+                      platform: salesforce
+                      enable: true
+                      isExport: false
+                      ingestionMode: append
+                      exportProperties:
+                        type: all
+                      dataElements:
+                        - name: Id
+                          displayName: Account ID
+                          dataType: String
+                          nativeDataType: id
+                          dataLength: 18
+                          enable: true
+                          isPrimaryKey: true
+                        - name: Name
+                          displayName: Account Name
+                          dataType: String
+                          nativeDataType: string
+                          dataLength: 255
+                          enable: true
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: The sync or connection belongs to a different account owner.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '422':
+          description: |-
+            The columns could not be fetched or merged — e.g. the table/object does not
+            exist in the source or the connection rejects the request.
+            Error code: `di_fetch_data_elements_failure`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  parameters:
+    Include:
+      name: include
+      in: query
+      required: false
+      description: |-
+        Comma-separated list of fields to project into each returned record.
+        Triggers summary projection: the response contains a minimal identity
+        set (`_id`, `name`, plus resource-specific fields) with the requested
+        fields added on top. Supports dot notation for nested fields.
+        Mutually exclusive with `exclude`.
+      schema:
+        type: string
+      example: _integrationId,disabled,lastModified
+    Exclude:
+      name: exclude
+      in: query
+      required: false
+      description: |-
+        Comma-separated list of fields to strip from the default response.
+        Unlike `include`, does not trigger summary projection — returns the
+        full record with the named fields removed. Protected identity fields
+        (e.g. `name`) cannot be stripped. Mutually exclusive with `include`.
+      schema:
+        type: string
+      example: createdAt,lastModified
+  schemas:
+    ElementDriftPolicy:
+      type: object
+      description: |-
+        How the sync reacts when columns/fields change in the source schema between runs.
+        `objectAdded` and `arrayAdded` refine what "automate" means for new nested structures and
+        are only valid when `added` is `automate` — otherwise the save fails with
+        `422 drift_policy_invalid_setup`.
+      properties:
+        added:
+          type: string
+          enum:
+            - automate
+            - ignore
+          description: |-
+            Handling for columns/fields that appear in the source after the sync
+            was configured. Choose `ignore` to keep destination tables stable and
+            opt in to new fields manually.
+          x-enumDescriptions:
+            automate: Automatically add the new column to the destination and start loading it.
+            ignore: Skip new columns until a user enables them explicitly.
+          examples:
+            - automate
+        objectAdded:
+          type: string
+          enum:
+            - preserve
+            - flatten
+          description: Shape given to a newly added **object** field when `added` is `automate`.
+          x-enumDescriptions:
+            preserve: Load the object as a single semi-structured column.
+            flatten: Expand the object's keys into individual columns.
+          examples:
+            - preserve
+        arrayAdded:
+          type: string
+          enum:
+            - preserve
+            - normalize
+          description: Shape given to a newly added **array** field when `added` is `automate`.
+          x-enumDescriptions:
+            preserve: Load the array as a single semi-structured column.
+            normalize: Split the array into a child table keyed back to the parent record.
+          examples:
+            - preserve
+        removed:
+          type: string
+          enum:
+            - automate
+          description: |-
+            Handling for columns/fields deleted from the source. Only automatic
+            propagation is supported.
+          x-enumDescriptions:
+            automate: Stop loading the column and reflect the removal downstream.
+          examples:
+            - automate
+        reduced:
+          type: string
+          enum:
+            - automate
+          description: |-
+            Handling for columns whose source data type shrank (e.g. a shorter
+            string length). Only automatic propagation is supported.
+          x-enumDescriptions:
+            automate: Adjust the destination column to the reduced type automatically.
+          examples:
+            - automate
+        expanded:
+          type: string
+          enum:
+            - automate
+          description: |-
+            Handling for columns whose source data type grew (e.g. a wider numeric
+            precision). Only automatic propagation is supported.
+          x-enumDescriptions:
+            automate: Widen the destination column automatically.
+          examples:
+            - automate
+      if:
+        anyOf:
+          - required:
+              - objectAdded
+          - required:
+              - arrayAdded
+      then:
+        properties:
+          added:
+            const: automate
+        required:
+          - added
+    SyncDriftPolicy:
+      type: object
+      description: |-
+        How the sync reacts when the source schema changes between runs (schema drift).
+        `dataset` covers whole tables/objects appearing or disappearing; `element` covers
+        individual columns/fields. Drift the policy automates is logged as `Schema Drift`
+        events, readable via `GET /v1/di/resource/syncs/{_syncId}/events`.
+      properties:
+        dataset:
+          type: object
+          description: Drift handling for whole tables/objects in the source.
+          properties:
+            added:
+              type: string
+              enum:
+                - automate
+                - ignore
+              description: |-
+                Handling for tables/objects that appear in the source after the sync was
+                configured. Choose `ignore` to keep the replicated set fixed and add new
+                tables manually.
+              x-enumDescriptions:
+                automate: Automatically add newly discovered tables to the sync and start replicating them.
+                ignore: Leave newly discovered tables out of the sync until a user enables them.
+              examples:
+                - automate
+            removed:
+              type: string
+              enum:
+                - automate
+              description: |-
+                Handling for tables/objects deleted from the source. Only automatic
+                propagation is supported.
+              x-enumDescriptions:
+                automate: Stop replicating the removed table automatically.
+              examples:
+                - automate
+        element:
+          $ref: '#/components/schemas/ElementDriftPolicy'
+    Sync:
+      type: object
+      description: |-
+        A sync continuously replicates data from a source application into a data warehouse.
+        New syncs start as disabled drafts; a sync can only be enabled once its source,
+        destination, and datasets are fully configured.
+      required:
+        - _id
+        - _userId
+        - _integrationId
+        - name
+        - disabled
+        - source
+        - destination
+        - driftPolicy
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Unique identifier for the sync.
+          examples:
+            - 6a4b8bfb731a7a5cae9bd364
+        _userId:
+          type: string
+          format: objectId
+          x-celigo-refModel: users
+          readOnly: true
+          description: Account owner the sync belongs to.
+          examples:
+            - 68c821306f5d848c881da205
+        _integrationId:
+          type: string
+          format: objectId
+          x-celigo-refModel: integrations
+          description: |-
+            Integration the sync lives in. Required when creating; cannot be changed
+            afterwards — sending it on an update fails with `400 sync_integration_id_update`.
+          examples:
+            - 69f4ffd395ec28be9cb8c12e
+        name:
+          type: string
+          maxLength: 150
+          description: |-
+            Display name shown in the UI. Defaults to an empty string when not
+            provided at creation.
+          examples:
+            - Salesforce Demo Sync
+        description:
+          type: string
+          maxLength: 5120
+          description: Free-form notes about what the sync replicates and why.
+          examples:
+            - Replicates core CRM objects into the analytics warehouse.
+        disabled:
+          type: boolean
+          default: true
+          description: |-
+            When true, the sync neither runs on schedule nor accepts on-demand runs. New syncs
+            start disabled. Enabling requires a fully configured sync — source and destination
+            connections plus a destination database and schema — and a `historicDateTime`;
+            otherwise the update fails with `422 sync_not_enabled`.
+          examples:
+            - false
+        schedule:
+          type: string
+          description: |-
+            Cron expression that controls automatic runs, e.g. `? 0 */6 * * *` for every
+            six hours. Empty or omitted means the sync only runs on demand via
+            `POST /v1/syncs/{_syncId}/run`. Evaluated in the sync's `timezone`.
+          examples:
+            - '? 0 */6 * * *'
+        timezone:
+          type: string
+          description: IANA time zone name (e.g. `America/New_York`) the `schedule` is evaluated in.
+          examples:
+            - America/New_York
+        historicDateTime:
+          type: string
+          format: date-time
+          description: |-
+            Earliest record timestamp to backfill from the source. The first run extracts
+            history from this point forward; later runs are incremental. Must be set before
+            the sync can be enabled.
+          examples:
+            - '2022-07-04T18:30:00.000Z'
+        source:
+          type: object
+          description: Application the sync extracts records from.
+          required:
+            - _connectionId
+          properties:
+            _connectionId:
+              type: string
+              format: objectId
+              x-celigo-refModel: connections
+              description: |-
+                Connection to the source application. The application must be one of the
+                supported sync sources returned by `GET /v1/di/metadata/sources`.
+              examples:
+                - 6a2a95909e994395f3c2a4e6
+        destination:
+          type: object
+          description: |-
+            Data warehouse the sync loads records into. Empty (`{}`) on a draft that has no
+            destination yet. Each source + destination host/database/schema combination must
+            be unique across syncs — reusing one fails with `422 duplicate_destination_host` —
+            and all syncs in an integration must target the same destination application type.
+          properties:
+            _connectionId:
+              type: string
+              format: objectId
+              x-celigo-refModel: connections
+              description: |-
+                Connection to the destination warehouse. The application must be one of the
+                supported sync destinations returned by `GET /v1/di/metadata/destinations`.
+              examples:
+                - 68d02dbe0839a514623c1d6d
+            database:
+              type: string
+              description: Database in the destination warehouse the sync loads into.
+              examples:
+                - ANALYTICS_DB
+            schema:
+              type: string
+              description: Schema within `database` where the sync creates and loads tables.
+              examples:
+                - salesforce_raw
+            tablePrefix:
+              type: string
+              description: |-
+                Prefix prepended to the name of every table the sync creates in the
+                destination schema. Omit to use unprefixed table names.
+              examples:
+                - sf_
+        driftPolicy:
+          $ref: '#/components/schemas/SyncDriftPolicy'
+    Error:
+      type: object
+      description: Standard error response envelope returned by integrator.io APIs.
+      properties:
+        errors:
+          type: array
+          description: List of errors that occurred while processing the request.
+          items:
+            type: object
+            properties:
+              code:
+                oneOf:
+                  - type: string
+                  - type: integer
+                description: |-
+                  Machine-readable error code. Usually a string like
+                  `invalid_ref`, `missing_required_field`, or `unauthorized`;
+                  may be an **integer** when the error mirrors an upstream HTTP
+                  status (e.g. `500`) — most commonly returned by connection-ping
+                  and adaptor-proxy responses.
+              message:
+                type: string
+                description: Human-readable description of the error.
+              field:
+                type: string
+                description: |-
+                  Optional pointer to the document field that caused the error.
+                  Used by structural validation errors (`missing_required_field`,
+                  `invalid_ref`) to indicate which field is at fault
+                  (e.g. `_id`, `type`, `http.baseURI`).
+              source:
+                type: string
+                description: |-
+                  Optional origin layer for the error — e.g. `application` when
+                  the error came from the remote system the adaptor called,
+                  `connector` when the adaptor itself rejected the request.
+            required:
+              - message
+      required:
+        - errors
+    Request:
+      type: object
+      description: |-
+        Writable sync fields for `POST /v1/syncs` and `PUT /v1/syncs/{_id}`. Updates are full
+        replacements: omitted optional fields (`schedule`, `timezone`, `destination` details,
+        `driftPolicy`) are cleared, not preserved, so send the complete desired configuration
+        on every PUT.
+      required:
+        - source
+      x-celigo-ai-guidance:
+        - |-
+          POST requires _integrationId (omitting it fails with 400 "To create sync integration id
+          is required") and source._connectionId (omitting it fails with 422 "Source connection is
+          missing in the request"). PUT requires source._connectionId too, and rejects
+          _integrationId with 400 sync_integration_id_update.
+        - |-
+          Never send _id or _userId in the body — the API rejects the request with
+          400 id_and_userId_in_request.
+        - |-
+          When scaffolding a draft sync before the destination is known, send only
+          _integrationId and source._connectionId; the sync is created disabled and the
+          destination can be filled in with a later PUT.
+      properties:
+        _integrationId:
+          type: string
+          format: objectId
+          x-celigo-refModel: integrations
+          description: |-
+            Integration to create the sync in. Required on create; forbidden on update —
+            the integration cannot be changed once assigned (`400 sync_integration_id_update`).
+          examples:
+            - 69f4ffd395ec28be9cb8c12e
+        name:
+          type: string
+          maxLength: 150
+          description: |-
+            Display name shown in the UI. Values over 150 characters fail with
+            `422 size_limit_exceeded`.
+          examples:
+            - Salesforce Demo Sync
+        description:
+          type: string
+          maxLength: 5120
+          description: Free-form notes about what the sync replicates and why.
+          examples:
+            - Replicates core CRM objects into the analytics warehouse.
+        disabled:
+          type: boolean
+          default: true
+          description: |-
+            When true, the sync neither runs on schedule nor accepts on-demand runs. Set to
+            false only once source, destination, datasets, and `historicDateTime` are all
+            configured; enabling an incomplete sync fails with `422 sync_not_enabled`.
+          examples:
+            - false
+        schedule:
+          type: string
+          description: |-
+            Cron expression that controls automatic runs, e.g. `? 0 */6 * * *` for every six
+            hours. Send an empty string (or omit) for a sync that only runs on demand.
+            Evaluated in `timezone`.
+          examples:
+            - '? 0 */6 * * *'
+        timezone:
+          type: string
+          description: IANA time zone name (e.g. `America/New_York`) the `schedule` is evaluated in.
+          examples:
+            - America/New_York
+        historicDateTime:
+          type: string
+          format: date-time
+          description: |-
+            Earliest record timestamp to backfill from the source. Must be set before the
+            sync can be enabled.
+          examples:
+            - '2022-07-04T18:30:00.000Z'
+        source:
+          type: object
+          description: Application the sync extracts records from.
+          required:
+            - _connectionId
+          properties:
+            _connectionId:
+              type: string
+              format: objectId
+              x-celigo-refModel: connections
+              description: |-
+                Connection to the source application. The application must be one of the
+                supported sync sources returned by `GET /v1/di/metadata/sources`. Omitting
+                it fails with `422 missing_source_connection`.
+              examples:
+                - 6a2a95909e994395f3c2a4e6
+        destination:
+          type: object
+          description: |-
+            Data warehouse the sync loads records into. Omit while drafting; a complete
+            destination (connection, database, schema) is required before the sync can be
+            enabled. The source + destination host/database/schema combination must be unique
+            across syncs (`422 duplicate_destination_host`), and all syncs in an integration
+            must target the same destination application type.
+          properties:
+            _connectionId:
+              type: string
+              format: objectId
+              x-celigo-refModel: connections
+              description: |-
+                Connection to the destination warehouse. The application must be one of the
+                supported sync destinations returned by `GET /v1/di/metadata/destinations`.
+              examples:
+                - 68d02dbe0839a514623c1d6d
+            database:
+              type: string
+              description: Database in the destination warehouse the sync loads into.
+              examples:
+                - ANALYTICS_DB
+            schema:
+              type: string
+              description: Schema within `database` where the sync creates and loads tables.
+              examples:
+                - salesforce_raw
+            tablePrefix:
+              type: string
+              description: |-
+                Prefix prepended to the name of every table the sync creates in the
+                destination schema. Omit to use unprefixed table names.
+              examples:
+                - sf_
+        driftPolicy:
+          $ref: '#/components/schemas/SyncDriftPolicy'
+    DataElement:
+      type: object
+      description: |-
+        Per-column/field replication settings inside a dataset. Elements with nested
+        structure (objects or arrays) carry a `transformMode` and a `children` array;
+        scalar elements carry neither.
+      properties:
+        name:
+          type: string
+          description: |-
+            Column/field name exactly as it appears in the source dataset. Discover the
+            available names via
+            `GET /v1/di/metadata/connections/{_connectionId}/datasets/{datasetName}/details`.
+          examples:
+            - Id
+        enable:
+          type: boolean
+          description: |-
+            When true, the sync extracts and loads this column. Disabled columns are left
+            out of the destination table.
+          examples:
+            - true
+        mask:
+          type: boolean
+          description: |-
+            When true, the value is masked before loading so the raw source value never
+            lands in the destination. Cannot be combined with `isPrimaryKey`.
+          examples:
+            - false
+        isPrimaryKey:
+          type: boolean
+          description: |-
+            When true, marks the column as (part of) the record key. Required on at least
+            one enabled scalar column when the dataset's `ingestionMode` is `merge`, and
+            used as the parent key for arrays normalized into child tables under `append`
+            and `replace`. The element must also be enabled, and cannot carry `mask` or a
+            `transformMode`.
+          examples:
+            - true
+        transformMode:
+          type: string
+          enum:
+            - preserve
+            - flatten
+            - normalize
+          description: |-
+            Only set on elements with `children` — it controls how the nested structure is
+            loaded. Setting it on a scalar element fails validation, as does omitting it on
+            an element that has children. Children nested under a `preserve` parent cannot
+            override it with another mode.
+          x-enumDescriptions:
+            preserve: Load the nested structure as a single semi-structured column.
+            flatten: Expand object keys into individual columns on the same table.
+            normalize: Split array items into a child table keyed back to the parent record.
+          examples:
+            - flatten
+        children:
+          type: array
+          description: |-
+            Nested elements of an object or array field. Present together with
+            `transformMode`; empty for scalar columns.
+          items:
+            $ref: '#/components/schemas/DataElement'
+    Dataset:
+      type: object
+      description: |-
+        One table/object a sync replicates, with its per-column selections and load behavior.
+        Datasets are scoped to a single sync and are created and updated in bulk via
+        `PUT /v1/syncs/{_syncId}/datasets`.
+      required:
+        - _id
+        - _userId
+        - _syncId
+        - name
+        - externalId
+        - enable
+        - enableAllDataElements
+        - userActionRequired
+        - exportProperties
+        - driftPolicy
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Unique identifier for the dataset.
+          examples:
+            - 6a559b547885d8f93921c2ba
+        _userId:
+          type: string
+          format: objectId
+          x-celigo-refModel: users
+          readOnly: true
+          description: Account owner the dataset belongs to.
+          examples:
+            - 68c821306f5d848c881da205
+        _syncId:
+          type: string
+          format: objectId
+          x-celigo-refModel: syncs
+          readOnly: true
+          description: Sync this dataset belongs to. Assigned from the request path at creation.
+          examples:
+            - 6a559b5185efa7502eefd439
+        name:
+          type: string
+          description: |-
+            Display name of the dataset, typically the source's human-readable label
+            (e.g. a Salesforce object's display name). Empty string when never set.
+          examples:
+            - Account
+        externalId:
+          type: string
+          description: |-
+            Identifier of the dataset in the source system — the table/object name for
+            application sources, or the export ID when `isExport` is true. Immutable after
+            creation.
+          examples:
+            - Account
+        enable:
+          type: boolean
+          description: |-
+            When true, the sync replicates this dataset on each run. Disabled datasets stay
+            configured but are skipped.
+          examples:
+            - true
+        enableAllDataElements:
+          type: boolean
+          readOnly: true
+          description: |-
+            When true, every column in the source dataset is replicated. Computed by the
+            platform: true while the dataset has no explicit `dataElements` selection,
+            false once one is saved.
+          examples:
+            - false
+        ingestionMode:
+          type: string
+          enum:
+            - append
+            - replace
+            - merge
+          description: |-
+            How each run's extracted records are written into the destination table.
+            Required once the dataset is enabled (`422
+            ingestion_mode_required_for_enabled_datasets`). `merge` additionally requires a
+            primary-key column in `dataElements`.
+          x-enumDescriptions:
+            append: Add extracted records to the destination table, keeping prior rows.
+            replace: Drop and reload the destination table with each run's records.
+            merge: Upsert records into the destination table by primary key.
+          examples:
+            - merge
+        tableName:
+          type: string
+          description: |-
+            Destination table name override. Must be unique among the sync's datasets
+            (`422 table_name_already_exists`); required when `isExport` is true. Omit to
+            let the platform derive the table name from the dataset.
+          examples:
+            - account
+        isExport:
+          type: boolean
+          description: |-
+            When true, the dataset's records come from an existing export resource instead
+            of a source table; `externalId` then holds the export ID, and the export must
+            use the sync's source connection. Export datasets require `tableName` and an
+            explicit `dataElements` selection, and do not accept `exportProperties`.
+          examples:
+            - false
+        exportProperties:
+          type: object
+          description: |-
+            Extraction behavior for the dataset. Only configurable on source-table
+            datasets — sending it on an export dataset (`isExport: true`) fails
+            validation; export-backed datasets return a platform-generated stub
+            (`{"delta": {}}`, no `type`) because extraction follows the export's own
+            configuration.
+          properties:
+            type:
+              type: string
+              enum:
+                - delta
+                - all
+              description: |-
+                Extraction strategy for each run. Use `delta` for incremental extraction of
+                changed records and `all` to re-extract every record on every run.
+              x-enumDescriptions:
+                delta: Extract only records changed since the previous run.
+                all: Extract every record on every run.
+              examples:
+                - delta
+            delta:
+              type: object
+              description: Incremental-extraction settings. Only used when `type` is `delta`.
+              properties:
+                dateField:
+                  type: string
+                  description: |-
+                    Source field that carries each record's last-modified timestamp, used as
+                    the delta cursor. Required for NetSuite datasets that extract via a
+                    `netsuite.recordType`; Salesforce datasets derive it automatically.
+                  examples:
+                    - lastmodifieddate
+            netsuite:
+              type: object
+              description: NetSuite-specific extraction settings. Omit for other sources.
+              properties:
+                recordType:
+                  type: string
+                  description: |-
+                    NetSuite record type backing a saved-search dataset. When set with
+                    `exportProperties.type: delta`, a `delta.dateField` is required.
+                  examples:
+                    - salesorder
+        driftPolicy:
+          type: object
+          description: |-
+            Per-dataset override of the sync's `driftPolicy` for column/field drift. Empty
+            (`{element: {}}`) when the dataset follows the sync-level policy.
+          properties:
+            element:
+              $ref: '#/components/schemas/ElementDriftPolicy'
+        dataElements:
+          type: array
+          description: |-
+            Per-column replication selections. Absent while `enableAllDataElements` is true
+            (every column replicated).
+          items:
+            $ref: '#/components/schemas/DataElement'
+        userActionRequired:
+          type: boolean
+          readOnly: true
+          description: |-
+            When true, the platform detected a schema change that needs a user decision
+            before the dataset can be modified or replicated again — typically drift the
+            `driftPolicy` does not automate. Updates to the dataset are rejected until the
+            conflict is resolved (in the UI) in the same save that clears the flag.
+          examples:
+            - false
+        mismatchSyncConnection:
+          type: boolean
+          readOnly: true
+          description: |-
+            Only present (as `true`) in list responses, on export-backed datasets whose
+            export no longer uses the sync's source connection. Repoint the export or
+            recreate the dataset to resume replicating it.
+          examples:
+            - true
+    DatasetUpsertItem:
+      type: object
+      description: |-
+        One dataset to create or update in a `PUT /v1/syncs/{_syncId}/datasets` batch.
+        Send `externalId` (without `_id`) to create, or `_id` (without `externalId`) to
+        update — providing both or neither fails with `400 dataset_externalId_id_required`.
+        Updates are full replacements of the writable fields.
+      x-celigo-ai-guidance:
+        - |-
+          Create items with externalId only; update items with _id only. Sending both on one
+          item fails the whole batch with 400 dataset_externalId_id_required, as does creating
+          a dataset whose externalId already exists on the sync (400) or updating an _id that
+          does not belong to the sync (400).
+        - |-
+          enable: true requires ingestionMode (422 ingestion_mode_required_for_enabled_datasets),
+          and ingestionMode merge requires at least one enabled dataElement with
+          isPrimaryKey: true (422).
+        - |-
+          To scaffold a dataset without replicating it yet, send name, externalId, enable: false
+          and no dataElements — the platform then replicates all columns once enabled.
+      properties:
+        _id:
+          type: string
+          format: objectId
+          description: |-
+            Dataset to update. The dataset must already belong to the sync in the request
+            path. Omit when creating.
+          examples:
+            - 6a559b547885d8f93921c2ba
+        externalId:
+          type: string
+          description: |-
+            Identifier of the dataset in the source system — the table/object name from
+            `GET /v1/di/metadata/connections/{_connectionId}/datasets`, or an export ID when
+            `isExport` is true. Set when creating; immutable afterwards. A dataset with the
+            same `externalId` must not already exist on the sync.
+          examples:
+            - Account
+        name:
+          type: string
+          description: Display name of the dataset, typically the source's human-readable label.
+          examples:
+            - Account
+        enable:
+          type: boolean
+          description: |-
+            When true, the sync replicates this dataset on each run. Required (with an
+            `ingestionMode`) to activate the dataset; datasets created with `enable: false`
+            stay configured but skipped.
+          examples:
+            - true
+        ingestionMode:
+          type: string
+          enum:
+            - append
+            - replace
+            - merge
+          description: |-
+            How extracted records are written into the destination table. Required when
+            `enable` is true. `merge` requires a primary key in `dataElements`.
+          x-enumDescriptions:
+            append: Add extracted records to the destination table, keeping prior rows.
+            replace: Drop and reload the destination table with each run's records.
+            merge: Upsert records into the destination table by primary key.
+          examples:
+            - merge
+        tableName:
+          type: string
+          description: |-
+            Destination table name override. Must be unique among the sync's datasets —
+            duplicates within the batch or with existing datasets fail with `400
+            duplicate_dataset_table_names` / `422 table_name_already_exists`. Required when
+            `isExport` is true.
+          examples:
+            - account
+        isExport:
+          type: boolean
+          description: |-
+            When true, the dataset's records come from an existing export resource:
+            `externalId` must be the export's ID, the export must use the sync's source
+            connection (`400 connection_mismatch`), and the item must include `tableName`
+            and `dataElements` but no `exportProperties`.
+          examples:
+            - false
+        exportProperties:
+          type: object
+          description: |-
+            Extraction behavior for the dataset. Only for source-table datasets — sending it
+            with `isExport: true` fails validation.
+          properties:
+            type:
+              type: string
+              enum:
+                - delta
+                - all
+              description: |-
+                Extraction strategy for each run. Use `delta` for incremental extraction of
+                changed records and `all` to re-extract every record on every run.
+              x-enumDescriptions:
+                delta: Extract only records changed since the previous run.
+                all: Extract every record on every run.
+              examples:
+                - delta
+            delta:
+              type: object
+              description: Incremental-extraction settings. Only used when `type` is `delta`.
+              properties:
+                dateField:
+                  type: string
+                  description: |-
+                    Source field carrying each record's last-modified timestamp, used as the
+                    delta cursor. Required for NetSuite datasets extracted via a
+                    `netsuite.recordType`; Salesforce datasets derive it automatically.
+                  examples:
+                    - lastmodifieddate
+            netsuite:
+              type: object
+              description: NetSuite-specific extraction settings. Omit for other sources.
+              properties:
+                recordType:
+                  type: string
+                  description: |-
+                    NetSuite record type backing a saved-search dataset. When set with
+                    `exportProperties.type: delta`, a `delta.dateField` is required.
+                  examples:
+                    - salesorder
+        driftPolicy:
+          type: object
+          description: |-
+            Per-dataset override of the sync's `driftPolicy` for column/field drift. Omit
+            to follow the sync-level policy.
+          properties:
+            element:
+              $ref: '#/components/schemas/ElementDriftPolicy'
+        dataElements:
+          type: array
+          description: |-
+            Per-column replication selections. Omit to replicate every column
+            (`enableAllDataElements` stays true). When provided, the array replaces the
+            dataset's previous selection entirely.
+          items:
+            $ref: '#/components/schemas/DataElement'
+    SyncRunRequest:
+      type: object
+      description: |-
+        Optional request body for triggering a sync run. When omitted or sent as `{}`, the sync runs
+        with `runType: "normal"` (incremental delta). Pass `runType: "resync"` to force a full re-extraction
+        from the source system, discarding the current delta checkpoint.
+      properties:
+        runType:
+          type: string
+          description: Controls whether the run is incremental or a full resync.
+          enum:
+            - normal
+            - resync
+          x-enumDescriptions:
+            normal: Incremental delta sync extracting only records modified since the last run.
+            resync: Full resync re-extracting all records from the source system.
+          default: normal
+      examples:
+        - runType: normal
+        - runType: resync
+    SyncRunResponse:
+      type: object
+      description: |-
+        Response from `POST /v1/syncs/{_syncId}/run`. Contains identifiers for the newly queued sync run.
+        Use `syncId` with `GET /v1/syncs/{_syncId}/syncJobs` or `flowExecutionGroupId` with
+        `GET /v1/syncJobs/{_syncJobId}` to poll for run completion.
+      properties:
+        syncId:
+          type: string
+          format: objectId
+          x-celigo-refModel: syncs
+          readOnly: true
+          description: The sync resource id that was triggered.
+          examples:
+            - 682094fa7eb7fc3e7ab7a4a0
+        flowExecutionGroupId:
+          type: string
+          readOnly: true
+          description: |-
+            Correlation id for this execution group. Groups the parent sync job and all child
+            table-level jobs spawned by this run.
+          examples:
+            - 6821c01c39db7c2b9cdc0e29
+      examples:
+        - syncId: 682094fa7eb7fc3e7ab7a4a0
+          flowExecutionGroupId: 6821c01c39db7c2b9cdc0e29
+    SyncJob:
+      type: object
+      required:
+        - _id
+        - _syncId
+        - _integrationId
+        - status
+        - runType
+        - createdAt
+      description: |-
+        A sync job represents one execution of a sync. Sync jobs are read-only records
+        created by the platform when a sync run is triggered (manually or on schedule). The job tracks
+        extraction, loading, and error counts across all tables in the sync. `numTablesSynced` reflects
+        only the tables that actively participated in this run -- for a delta run it may be lower than
+        the total table count.
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Sync job id.
+          examples:
+            - 6821c01c39db7c2b9cdc0e30
+        flowExecutionGroupId:
+          type: string
+          readOnly: true
+          description: Correlation id grouping this job with its child table jobs.
+          examples:
+            - 6821c01c39db7c2b9cdc0e29
+        _integrationId:
+          type: string
+          format: objectId
+          x-celigo-refModel: integrations
+          readOnly: true
+          description: Integration id this sync belongs to.
+          examples:
+            - 67d7b6e69e4b1371e5d1e2a1
+        _syncId:
+          type: string
+          format: objectId
+          x-celigo-refModel: syncs
+          readOnly: true
+          description: Sync resource id.
+          examples:
+            - 682094fa7eb7fc3e7ab7a4a0
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: When the sync job record was created (queued).
+          examples:
+            - '2026-04-28T14:30:00.000Z'
+        startedAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: When execution actually began. Absent while the job is still queued.
+          examples:
+            - '2026-04-28T14:30:01.123Z'
+        endedAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: When execution completed. Absent while the job is still running.
+          examples:
+            - '2026-04-28T14:35:12.456Z'
+        purgeAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: When the job record will be purged from storage.
+          examples:
+            - '2026-07-28T14:35:12.456Z'
+        status:
+          type: string
+          readOnly: true
+          description: |-
+            Current lifecycle state. Jobs start as `queued` when a run is accepted, move to
+            `running` once a worker picks them up, and end as `completed`, `failed`, or
+            `canceled`.
+          enum:
+            - queued
+            - running
+            - completed
+            - failed
+            - canceled
+          x-enumDescriptions:
+            queued: Run accepted and waiting for a worker to start execution.
+            running: Sync is currently executing.
+            completed: Sync finished successfully.
+            failed: Sync finished with a fatal error.
+            canceled: Sync was canceled by a user or the system.
+        numErrors:
+          type: integer
+          readOnly: true
+          description: Total number of errors produced across all tables in this run.
+          examples:
+            - 0
+        numLoadedRecords:
+          type: integer
+          readOnly: true
+          description: Total number of records loaded (written) to the data warehouse.
+          examples:
+            - 12450
+        numExtractedRecords:
+          type: integer
+          readOnly: true
+          description: Total number of records extracted from the source system.
+          examples:
+            - 12450
+        numTablesSynced:
+          type: integer
+          readOnly: true
+          description: Number of tables that were synced in this run.
+          examples:
+            - 3
+        triggeredBy:
+          type: string
+          readOnly: true
+          description: Who or what triggered this sync run (e.g. `"user:email"`, `"schedule"`).
+          examples:
+            - user:tyler.lamparter@celigo.com
+        canceledBy:
+          type: string
+          readOnly: true
+          description: Who or what canceled this run. Only present when `status` is `canceled`.
+          examples:
+            - user:tyler.lamparter@celigo.com
+        runType:
+          type: string
+          readOnly: true
+          description: Whether this was a normal (delta) or full resync run.
+          enum:
+            - normal
+            - resync
+          x-enumDescriptions:
+            normal: Incremental delta sync extracting only records modified since the last run.
+            resync: Full resync re-extracting all records from the source system.
+      examples:
+        - _id: 6821c01c39db7c2b9cdc0e30
+          flowExecutionGroupId: 6821c01c39db7c2b9cdc0e29
+          _integrationId: 67d7b6e69e4b1371e5d1e2a1
+          _syncId: 682094fa7eb7fc3e7ab7a4a0
+          createdAt: '2026-04-28T14:30:00.000Z'
+          startedAt: '2026-04-28T14:30:01.123Z'
+          endedAt: '2026-04-28T14:35:12.456Z'
+          purgeAt: '2026-07-28T14:35:12.456Z'
+          status: completed
+          numErrors: 0
+          numLoadedRecords: 12450
+          numExtractedRecords: 12450
+          numTablesSynced: 3
+          triggeredBy: user:tyler.lamparter@celigo.com
+          runType: normal
+    SyncJobsResponse:
+      type: object
+      description: |-
+        Paginated list of sync jobs for a given sync. Contains the array of job records and a total count.
+
+        Note: although the response includes `totalCount`, the `limit` and `offset` query parameters
+        on the list endpoint are silently ignored by the server as of this writing. The response always
+        returns all jobs.
+      properties:
+        data:
+          type: array
+          description: Array of sync job records.
+          items:
+            $ref: '#/components/schemas/SyncJob'
+        totalCount:
+          type: integer
+          readOnly: true
+          description: Total number of sync jobs for this sync (across all pages).
+          examples:
+            - 1
+      examples:
+        - data:
+            - _id: 6821c01c39db7c2b9cdc0e30
+              flowExecutionGroupId: 6821c01c39db7c2b9cdc0e29
+              _integrationId: 67d7b6e69e4b1371e5d1e2a1
+              _syncId: 682094fa7eb7fc3e7ab7a4a0
+              createdAt: '2026-04-28T14:30:00.000Z'
+              startedAt: '2026-04-28T14:30:01.123Z'
+              endedAt: '2026-04-28T14:35:12.456Z'
+              purgeAt: '2026-07-28T14:35:12.456Z'
+              status: completed
+              numErrors: 0
+              numLoadedRecords: 12450
+              numExtractedRecords: 12450
+              numTablesSynced: 3
+              triggeredBy: user:tyler.lamparter@celigo.com
+              runType: normal
+          totalCount: 1
+    SyncTableJob:
+      type: object
+      description: |-
+        A child job representing one table's extraction and load within a parent sync run. Each table
+        job tracks its own record counts, error counts, and timing independently.
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Child table job id.
+          examples:
+            - 6821c01c39db7c2b9cdc0e31
+        tableName:
+          type: string
+          readOnly: true
+          description: Name of the table being synced (e.g. `"contacts"`, `"orders"`).
+          examples:
+            - contacts
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: When this child job was created.
+          examples:
+            - '2026-04-28T14:30:01.200Z'
+        status:
+          type: string
+          readOnly: true
+          description: |-
+            Current lifecycle state of this table's sync. Table jobs start as `queued`, move
+            to `running` when extraction begins, and end as `completed`, `failed`, or
+            `canceled`.
+          enum:
+            - queued
+            - running
+            - completed
+            - failed
+            - canceled
+          x-enumDescriptions:
+            queued: Table sync is waiting for a worker to start.
+            running: Table sync is currently executing.
+            completed: Table sync finished successfully.
+            failed: Table sync finished with a fatal error.
+            canceled: Table sync was canceled.
+        numErrors:
+          type: integer
+          readOnly: true
+          description: Number of errors encountered syncing this table.
+          examples:
+            - 0
+        numLoadedRecords:
+          type: integer
+          readOnly: true
+          description: Number of records loaded into the warehouse for this table.
+          examples:
+            - 8200
+        numExtractedRecords:
+          type: integer
+          readOnly: true
+          description: Number of records extracted from the source for this table.
+          examples:
+            - 8200
+        isNormalizedTable:
+          type: boolean
+          readOnly: true
+          description: |-
+            When true, this table is a normalized child table split out from
+            nested data in the source dataset rather than a source table itself.
+            Present only when true — omitted from the response when false.
+        startedAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: When extraction began for this table. Absent if not yet started.
+          examples:
+            - '2026-04-28T14:30:01.300Z'
+        endedAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: When loading completed for this table. Absent if still running.
+          examples:
+            - '2026-04-28T14:33:45.100Z'
+      examples:
+        - _id: 6821c01c39db7c2b9cdc0e31
+          tableName: contacts
+          createdAt: '2026-04-28T14:30:01.200Z'
+          status: completed
+          numErrors: 0
+          numLoadedRecords: 8200
+          numExtractedRecords: 8200
+          startedAt: '2026-04-28T14:30:01.300Z'
+          endedAt: '2026-04-28T14:33:45.100Z'
+    SyncJobFamily:
+      type: object
+      description: |-
+        A sync job family consisting of the parent sync job and its per-table child jobs. Each entry in
+        `tables` represents one table that was synced as part of this run, with its own status, record
+        counts, and timing. The parent-level counters are the authoritative totals; `tables[]` provides
+        the per-table breakdown. `tables` may be empty if the job was canceled before any table work
+        started.
+      allOf:
+        - $ref: '#/components/schemas/SyncJob'
+        - type: object
+          properties:
+            tables:
+              type: array
+              description: Per-table child job records for this sync run.
+              items:
+                $ref: '#/components/schemas/SyncTableJob'
+    SyncError:
+      type: object
+      description: |-
+        An individual error record from a sync run. Errors are scoped to a specific table (identified by
+        `tableName` and `_datasetId`) within a sync execution. `_parentSyncJobId` links to the parent
+        sync job and `_childSyncJobId` links to the table-level child.
+      properties:
+        scope:
+          type: string
+          readOnly: true
+          description: Pipeline scope where the error occurred (e.g. `"extract"`, `"load"`).
+          examples:
+            - extract
+        source:
+          type: string
+          readOnly: true
+          description: System or component that produced the error.
+          examples:
+            - salesforce
+        code:
+          type: string
+          readOnly: true
+          description: Machine-readable error code.
+          examples:
+            - INVALID_FIELD
+        message:
+          type: string
+          readOnly: true
+          description: Human-readable error message.
+          examples:
+            - No such column 'Custom_Field__c' on entity 'Account'.
+        _datasetId:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Dataset id associated with this error.
+          examples:
+            - 6821c01c39db7c2b9cdc0e35
+        _syncId:
+          type: string
+          format: objectId
+          x-celigo-refModel: syncs
+          readOnly: true
+          description: Sync resource id.
+          examples:
+            - 682094fa7eb7fc3e7ab7a4a0
+        _parentSyncJobId:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Parent sync job id.
+          examples:
+            - 6821c01c39db7c2b9cdc0e30
+        _childSyncJobId:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Child (table-level) sync job id.
+          examples:
+            - 6821c01c39db7c2b9cdc0e31
+        flowExecutionGroupId:
+          type: string
+          readOnly: true
+          description: Correlation id for the execution group.
+          examples:
+            - 6821c01c39db7c2b9cdc0e29
+        stage:
+          type: string
+          readOnly: true
+          description: Pipeline stage where the error occurred.
+          examples:
+            - extraction
+        datasetName:
+          type: string
+          readOnly: true
+          description: Human-readable dataset name.
+          examples:
+            - Salesforce Accounts
+        tableName:
+          type: string
+          readOnly: true
+          description: Table name where the error occurred.
+          examples:
+            - accounts
+        occurredAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: When the error occurred.
+          examples:
+            - '2026-04-28T14:31:22.789Z'
+      examples:
+        - scope: extract
+          source: salesforce
+          code: INVALID_FIELD
+          message: No such column 'Custom_Field__c' on entity 'Account'.
+          _datasetId: 6821c01c39db7c2b9cdc0e35
+          _syncId: 682094fa7eb7fc3e7ab7a4a0
+          _parentSyncJobId: 6821c01c39db7c2b9cdc0e30
+          _childSyncJobId: 6821c01c39db7c2b9cdc0e31
+          flowExecutionGroupId: 6821c01c39db7c2b9cdc0e29
+          stage: extraction
+          datasetName: Salesforce Accounts
+          tableName: accounts
+          occurredAt: '2026-04-28T14:31:22.789Z'
+    SyncEvent:
+      type: object
+      description: |-
+        One event recorded while a sync runs — schema drift the platform detected or
+        handled, and data-catalog activity. Events are retained per the account's data
+        retention period and ordered newest first.
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: Unique identifier for the event.
+          examples:
+            - 80ba31fe-b66d-4777-9b12-3177c55aab13
+        _userId:
+          type: string
+          format: objectId
+          x-celigo-refModel: users
+          description: Account owner the event belongs to.
+          examples:
+            - 68c821306f5d848c881da205
+        _syncId:
+          type: string
+          format: objectId
+          x-celigo-refModel: syncs
+          description: Sync the event was recorded for.
+          examples:
+            - 6a4b8bfb731a7a5cae9bd364
+        flowExecutionGroupId:
+          type: string
+          description: |-
+            Run the event belongs to. Matches the `flowExecutionGroupId` returned by
+            `POST /v1/syncs/{_syncId}/run` and carried on the run's sync jobs, so events
+            can be correlated with jobs and errors from the same execution.
+          examples:
+            - d0f875a575bd4b8c944533da773f350a
+        resourceName:
+          type: string
+          description: Source table/object the event is about.
+          examples:
+            - Account
+        severity:
+          type: string
+          enum:
+            - INFO
+            - WARN
+            - ERROR
+          description: |-
+            How much attention the event needs. Informational drift the policy handled
+            automatically is `INFO`; conditions requiring user action surface as `WARN`
+            or `ERROR`.
+          x-enumDescriptions:
+            INFO: Informational; the platform handled the event automatically.
+            WARN: The event may need review but did not stop the sync.
+            ERROR: The event blocked part of the sync and needs user action.
+          examples:
+            - INFO
+        eventTime:
+          type: string
+          format: date-time
+          description: Timestamp when the event was recorded.
+          examples:
+            - '2026-07-13T12:36:06.225Z'
+        type:
+          type: string
+          enum:
+            - Schema Drift
+            - Data Catalog
+          description: |-
+            Event category. Filter the list to one category with the `type` query
+            parameter.
+          x-enumDescriptions:
+            Schema Drift: A change to the source schema was detected or applied (e.g. table added, column removed).
+            Data Catalog: Dataset metadata activity recorded while cataloging the source.
+          examples:
+            - Schema Drift
+        stage:
+          type: string
+          enum:
+            - Extract
+            - Transform
+            - Load
+            - ''
+          description: |-
+            Pipeline stage the event was recorded in. Empty when the event is not tied to
+            a specific stage.
+          x-enumDescriptions:
+            Extract: While reading records or schema from the source.
+            Transform: While reshaping records between source and destination.
+            Load: While writing records or applying schema changes in the destination.
+            '': Not tied to a specific pipeline stage.
+          examples:
+            - Extract
+        metadata:
+          description: |-
+            Event-specific detail. For `Schema Drift` events this is an object with an
+            `action` (e.g. `Table added`, `Table removed`, `Column added`, `Column removed`,
+            `Column expanded`, `Column reduced`, `Column constraint updated`), the
+            `resourceType` affected, and — for column-level drift — fields like `fieldName`,
+            `oldValue`, `newValue`, or the applied DDL under `query`.
+          oneOf:
+            - title: object
+              type: object
+              additionalProperties: true
+            - title: string
+              type: string
+          examples:
+            - action: Table removed
+              resourceType: Table
+  responses:
+    401-unauthorized:
+      description: |-
+        Unauthorized. The request lacks a valid bearer token, or the provided token
+        failed to authenticate.
+
+        Note: the 401 response is produced by the auth middleware **before** the
+        request reaches the endpoint handler, so it does **not** follow the
+        standard `{errors: [...]}` envelope. Instead the body is a bare
+        `{message: string}` object with no `code`, no `errors` array. Callers
+        handling 401s should key off the HTTP status and the `message` string,
+        not try to destructure an `errors[]`.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                description: |-
+                  Human-readable description of the auth failure. Known values:
+                  - `"Unauthorized"` — no `Authorization` header on the request.
+                  - `"Bearer Authentication Failed"` — header present but token
+                    is invalid, revoked, or expired.
+            required:
+              - message
+          examples:
+            missing_token:
+              summary: No Authorization header sent
+              value:
+                message: Unauthorized
+            invalid_token:
+              summary: Bearer token invalid or revoked
+              value:
+                message: Bearer Authentication Failed
+    422-unprocessable-entity:
+      description: |
+        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: unprocessable_entity
+                    message: The request could not be processed due to a semantic error.
+    404-not-found:
+      description: |
+        Not found. The requested resource does not exist or is not visible to the caller.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: not_found
+                    message: The requested resource was not found.
+    400-bad-request:
+      description: |
+        Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: invalid_request
+                    message: The request body failed validation.
+x-enable-proxy: true
+x-internal: false