@celigo/api-specs 0.2.145 → 0.2.147

package/dist/api.yml

@@ -5385,7 +5385,7 @@ components:
               x-celigo-ai-guidance:
                 - To change throughput while this is true, write `targetConcurrencyLevel`; a `concurrencyLevel` sent in a PUT returns 200 and changes nothing.
                 - Turning it on copies `concurrencyLevel` into `targetConcurrencyLevel`; turning it off unsets the target and leaves `concurrencyLevel` at its current value, which may be below the old target if a recovery was in progress. A `targetConcurrencyLevel` written while this is false is unset by the save.
-                - These four settings (`concurrencyLevel`, `targetConcurrencyLevel`, `_borrowConcurrencyFromConnectionId`, this flag) accept a credential-free `PATCH /v1/connections/{_id}`. A PUT must re-send the credentials — omitting them or echoing their masked `******` values clears them.
+                - These four settings (`concurrencyLevel`, `targetConcurrencyLevel`, `_borrowConcurrencyFromConnectionId`, this flag) accept a credential-free `PATCH /v1/connections/{_id}`. A PUT replaces the whole document, so send each secret back as its masked `******` value (that keeps it) or as a new value, and never drop one to keep it — an omitted password or `http.encrypted` is cleared, and a static token left out (with no `refreshMethod`) fails the PUT with 422.
             enableMicroBatchForOneToMany:
               type: boolean
               default: true
@@ -7036,7 +7036,9 @@ components:
                     - svc_account
                 password:
                   type: string
-                  description: Password for Basic/Digest/WSSE authentication (encrypted at rest).
+                  description: |-
+                    Password for Basic/Digest/WSSE authentication (encrypted at rest). On update, the
+                    masked `"******"` sent back keeps the stored password; a new value replaces it.
                   writeOnly: true
                   examples:
                     - s3cr3t-p4ssw0rd
@@ -7053,6 +7055,7 @@ components:
                   type: string
                   description: |
                     The API key or bearer token value (encrypted at rest); returned masked as `"******"`.
+                    On update, the mask sent back keeps the stored token; a new value replaces it.
                     Required unless automatic token refresh is configured.
                   examples:
                     - my-api-token-EXAMPLE
@@ -7515,7 +7518,8 @@ components:
             Encrypted custom fields for storing sensitive configuration values (API secrets,
             private keys, etc.) that don't fit standard auth fields. Sent as an object of
             field-name/value pairs; values are encrypted at rest. Returned as the masked
-            string `"******"` on responses. Field definitions are specified in encryptedFields.
+            string `"******"` on responses; on update, that mask sent back keeps the stored values,
+            and a new object replaces them. Field definitions are specified in encryptedFields.
           examples:
             - apiSecret: s3cr3t-value
               signingKey: another-s3cr3t
@@ -9257,6 +9261,7 @@ components:
           type: string
           description: |
             The API key or bearer token value (encrypted at rest); returned masked as `"******"`.
+            On update, the mask sent back keeps the stored token; a new value replaces it.
             Required unless automatic token refresh is configured.
           examples:
             - my-api-token-EXAMPLE

package/dist/connection.yml

@@ -830,8 +830,11 @@ paths:
       description: |
         Updates an existing connection configuration. This is a full-replace operation —
         send the complete connection document, not just the fields you want to change; a field
-        omitted from the body is cleared, including credentials (re-send them, or the masked
-        `"******"` value clears them too).
+        omitted from the body is cleared. A stored secret sent back as the masked `"******"` value a
+        GET returns keeps its stored value; send a new value to change it. Don't leave a secret out
+        to keep it: an omitted `http.auth.basic.password` or `http.encrypted` is cleared, and a
+        static-token connection (no `http.auth.token.refreshMethod`) sent without
+        `http.auth.token.token` is rejected with 422 `Expected field: refreshMethod to be present.`
 
         Three settings are the exception and survive an omission: `endUserProvidedFields`
         (send `null` to clear it — `[]` is treated like an omission), and on `ftp` connections
@@ -985,9 +988,11 @@ paths:
       x-celigo-ai-guidance:
         - |-
           PUT replaces the document: GET it first, change what you need, and send the whole body
-          back with the real credential values (masked "******" values clear the stored secret).
-          To change only name, debug window, or concurrency settings without touching credentials,
-          use PATCH instead.
+          back. Leave each secret's masked "******" value exactly as the GET returned it (that keeps
+          the stored secret) or put a new value in its place. Never drop a secret field to keep it:
+          an omitted password or `http.encrypted` is cleared, and a static token left out (with no
+          `refreshMethod`) fails the PUT with 422. To change only name, debug window, or concurrency
+          settings without touching credentials, use PATCH instead.
     patch:
       x-internal: false
       summary: Patch a connection
@@ -4240,7 +4245,7 @@ components:
               x-celigo-ai-guidance:
                 - To change throughput while this is true, write `targetConcurrencyLevel`; a `concurrencyLevel` sent in a PUT returns 200 and changes nothing.
                 - Turning it on copies `concurrencyLevel` into `targetConcurrencyLevel`; turning it off unsets the target and leaves `concurrencyLevel` at its current value, which may be below the old target if a recovery was in progress. A `targetConcurrencyLevel` written while this is false is unset by the save.
