@celigo/api-specs 0.2.19 → 0.2.21

package/dist/sync.yml

@@ -888,12 +888,13 @@ paths:
         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.
+        A resync drops the delta checkpoint and reloads all data. Subset selection on a resync
+        is always accepted; on a normal run it is rejected unless the account has partial
+        normal sync enabled.
 
         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`).
+        - There must not be a job already queued or running 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
@@ -921,6 +922,13 @@ paths:
                 summary: Full resync from source
                 value:
                   runType: resync
+              resyncSubset:
+                summary: Resync selected datasets
+                value:
+                  runType: resync
+                  datasetIds:
+                    - 6a559b547885d8f93921c2ba
+                    - 6a559b547885d8f93921c2bb
       responses:
         '200':
           description: Sync run accepted and queued.
@@ -936,8 +944,10 @@ paths:
                     flowExecutionGroupId: 6821c01c39db7c2b9cdc0e29
         '400':
           description: |-
-            Bad request. Invalid `runType` value.
-            Error code: `invalid_parameter`.
+            Bad request. Invalid `runType`, invalid `datasetIds` shape, subset selection on a
+            normal run when that is not enabled for the account, or datasets that do not
+            belong to this sync / are disabled.
+            Error codes: `invalid_parameter`, `invalid_dataset_selection`.
           content:
             application/json:
               schema:
@@ -948,7 +958,25 @@ paths:
                   value:
                     errors:
                       - code: invalid_parameter
-                        message: Invalid value for runType.
+                        message: 'runType must be one of: normal, resync'
+                dataset_ids_not_supported:
+                  summary: Subset selection on a normal run is not enabled
+                  value:
+                    errors:
+                      - code: invalid_parameter
+                        message: datasetIds is not supported for normal sync runs
+                invalid_dataset_ids_shape:
+                  summary: datasetIds is not a non-empty array of ObjectIds
+                  value:
+                    errors:
+                      - code: invalid_parameter
+                        message: datasetIds must be an array of valid dataset IDs
+                invalid_dataset_selection:
+                  summary: Selected datasets do not belong to this sync or are disabled
+                  value:
+                    errors:
+                      - code: invalid_dataset_selection
+                        message: one or more selected datasets do not belong to this sync or are disabled
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '404':
@@ -1004,12 +1032,10 @@ paths:
         - 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.
+        Returns parent sync jobs for the given sync, newest first. When a created-at filter is
+        set, `queued` and `running` jobs are pinned to the first pages even if they fall outside
+        the range; `canceling` jobs are not pinned. Follow `Link` header URLs as-is to page
+        through pinned jobs and then the date-filtered remainder.
       parameters:
         - name: _syncId
           in: path
@@ -1019,9 +1045,73 @@ paths:
             type: string
             format: objectId
             x-celigo-refModel: syncs
+        - name: pageSize
+          in: query
+          required: false
+          description: Maximum number of jobs to return per page.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 100
+            examples:
+              - 25
+        - 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
+        - name: before
+          in: query
+          required: false
+          description: |-
+            Opaque pagination cursor for the previous page. Take it from the `before` value in
+            the `Link` response header's `rel="prev"` URL rather than constructing it.
+          schema:
+            type: string
+        - name: createdAt_gt
+          in: query
+          required: false
+          description: Only return jobs created after this time. Accepts ISO 8601 or epoch milliseconds.
+          schema:
+            type: string
+            examples:
+              - '2026-04-01T00:00:00.000Z'
+        - name: createdAt_lte
+          in: query
+          required: false
+          description: Only return jobs created at or before this time. Accepts ISO 8601 or epoch milliseconds.
+          schema:
+            type: string
+            examples:
+              - '2026-04-30T23:59:59.000Z'
+        - name: listPhase
+          in: query
+          required: false
+          description: |-
+            Pagination phase echoed in `Link` URLs when a date filter is present. Follow those
+            URLs as-is rather than setting this yourself.
+          schema:
+            type: string
+            enum:
+              - pinned
+              - historical
+            x-enumDescriptions:
+              pinned: Pages queued and running jobs first
+              historical: Pages the date-filtered remainder (completed, failed, canceled, canceling)
       responses:
         '200':
-          description: List of sync jobs.
+          description: Page of sync jobs.
+          headers:
+            Link:
+              description: |-
+                RFC 5988 pagination links. Includes `<...>; rel="next"` and/or
+                `<...>; rel="prev"` when more pages remain; absent on a single page.
+              schema:
+                type: string
           content:
             application/json:
               schema:
@@ -1060,8 +1150,30 @@ paths:
                         numExtractedRecords: 11982
                         numTablesSynced: 3
                         triggeredBy: schedule
-                        runType: normal
+                        runType: resync
+                        datasetIds:
+                          - 6a559b547885d8f93921c2ba
                     totalCount: 2
+                empty:
+                  summary: Sync with no jobs
+                  value:
+                    data: []
+                    totalCount: 0
+        '400':
+          description: |-
+            Invalid pagination cursor or query parameter.
+            Error code: `invalid_query_param`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_query_param:
+                  summary: Malformed pagination cursor
+                  value:
+                    errors:
+                      - code: invalid_query_param
+                        message: Invalid pagination cursor.
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '404':
@@ -1085,14 +1197,15 @@ paths:
       operationId: cancelSyncJobs
       tags:
         - Sync Jobs
-      summary: Cancel all running sync jobs for a sync
+      summary: Cancel all in-progress sync jobs
       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.
+        Cancels every queued or running sync job for the given sync, including the underlying
+        flow jobs for each run.
 
-        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`.
+        If every job is already terminal, the request is rejected. If parent jobs are canceled
+        but no flow jobs remain, the response includes a confirmation message instead of an
+        empty success. A job whose cancellation is already in progress is not cancelled again.
+        To cancel a single specific job instead, use `PUT /v1/syncJobs/{_syncJobId}/cancel`.
       parameters:
         - name: _syncId
           in: path