-                - These four settings (`concurrencyLevel`, `targetConcurrencyLevel`, `_borrowConcurrencyFromConnectionId`, this flag) accept a credential-free `PATCH /v1/connections/{_id}`. A PUT must re-send the credentials — omitting them or echoing their masked `******` values clears them.
+                - These four settings (`concurrencyLevel`, `targetConcurrencyLevel`, `_borrowConcurrencyFromConnectionId`, this flag) accept a credential-free `PATCH /v1/connections/{_id}`. A PUT replaces the whole document, so send each secret back as its masked `******` value (that keeps it) or as a new value, and never drop one to keep it — an omitted password or `http.encrypted` is cleared, and a static token left out (with no `refreshMethod`) fails the PUT with 422.
             enableMicroBatchForOneToMany:
               type: boolean
               default: true
@@ -5891,7 +5896,9 @@ components:
                     - svc_account
                 password:
                   type: string
-                  description: Password for Basic/Digest/WSSE authentication (encrypted at rest).
+                  description: |-
+                    Password for Basic/Digest/WSSE authentication (encrypted at rest). On update, the
+                    masked `"******"` sent back keeps the stored password; a new value replaces it.
                   writeOnly: true
                   examples:
                     - s3cr3t-p4ssw0rd
@@ -5908,6 +5915,7 @@ components:
                   type: string
                   description: |
                     The API key or bearer token value (encrypted at rest); returned masked as `"******"`.
+                    On update, the mask sent back keeps the stored token; a new value replaces it.
                     Required unless automatic token refresh is configured.
                   examples:
                     - my-api-token-EXAMPLE
@@ -6370,7 +6378,8 @@ components:
             Encrypted custom fields for storing sensitive configuration values (API secrets,
             private keys, etc.) that don't fit standard auth fields. Sent as an object of
             field-name/value pairs; values are encrypted at rest. Returned as the masked
-            string `"******"` on responses. Field definitions are specified in encryptedFields.
+            string `"******"` on responses; on update, that mask sent back keeps the stored values,
+            and a new object replaces them. Field definitions are specified in encryptedFields.
           examples:
             - apiSecret: s3cr3t-value
               signingKey: another-s3cr3t
@@ -8112,6 +8121,7 @@ components:
           type: string
           description: |
             The API key or bearer token value (encrypted at rest); returned masked as `"******"`.
+            On update, the mask sent back keeps the stored token; a new value replaces it.
             Required unless automatic token refresh is configured.
           examples:
             - my-api-token-EXAMPLE

package/dist/enduser.yml

@@ -2357,7 +2357,7 @@ components:
               x-celigo-ai-guidance:
                 - To change throughput while this is true, write `targetConcurrencyLevel`; a `concurrencyLevel` sent in a PUT returns 200 and changes nothing.
                 - Turning it on copies `concurrencyLevel` into `targetConcurrencyLevel`; turning it off unsets the target and leaves `concurrencyLevel` at its current value, which may be below the old target if a recovery was in progress. A `targetConcurrencyLevel` written while this is false is unset by the save.
-                - These four settings (`concurrencyLevel`, `targetConcurrencyLevel`, `_borrowConcurrencyFromConnectionId`, this flag) accept a credential-free `PATCH /v1/connections/{_id}`. A PUT must re-send the credentials — omitting them or echoing their masked `******` values clears them.
+                - These four settings (`concurrencyLevel`, `targetConcurrencyLevel`, `_borrowConcurrencyFromConnectionId`, this flag) accept a credential-free `PATCH /v1/connections/{_id}`. A PUT replaces the whole document, so send each secret back as its masked `******` value (that keeps it) or as a new value, and never drop one to keep it — an omitted password or `http.encrypted` is cleared, and a static token left out (with no `refreshMethod`) fails the PUT with 422.
             enableMicroBatchForOneToMany:
               type: boolean
               default: true
@@ -4008,7 +4008,9 @@ components:
                     - svc_account
                 password:
                   type: string
-                  description: Password for Basic/Digest/WSSE authentication (encrypted at rest).
+                  description: |-
+                    Password for Basic/Digest/WSSE authentication (encrypted at rest). On update, the
+                    masked `"******"` sent back keeps the stored password; a new value replaces it.
                   writeOnly: true
                   examples:
                     - s3cr3t-p4ssw0rd
@@ -4025,6 +4027,7 @@ components:
                   type: string
                   description: |
                     The API key or bearer token value (encrypted at rest); returned masked as `"******"`.
+                    On update, the mask sent back keeps the stored token; a new value replaces it.
                     Required unless automatic token refresh is configured.
                   examples:
                     - my-api-token-EXAMPLE
@@ -4487,7 +4490,8 @@ components:
             Encrypted custom fields for storing sensitive configuration values (API secrets,
             private keys, etc.) that don't fit standard auth fields. Sent as an object of
             field-name/value pairs; values are encrypted at rest. Returned as the masked
-            string `"******"` on responses. Field definitions are specified in encryptedFields.
+            string `"******"` on responses; on update, that mask sent back keeps the stored values,
+            and a new object replaces them. Field definitions are specified in encryptedFields.
           examples:
             - apiSecret: s3cr3t-value
               signingKey: another-s3cr3t
@@ -6229,6 +6233,7 @@ components:
           type: string
           description: |
             The API key or bearer token value (encrypted at rest); returned masked as `"******"`.
+            On update, the mask sent back keeps the stored token; a new value replaces it.
             Required unless automatic token refresh is configured.
           examples:
             - my-api-token-EXAMPLE

package/dist/export.yml

@@ -6001,7 +6001,9 @@ components:
           description: |-
             Topic this listener subscribes to. Create or look it up with `GET /v1/topics`; the
             topic must belong to the same account. Pointing an existing listener at a different
-            topic starts a new subscription, read from `startPosition`.
+            topic starts a new subscription, read from `startPosition`. A clone made in the same
+            environment — of this export, or of a flow that contains it — keeps `_topicId`, so the
+            copy becomes another listener on the topic once its flow is enabled.
           x-celigo-ai-guidance:
             - |-
               An id that is not a topic in the account fails the save with 422 `invalid_ref`
@@ -16517,7 +16519,10 @@ components:
             - 'null'
           format: objectId
           x-celigo-refModel: integrations
-          description: Integration this export belongs to.
+          description: |-
+            Not stored on an export: a value sent on create or on a full update is dropped, and a GET
+            doesn't return the field. An export isn't owned by an integration; to find the flows and
+            other resources that use it, call `GET /v1/exports/{_id}/dependencies`.
         _connectorId:
           type: string
           format: objectId

package/dist/filestorage.yml

@@ -2047,12 +2047,12 @@ paths:
       x-internal: false
       summary: Get audit log for a file
       description: |-
-        Returns the change history for a file — creation (recorded once the
-        upload finalizes), renames and description edits, moves, content
-        replacements, downloads, deletes, restores, and purges — newest first.
-        Each entry records who made the change, when, and which fields were
-        affected. History survives purging, so a purged file's entries stay
-        readable. Folders have their own route, `GET /v1/folders/{_id}/audit`.
+        Returns the audit entries recorded for a file, newest first, or 204 with
+        no body when it has none. File operations are no longer written to this
+        audit log, so only entries recorded before that change are returned, and
+        a file created since has none. Each entry records who made the change,
+        when, and which fields were affected. Entries survive purging. Folders
+        have their own route, `GET /v1/folders/{_id}/audit`.
       tags:
         - File Storage
       operationId: getStorageFileAudit
@@ -2166,11 +2166,12 @@ paths:
       x-internal: false
       summary: Get audit log for a folder
       description: |-
-        Returns the change history for a folder — creation, renames and
-        description edits, moves, deletes, restores, and purges — newest first.
-        Each entry records who made the change, when, and which fields were
-        affected. History survives purging, so a purged folder's entries stay
-        readable. Files have their own route, `GET /v1/files/{_id}/audit`.
+        Returns the audit entries recorded for a folder, newest first, or 204
+        with no body when it has none. Folder operations are no longer written
+        to this audit log, so only entries recorded before that change are
+        returned, and a folder created since has none. Each entry records who
+        made the change, when, and which fields were affected. Entries survive
+        purging. Files have their own route, `GET /v1/files/{_id}/audit`.
       tags:
         - File Storage
       operationId: getStorageFolderAudit

package/dist/iclient.yml

@@ -324,9 +324,8 @@ paths:
         account: every update must include the full JSON key. An Azure
         service principal keeps its stored `clientSecret` or `certificate`
         when the field is omitted — only a new value replaces it, and
-        `certificate` is never returned. Connections work the other way:
-        re-sending the mask on `PUT /v1/connections/{_id}` clears the stored
-        credential.
+        `certificate` is never returned. A connection keeps a secret re-sent
+        as the mask the same way (`PUT /v1/connections/{_id}`).
       operationId: updateIClient
       tags:
         - iClients

package/dist/import.yml