@@ -1103,8 +1216,25 @@ paths:
             format: objectId
             x-celigo-refModel: syncs
       responses:
+        '200':
+          description: Parent jobs canceled; no remaining flow jobs to cancel.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                    description: Confirmation that there were no remaining flow jobs to cancel.
+                    examples:
+                      - No more jobs to cancel
+              examples:
+                no_more_jobs:
+                  summary: Parents canceled with no remaining flow jobs
+                  value:
+                    message: No more jobs to cancel
         '204':
-          description: All running sync jobs have been canceled. No response body.
+          description: Cancellation accepted. No response body.
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '404':
@@ -1117,11 +1247,26 @@ paths:
                 $ref: '#/components/schemas/Error'
               examples:
                 no_jobs:
-                  summary: No running jobs to cancel
+                  summary: No queued or running jobs to cancel
                   value:
                     errors:
                       - code: sync_jobs_not_found
                         message: No cancellable sync jobs found.
+        '409':
+          description: |-
+            Cancellation is already in progress for the remaining jobs.
+            Error code: `sync_job_cancellation_in_progress`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                cancellation_in_progress:
+                  summary: Jobs already canceling
+                  value:
+                    errors:
+                      - code: sync_job_cancellation_in_progress
+                        message: 'Cancellation is already in progress for sync job(s): 6821c01c39db7c2b9cdc0e30.'
   /v1/syncJobs/{_syncJobId}:
     get:
       x-internal: false
@@ -1271,17 +1416,12 @@ paths:
         - 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).
+        Returns errors produced during extraction or loading for the given parent sync job,
+        scoped to individual tables.
 