@@ -8507,7 +8507,8 @@ components:
           x-celigo-ui-override: 'Required by the Event Streams publisher form (fieldDefinitions/resources/imports/import.js: ''topic._topicId'' is required:true, validWhen isNot ''''). The API saves a TopicImport without it, so the requirement is encoded on the request schema to mirror the form and keep publishers bound to a topic.'
           description: |-
             Topic the records are published to. Create or look it up with `GET /v1/topics`; the
-            topic must belong to the same account.
+            topic must belong to the same account. A clone of the import made in the same
+            environment keeps `_topicId`.
           x-celigo-ai-guidance:
             - |-
               An id that is not a topic in the account fails the save with 422 `invalid_ref`
@@ -15842,9 +15843,10 @@ components:
             - 'null'
           format: objectId
           x-celigo-refModel: integrations
-          description: Integration this import belongs to.
-          examples:
-            - 60a2c4e6f321d800129a1a3c
+          description: |-
+            Not stored on an import: a value sent on create or on a full update is dropped, and a GET
+            doesn't return the field. An import isn't owned by an integration; to find the flows and
+            other resources that use it, call `GET /v1/imports/{_id}/dependencies`.
         _connectorId:
           type: string
           format: objectId

package/dist/integration.yml

@@ -4280,7 +4280,9 @@ components:
             When true, the integration is a container for Celigo Sync resources — set it on
             `POST /v1/integrations` before creating syncs in it (`POST /v1/syncs` into an
             integration without it fails with `422 integration_not_for_sync`). Fixed at creation:
-            `PUT /v1/integrations/{_id}` ignores the field in both directions.
+            `PUT /v1/integrations/{_id}` ignores the field in both directions. Keep flows out of
+            it: a flow create isn't refused there. While the integration holds a sync, deleting
+            it fails with 422 "sync <id> must be deleted before you can delete integration <id>".
         aliases:
           type: array
           description: Named aliases that map to specific resources within the integration.
@@ -4448,8 +4450,8 @@ components:
                 Maintained by the platform: added through the integration's topic `register` operations,
                 `POST /v1/topics` with `__integrationIds`, or automatically when a flow in the integration
                 is saved with a step bound to a topic; removed by the `DELETE …/register` operation or when
-                the topic is deleted. Client-sent values are ignored (PUT-verified). Absent on integrations
-                that have never had a topic registered.
+                the topic is deleted. Client-sent values are ignored (PUT-verified). With no topic
+                registered it is an empty array, or absent on older integrations.
               items:
                 type: string
                 format: objectId

package/dist/mcp-server.yml

@@ -4188,7 +4188,7 @@ components:
               x-celigo-ai-guidance:
                 - To change throughput while this is true, write `targetConcurrencyLevel`; a `concurrencyLevel` sent in a PUT returns 200 and changes nothing.
                 - Turning it on copies `concurrencyLevel` into `targetConcurrencyLevel`; turning it off unsets the target and leaves `concurrencyLevel` at its current value, which may be below the old target if a recovery was in progress. A `targetConcurrencyLevel` written while this is false is unset by the save.
-                - These four settings (`concurrencyLevel`, `targetConcurrencyLevel`, `_borrowConcurrencyFromConnectionId`, this flag) accept a credential-free `PATCH /v1/connections/{_id}`. A PUT must re-send the credentials — omitting them or echoing their masked `******` values clears them.
+                - These four settings (`concurrencyLevel`, `targetConcurrencyLevel`, `_borrowConcurrencyFromConnectionId`, this flag) accept a credential-free `PATCH /v1/connections/{_id}`. A PUT replaces the whole document, so send each secret back as its masked `******` value (that keeps it) or as a new value, and never drop one to keep it — an omitted password or `http.encrypted` is cleared, and a static token left out (with no `refreshMethod`) fails the PUT with 422.
             enableMicroBatchForOneToMany:
               type: boolean
               default: true
@@ -5839,7 +5839,9 @@ components:
                     - svc_account
                 password:
                   type: string
-                  description: Password for Basic/Digest/WSSE authentication (encrypted at rest).
+                  description: |-
+                    Password for Basic/Digest/WSSE authentication (encrypted at rest). On update, the
+                    masked `"******"` sent back keeps the stored password; a new value replaces it.
                   writeOnly: true
                   examples:
                     - s3cr3t-p4ssw0rd
@@ -5856,6 +5858,7 @@ components:
                   type: string
                   description: |
                     The API key or bearer token value (encrypted at rest); returned masked as `"******"`.
+                    On update, the mask sent back keeps the stored token; a new value replaces it.
                     Required unless automatic token refresh is configured.
                   examples:
                     - my-api-token-EXAMPLE
@@ -6318,7 +6321,8 @@ components:
             Encrypted custom fields for storing sensitive configuration values (API secrets,
             private keys, etc.) that don't fit standard auth fields. Sent as an object of
             field-name/value pairs; values are encrypted at rest. Returned as the masked
-            string `"******"` on responses. Field definitions are specified in encryptedFields.
+            string `"******"` on responses; on update, that mask sent back keeps the stored values,
+            and a new object replaces them. Field definitions are specified in encryptedFields.
           examples:
             - apiSecret: s3cr3t-value
               signingKey: another-s3cr3t
@@ -8060,6 +8064,7 @@ components:
           type: string
           description: |
             The API key or bearer token value (encrypted at rest); returned masked as `"******"`.
+            On update, the mask sent back keeps the stored token; a new value replaces it.
             Required unless automatic token refresh is configured.
           examples:
             - my-api-token-EXAMPLE

package/dist/sync.yml

@@ -153,7 +153,9 @@ paths:
         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.
+        a sync also registers its connections for the platform's replication runtime: each
+        connection gets `microServices.workerGroup: "DIWorker"` and joins the integration's
+        `_registeredConnectionIds`.
       operationId: createSync
       tags:
         - Syncs
@@ -215,7 +217,8 @@ paths:
                       _connectionId: 6a2a95909e994395f3c2a4e6
                     destination: {}
                     driftPolicy:
-                      dataset: {}
+                      dataset:
+                        added: ignore
                       element: {}
         '400':
           description: |-
@@ -328,12 +331,14 @@ paths:
       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.
+        fields (`schedule`, `timezone`, destination details, the `driftPolicy.element`
+        settings) 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
+        Set `disabled: false` to enable the sync once its source, a complete destination, and
         `historicDateTime` are configured; enabling an incomplete sync fails with
-        `422 sync_not_enabled`.
+        `422 sync_not_enabled`. Always send `disabled`: a PUT that omits it enables a sync
+        whose source, destination and `historicDateTime` are set.
       operationId: updateSync
       tags:
         - Syncs
@@ -356,9 +361,10 @@ paths:
               $ref: '#/components/schemas/Request'
             examples:
               configure:
-                summary: Name the sync and set its destination
+                summary: Name the sync and set its destination, keeping it disabled
                 value:
                   name: Salesforce Demo Sync
+                  disabled: true
                   schedule: '? 0 */6 * * *'
                   timezone: America/New_York
                   historicDateTime: '2022-07-04T18:30:00.000Z'
@@ -443,13 +449,19 @@ paths:
             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`).
+            (`size_limit_exceeded`), the drift policy is inconsistent
+            (`drift_policy_invalid_setup`), or the destination's application differs from
+            the integration's other syncs or from the sync's saved destination.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
               examples:
+                mixed_destination_types:
+                  summary: Another destination application in the same integration
+                  value:
+                    errors:
+                      - message: The destination type for all the syncs under an integration must be same.
                 not_ready_to_enable:
                   summary: Enabling an incomplete sync
                   value:
@@ -464,6 +476,8 @@ paths:
         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.
+        The sync's job records stay until their `purgeAt`, and while they exist the deleted
+        integration that held the sync can't be purged from the recycle bin.
       operationId: deleteSync
       tags:
         - Syncs
@@ -710,9 +724,11 @@ paths:
       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`.
+        single request can mix both. An update replaces the dataset's `name`, `tableName` and
+        `exportProperties` with what the item carries, so send each item whole. One failing
+        item rejects the whole batch, valid items included, and datasets the batch doesn't
+        name are left unchanged. The response body is empty — read back the saved datasets
+        with `GET /v1/syncs/{_syncId}/datasets`.
       operationId: upsertDatasetsForSync
       tags:
         - Syncs
@@ -761,12 +777,14 @@ paths:
                     exportProperties:
                       type: delta
               update:
-                summary: Switch an existing dataset to append mode
+                summary: Switch an existing dataset to append mode, sending the whole item
                 value:
                   - _id: 6a559b547885d8f93921c2ba
                     name: Account
                     enable: true
                     ingestionMode: append
+                    exportProperties:
+                      type: delta
                     dataElements:
                       - name: Id
                         enable: true
@@ -801,7 +819,8 @@ paths:
           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
+            primary key, a `tableName` is already taken (or, for an enabled dataset, matches
+            another dataset's table name in another letter case), 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`).
@@ -1043,7 +1062,7 @@ paths:
                   value:
                     errors:
                       - code: sync_job_already_queued
-                        message: A sync job is already queued for this sync.
+                        message: Another instance for this sync is already queued or running. Please try again later.
         '422':
           description: |-
             The sync is disabled and cannot be run.
@@ -1058,7 +1077,7 @@ paths:
                   value:
                     errors:
                       - code: invalid_sync
-                        message: The sync is disabled.
+                        message: Sync disabled. Please enable your sync and try again.
   /v1/syncs/{_syncId}/syncJobs:
     get:
       x-internal: false
@@ -1286,7 +1305,7 @@ paths:
                   value:
                     errors:
                       - code: sync_jobs_not_found
-                        message: No cancellable sync jobs found.
+                        message: 'Sync jobs not found for syncId: <syncId>'
         '409':
           description: |-
             Cancellation is already in progress for the remaining jobs.
@@ -1740,7 +1759,7 @@ paths:
                   value:
                     errors:
                       - code: sync_job_invalid_integration_id
-                        message: The integration is not sync-enabled.
+                        message: The integration <integrationId> is not allowed to have syncs
                 missing:
                   summary: Integration does not exist
                   value:
@@ -2856,7 +2875,10 @@ paths:
         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.
+        is the `name` to reference there. Read an export's record structure (`isExport=true`)
+        or an HTTP-connector object's columns through
+        `GET /v1/di/metadata/sync/{_syncId}/connections/{_connectionId}/datasets/{datasetName}/details`
+        once a draft sync exists.
       operationId: getConnectionDatasetDetails
       tags:
         - Syncs
@@ -3149,6 +3171,11 @@ paths:
               schema:
                 $ref: '#/components/schemas/Error'
               examples:
+                export_or_connector_object:
+                  summary: An export or HTTP-connector object (read it through the sync-scoped route)
+                  value:
+                    errors:
+                      - message: 'A required parameter is missing: _datasetId'
                 unknown_dataset:
                   summary: Table does not exist in the source
                   value:
@@ -3763,7 +3790,8 @@ components:
         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`.
+        events, readable via `GET /v1/di/resource/syncs/{_syncId}/events`. A PUT that omits the
+        `element` settings clears them.
       properties:
         dataset:
           type: object
@@ -3777,7 +3805,9 @@ components:
               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.
+                tables manually. A sync created through the API starts at `ignore`, and a PUT
+                that omits `driftPolicy` or sends an empty `dataset` object keeps the stored
+                value, so moving back from `automate` takes an explicit `ignore`.
               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.
@@ -3800,8 +3830,8 @@ components:
       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.
+        New syncs start as disabled drafts; a sync can be enabled once its source, a complete
+        destination, and `historicDateTime` are configured.
       required:
         - _id
         - _userId
@@ -3909,8 +3939,8 @@ components:
             destination yet. The destination application is the connection's own type
             (`rdbms.type` for warehouse connections), so `database` and `schema` are read in that
             application's terms — Google BigQuery treats them as the GCP project and the dataset.
-            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
+            A `database` and `schema` pair can back only one sync, even across integrations — reusing one,
+            in any letter case, fails with `422 duplicate_destination_host` — and all syncs in an
             integration must target the same destination application type.
           properties:
             _connectionId:
@@ -3991,8 +4021,9 @@ components:
       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.
+        the `driftPolicy.element` settings) are cleared, not preserved, so send the complete
+        desired configuration on every PUT. A PUT that omits `disabled` returns the sync enabled
+        (`disabled: false`) when its source, destination and `historicDateTime` are set.
       required:
         - source
       x-celigo-ai-guidance:
@@ -4015,6 +4046,16 @@ components:
           integration created without it fails the sync create with 422 integration_not_for_sync
           ("An integration is suppose to have either flows or syncs but not both"), and PUT
           /v1/integrations/{_id} ignores the syncs field, so the only fix is a new integration.
+        - |-
+          Send disabled explicitly on every PUT. A PUT that omits it returns disabled: false once
+          the sync's source, destination and historicDateTime are complete; disabled: true in the
+          body keeps it disabled.
+        - |-
+          Creating a sync, and saving its destination, registers the connections with the
+          replication runtime: the platform sets microServices.workerGroup to "DIWorker" on each
+          connection (a system change in its audit log) and adds them to the integration's
+          _registeredConnectionIds. Deleting the syncs that used a connection cleared its worker
+          group when no other sync used it.
       properties:
         _integrationId:
           type: string
@@ -4044,11 +4085,12 @@ components:
             - 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`.
+            When true, the sync neither runs on schedule nor accepts on-demand runs. A PUT that
+            omits it returns the sync enabled once its source, destination and `historicDateTime`
+            are set, so send it on every PUT. Set to false once the source, a complete
+            destination, and `historicDateTime` are configured; enabling an incomplete sync fails with
+            `422 sync_not_enabled`. Datasets aren't checked: a sync with none enables.
           examples:
             - false
         schedule:
@@ -4101,9 +4143,10 @@ components:
             enabled. The destination application is the connection's own type (`rdbms.type`
             for warehouse connections), so `database` and `schema` are read in that
             application's terms — Google BigQuery treats them as the GCP project and the
-            dataset. 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.
+            dataset. A `database` and `schema` pair, in any letter case, can back only one sync,
+            even across integrations (`422 duplicate_destination_host`, "Duplicate destination host found"). All syncs in
+            an integration must target the same destination application type, and a sync's
+            destination type can't change once saved.
           x-celigo-ai-guidance:
             - |-
               Send the block complete or not at all. A partial block is rejected in the destination's
@@ -4115,10 +4158,26 @@ components:
               `002003` "Database 'UNDEFINED' does not exist" error.
             - |-
               Saving a complete destination connects to the warehouse to create the schema
-              (dataset) when it is missing. An unreachable host or unusable credentials fail the
-              save with the connection's error — 422 `invalid_host` for SQL Server,
-              `big_query_unexpected_error` for BigQuery — and no sync document is created or
-              updated; fix the connection rather than changing database or schema names.
+              (dataset) when it is missing. When the host resolves but the connection fails, or
+              the credentials are unusable, the save fails with the connection's error — 422
+              `invalid_host` for SQL Server, `big_query_unexpected_error` for BigQuery — and no
+              sync document is created or updated; fix the connection rather than changing
+              database or schema names.
+            - |-
+              A destination host that doesn't resolve can leave the save without a response for
+              more than 30 seconds, with nothing saved (seen on SQL Server and Snowflake
+              connections). Read the sync back before sending it again.
+            - |-
+              The duplicate_destination_host check compares the database and schema names
+              without regard to case. It refused a pair already used by another sync even when
+              the host, the destination type, the source connection and the integration all
+              differed, so give each sync a schema of its own.
+            - |-
+              A destination whose application differs from the other syncs' in the same
+              integration fails with 422 "The destination type for all the syncs under an
+              integration must be same.", and changing a saved destination to another application
+              fails with 422 "Destination connection type is not same as the previous destination
+              connection type". Another warehouse type needs a new sync in its own integration.
             - |-
               Microsoft SQL Server validates `database` and `schema` as identifiers (start with a
               letter or underscore; letters, digits, underscore or `$`; at most 128 characters) and
@@ -4417,7 +4476,9 @@ components:
         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.
+        An update replaces `name`, `tableName` and `exportProperties` with what the item
+        carries, clearing any it omits; an omitted `ingestionMode` or `dataElements` keeps its
+        saved value. Send each update item whole.
       x-celigo-ai-guidance:
         - |-
           Create items with externalId only; update items with _id only. Sending both on one
@@ -4431,6 +4492,16 @@ components:
         - |-
           To scaffold a dataset without replicating it yet, send name, externalId, enable: false
           and no dataElements — the platform then replicates all columns once enabled.
+        - |-
+          A partial update item such as {_id, enable: false} is accepted and clears the dataset's
+          name and tableName — on an export-backed dataset too, whose create requires tableName.
+          Build each update item from the dataset's read-back, minus externalId and the read-only
+          fields.
+        - |-
+          Selections are not checked against the source at save: an externalId the catalog
+          doesn't list, and dataElements names a catalog table doesn't have (even an enabled
+          merge key), save without an error. Take externalId values from the connection's
+          dataset catalog and column names from its details read.
       properties:
         _id:
           type: string
@@ -4483,7 +4554,9 @@ components:
             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.
+            `isExport` is true. The save-time check matches exact names only; a name that
+            differs only in case saves, and enabling one of the two then fails with 422
+            "Another dataset in this sync resolves to the same destination table".
           examples:
             - account
         isExport:
@@ -5016,9 +5089,13 @@ components:
         stage:
           type: string
           readOnly: true
-          description: Pipeline stage where the error occurred.
+          description: |-
+            Pipeline stage where the error occurred. `init` errors come from the checks a run
+            makes before it extracts — `di_ping_failure` when a connection's host can't be
+            reached — and carry no table.
           examples:
             - extraction
+            - init
         datasetName:
           type: string
           readOnly: true

package/dist/tool.yml

@@ -7568,7 +7568,7 @@ components:
               x-celigo-ai-guidance:
                 - To change throughput while this is true, write `targetConcurrencyLevel`; a `concurrencyLevel` sent in a PUT returns 200 and changes nothing.
                 - Turning it on copies `concurrencyLevel` into `targetConcurrencyLevel`; turning it off unsets the target and leaves `concurrencyLevel` at its current value, which may be below the old target if a recovery was in progress. A `targetConcurrencyLevel` written while this is false is unset by the save.
-                - These four settings (`concurrencyLevel`, `targetConcurrencyLevel`, `_borrowConcurrencyFromConnectionId`, this flag) accept a credential-free `PATCH /v1/connections/{_id}`. A PUT must re-send the credentials — omitting them or echoing their masked `******` values clears them.
+                - These four settings (`concurrencyLevel`, `targetConcurrencyLevel`, `_borrowConcurrencyFromConnectionId`, this flag) accept a credential-free `PATCH /v1/connections/{_id}`. A PUT replaces the whole document, so send each secret back as its masked `******` value (that keeps it) or as a new value, and never drop one to keep it — an omitted password or `http.encrypted` is cleared, and a static token left out (with no `refreshMethod`) fails the PUT with 422.
             enableMicroBatchForOneToMany:
               type: boolean
               default: true
@@ -9219,7 +9219,9 @@ components:
                     - svc_account
                 password:
                   type: string
-                  description: Password for Basic/Digest/WSSE authentication (encrypted at rest).
+                  description: |-
+                    Password for Basic/Digest/WSSE authentication (encrypted at rest). On update, the
+                    masked `"******"` sent back keeps the stored password; a new value replaces it.
                   writeOnly: true
                   examples:
                     - s3cr3t-p4ssw0rd
@@ -9236,6 +9238,7 @@ components:
                   type: string
                   description: |
                     The API key or bearer token value (encrypted at rest); returned masked as `"******"`.
+                    On update, the mask sent back keeps the stored token; a new value replaces it.
                     Required unless automatic token refresh is configured.
                   examples:
                     - my-api-token-EXAMPLE
@@ -9698,7 +9701,8 @@ components:
             Encrypted custom fields for storing sensitive configuration values (API secrets,
             private keys, etc.) that don't fit standard auth fields. Sent as an object of
             field-name/value pairs; values are encrypted at rest. Returned as the masked
-            string `"******"` on responses. Field definitions are specified in encryptedFields.
+            string `"******"` on responses; on update, that mask sent back keeps the stored values,
+            and a new object replaces them. Field definitions are specified in encryptedFields.
           examples:
             - apiSecret: s3cr3t-value
               signingKey: another-s3cr3t
@@ -11440,6 +11444,7 @@ components:
           type: string
           description: |
             The API key or bearer token value (encrypted at rest); returned masked as `"******"`.
+            On update, the mask sent back keeps the stored token; a new value replaces it.
             Required unless automatic token refresh is configured.
           examples:
             - my-api-token-EXAMPLE
@@ -19890,7 +19895,8 @@ components:
           x-celigo-ui-override: 'Required by the Event Streams publisher form (fieldDefinitions/resources/imports/import.js: ''topic._topicId'' is required:true, validWhen isNot ''''). The API saves a TopicImport without it, so the requirement is encoded on the request schema to mirror the form and keep publishers bound to a topic.'
           description: |-
             Topic the records are published to. Create or look it up with `GET /v1/topics`; the
-            topic must belong to the same account.
+            topic must belong to the same account. A clone of the import made in the same
+            environment keeps `_topicId`.
           x-celigo-ai-guidance:
             - |-
               An id that is not a topic in the account fails the save with 422 `invalid_ref`
@@ -24718,9 +24724,10 @@ components:
             - 'null'
           format: objectId
           x-celigo-refModel: integrations
-          description: Integration this import belongs to.
-          examples:
-            - 60a2c4e6f321d800129a1a3c
+          description: |-
+            Not stored on an import: a value sent on create or on a full update is dropped, and a GET
+            doesn't return the field. An import isn't owned by an integration; to find the flows and
+            other resources that use it, call `GET /v1/imports/{_id}/dependencies`.
         _connectorId:
           type: string
           format: objectId
@@ -30403,7 +30410,9 @@ components:
           description: |-
             Topic this listener subscribes to. Create or look it up with `GET /v1/topics`; the
             topic must belong to the same account. Pointing an existing listener at a different
-            topic starts a new subscription, read from `startPosition`.
+            topic starts a new subscription, read from `startPosition`. A clone made in the same
+            environment — of this export, or of a flow that contains it — keeps `_topicId`, so the
+            copy becomes another listener on the topic once its flow is enabled.
           x-celigo-ai-guidance:
             - |-
               An id that is not a topic in the account fails the save with 422 `invalid_ref`