-        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.
+        Use `_childJobId` to filter to a single table. 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`.
       parameters:
         - name: _parentJobId
           in: path
@@ -1295,21 +1435,54 @@ paths:
           in: query
           required: false
           description: |-
-            Optional child (table-level) job id to filter errors to a single table.
+            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
+        - name: pageSize
+          in: query
+          required: false
+          description: Maximum number of errors to return per page.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 100
+            examples:
+              - 25
+        - 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
+        - name: before
+          in: query
+          required: false
+          description: |-
+            Opaque pagination cursor for the previous page. Take it from the `before` value in
+            the `Link` response header's `rel="prev"` URL rather than constructing it.
+          schema:
+            type: string
       responses:
         '200':
           description: Array of sync error records.
           headers:
-            x-total-count:
-              description: Total number of errors matching the query.
+            X-Total-Count:
+              description: Total number of errors matching the query, ignoring the current page.
               schema:
                 type: integer
+            Link:
+              description: |-
+                RFC 5988 pagination links. Includes `<...>; rel="next"` and/or
+                `<...>; rel="prev"` when more pages remain; absent on a single page.
+              schema:
+                type: string
           content:
             application/json:
               schema:
@@ -1349,6 +1522,21 @@ paths:
                 empty:
                   summary: No errors
                   value: []
+        '400':
+          description: |-
+            Invalid pagination cursor or query parameter.
+            Error code: `invalid_query_param`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_query_param:
+                  summary: Malformed pagination cursor
+                  value:
+                    errors:
+                      - code: invalid_query_param
+                        message: Invalid pagination cursor.
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '404':
@@ -1361,11 +1549,13 @@ paths:
         - Sync Jobs
       summary: Cancel a single sync job
       description: |-
-        Cancels a specific sync job by id.
+        Cancels a specific sync job by id, including its underlying flow jobs.
 
-        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.
+        Only queued or running jobs can be canceled. Terminal jobs cannot. A job whose
+        cancellation is already in progress is not cancelled again. If the parent is canceled
+        but no flow jobs remain, the response includes a confirmation message instead of an
+        empty success. To cancel all in-progress jobs for a sync at once, use
+        `PUT /v1/syncs/{_syncId}/syncJobs/cancel`.
       parameters:
         - name: _syncJobId
           in: path
@@ -1376,8 +1566,25 @@ paths:
             format: objectId
             x-celigo-refModel: syncJobs
       responses:
+        '200':
+          description: Parent job canceled; no remaining flow jobs to cancel.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                    description: Confirmation that there were no remaining flow jobs to cancel.
+                    examples:
+                      - No more jobs to cancel
+              examples:
+                no_more_jobs:
+                  summary: Parent canceled with no remaining flow jobs
+                  value:
+                    message: No more jobs to cancel
         '204':
-          description: Sync job canceled successfully. No response body.
+          description: Cancellation accepted. No response body.
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '403':
@@ -1394,9 +1601,24 @@ paths:
                   value:
                     errors:
                       - code: sync_job_not_cancellable
-                        message: The sync job is not in a cancellable state.
+                        message: The job 6821c01c39db7c2b9cdc0e30 is already in terminal state. Status - completed
         '404':
           $ref: '#/components/responses/404-not-found'
+        '409':
+          description: |-
+            Cancellation is already in progress for this job.
+            Error code: `sync_job_cancellation_in_progress`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                cancellation_in_progress:
+                  summary: Job already canceling
+                  value:
+                    errors:
+                      - code: sync_job_cancellation_in_progress
+                        message: 'Cancellation is already in progress for sync job(s): 6821c01c39db7c2b9cdc0e30.'
   /v1/integrations/{_integrationId}/syncJobs/latest:
     get:
       x-internal: false
@@ -4220,9 +4442,8 @@ components:
     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.
+        Optional request body for triggering a sync run. When omitted or sent as `{}`, the sync
+        runs every enabled dataset as an incremental delta.
       properties:
         runType:
           type: string
@@ -4234,9 +4455,32 @@ components:
             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
+        datasetIds:
+          type: array
+          minItems: 1
+          description: |-
+            Scopes this run to these datasets on the sync. Omit the field to run every
+            enabled dataset; an empty array is rejected. Each id must belong to this sync
+            and be enabled, and subset selection on a normal run is rejected unless the
+            account has partial normal sync enabled.
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: datasets
+          examples:
+            - - 6a559b547885d8f93921c2ba
+              - 6a559b547885d8f93921c2bb
+          x-celigo-ai-guidance:
+            - Omit datasetIds to run every enabled dataset. Empty array is rejected; duplicates are de-duplicated.
+            - Partial selection with runType resync is always accepted. Partial selection with runType normal is rejected with invalid_parameter unless the account has partial normal sync enabled.
+            - Datasets that do not belong to this sync or are disabled fail with 400 invalid_dataset_selection.
       examples:
         - runType: normal
         - runType: resync
+        - runType: resync
+          datasetIds:
+            - 6a559b547885d8f93921c2ba
+            - 6a559b547885d8f93921c2bb
     SyncRunResponse:
       type: object
       description: |-
@@ -4340,18 +4584,19 @@ components:
           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`.