@@ -37517,7 +37526,10 @@ components:
             - 'null'
           format: objectId
           x-celigo-refModel: integrations
-          description: Integration this export belongs to.
+          description: |-
+            Not stored on an export: a value sent on create or on a full update is dropped, and a GET
+            doesn't return the field. An export isn't owned by an integration; to find the flows and
+            other resources that use it, call `GET /v1/exports/{_id}/dependencies`.
         _connectorId:
           type: string
           format: objectId

package/dist/topic.yml

@@ -616,9 +616,11 @@ paths:
       summary: Purge retained messages
       description: |-
         Removes every retained message from the topic while keeping the topic, its retention setting,
-        and its subscriptions; the purge cannot be undone. Records an audit entry with `event: purge`
-        and `fieldChanges[0].fieldPath: messages`. To remove the topic itself, use
-        `DELETE /v1/topics/{_id}`.
+        and its subscriptions; the purge cannot be undone. Positions keep counting: the next message
+        published takes the next offset, subscribed listeners receive it as before, and a listener
+        whose saved position was purged resumes from the earliest message still retained. Records an
+        audit entry with `event: purge` and `fieldChanges[0].fieldPath: messages`. To remove the topic
+        itself, use `DELETE /v1/topics/{_id}`.
       operationId: purgeTopicMessages
       tags:
         - Topics
@@ -977,15 +979,19 @@ paths:
                         purge: Retained messages were purged, or the topic was permanently removed from the recycle bin.
                     source:
                       type: string
-                      description: How the change was initiated. Restores from the recycle bin are recorded as `system`.
+                      description: |-
+                        How the change was initiated. A change made through the Celigo CLI is recorded as
+                        `cli` — deletes, restores from the recycle bin, and message purges included.
                       enum:
                         - api
                         - ui
                         - system
+                        - cli
                       x-enumDescriptions:
                         api: Change made via the REST API.
                         ui: Change made through the Celigo UI.
                         system: Change made by an automated platform process.
+                        cli: Change made through the Celigo CLI.
                     time:
                       type: string
                       format: date-time
@@ -1651,13 +1657,16 @@ components:
         hasCursor:
           type: boolean
           description: |-
-            When true, the export has committed a read position on this topic and its next run resumes
-            from `offset`. False when the export has never consumed the topic, when its last committed
-            position has expired from the stream, or when it does not listen to this topic at all — a
-            listener without a cursor starts from its own `topic.startPosition` (`latest` or `earliest`).
-            A listener whose flow is disabled keeps its position; a listener saved without
-            `type: "stream"`, or whose flow has not been enabled since the listener was saved, has
-            never subscribed and reports false.
+            When true, the listener is subscribed to this topic and its next run resumes from `offset`.
+            The position appears when the listener's flow goes from disabled to enabled, before anything
+            is read: at the end of the stream under `topic.startPosition: latest`, at the first retained
+            message under `earliest`. False when the listener has never subscribed — it was saved
+            without `type: "stream"`, its flow has not gone from disabled to enabled since it was saved
+            (a flow created enabled never subscribes), or it does not listen to this topic. A listener
+            whose flow is disabled keeps its position. When the message at that position is no longer
+            retained — it expired past `retentionMs` or was purged — the listener still reports true
+            with the old `offset`, and its next run resumes from the earliest message still retained,
+            whatever its `startPosition`.
           examples:
             - true
             - false
@@ -1666,8 +1675,9 @@ components:
           minimum: -1
           description: |-
             Zero-based position of the next message the export will read. `-1` when `hasCursor` is
-            false. The position counts from the start of the stream, so while no message has expired
-            the retained message count minus `offset` is the listener's backlog.
+            false. The position counts from the start of the stream and keeps counting after a purge,
+            so while no message has expired or been purged the retained message count minus `offset`
+            is the listener's backlog.
           examples:
             - 1287
             - -1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.145",
+  "version": "0.2.147",
   "private": false,
   "description": "Public OpenAPI bundles (dist/) and the celigo-cli lint schema pack (schemas.json).",
   "keywords": [

package/schemas.json

@@ -1,7 +1,7 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "325c42fa",
+		"iasCommit": "53d752ea",
 		"generatedAt": "2026-10-21"
 	},
 	"roots": {