+            Current lifecycle state. Cancel is asynchronous: the job stays non-terminal
+            until in-flight work stops.
           enum:
             - queued
             - running
+            - canceling
             - completed
             - failed
             - canceled
           x-enumDescriptions:
             queued: Run accepted and waiting for a worker to start execution.
             running: Sync is currently executing.
+            canceling: Cancellation requested; in-flight work has not yet stopped.
             completed: Sync finished successfully.
             failed: Sync finished with a fatal error.
             canceled: Sync was canceled by a user or the system.
@@ -4388,7 +4633,7 @@ components:
         canceledBy:
           type: string
           readOnly: true
-          description: Who or what canceled this run. Only present when `status` is `canceled`.
+          description: Who requested cancellation. Present once cancellation has been requested.
           examples:
             - user:tyler.lamparter@celigo.com
         runType:
@@ -4401,6 +4646,17 @@ components:
           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.
+        datasetIds:
+          type: array
+          readOnly: true
+          description: Datasets this run was scoped to. Absent when the run included every enabled dataset.
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: datasets
+          examples:
+            - - 6a559b547885d8f93921c2ba
+              - 6a559b547885d8f93921c2bb
       examples:
         - _id: 6821c01c39db7c2b9cdc0e30
           flowExecutionGroupId: 6821c01c39db7c2b9cdc0e29
@@ -4417,24 +4673,35 @@ components:
           numTablesSynced: 3
           triggeredBy: user:tyler.lamparter@celigo.com
           runType: normal
+        - _id: 6821c01c39db7c2b9cdc0e40
+          flowExecutionGroupId: 6821c01c39db7c2b9cdc0e39
+          _integrationId: 67d7b6e69e4b1371e5d1e2a1
+          _syncId: 682094fa7eb7fc3e7ab7a4a0
+          createdAt: '2026-04-28T15:00:00.000Z'
+          startedAt: '2026-04-28T15:00:01.000Z'
+          status: running
+          numErrors: 0
+          numLoadedRecords: 0
+          numExtractedRecords: 0
+          numTablesSynced: 1
+          triggeredBy: user:tyler.lamparter@celigo.com
+          runType: resync
+          datasetIds:
+            - 6a559b547885d8f93921c2ba
+            - 6a559b547885d8f93921c2bb
     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.
+      description: One page of sync jobs for a given sync, plus the total number of jobs matching the query.
       properties:
         data:
           type: array
-          description: Array of sync job records.
+          description: Sync job records for this page, newest first.
           items:
             $ref: '#/components/schemas/SyncJob'
         totalCount:
           type: integer
           readOnly: true
-          description: Total number of sync jobs for this sync (across all pages).
+          description: Total number of sync jobs matching the query, including queued and running jobs pinned outside a date filter.
           examples:
             - 1
       examples: