@celigo/api-specs 0.2.206 → 0.2.208

package/dist/export.yml

@@ -1661,6 +1661,21 @@ components:
             - shopify
             - stripe
             - custom
+        formType:
+          type: string
+          enum:
+            - simple
+            - webhook
+          x-enumDescriptions:
+            simple: Simple form, the default for a named provider (e.g. `shopify`, `stripe`).
+            webhook: Full webhook form, the default when `provider` is `custom` or omitted.
+          description: |-
+            Which webhook export form the UI uses to edit this listener. A value sent on create or
+            update wins (case-insensitive — `Simple` is stored as `simple`); a PUT that omits it
+            keeps the stored value, and a new export without one gets the default for its
+            `provider`. Every webhook export GET carries it.
+          examples:
+            - webhook
         verify:
           type: string
           x-celigo-ui-override: Required by the webhook export form (verify is required:true). Encoded to mirror the form so builders produce connectable configurations.
@@ -5958,6 +5973,8 @@ components:
           A stream export that resolves no snapshot mode — neither `snapshotMode` nor a
           `snapshot.mode` entry in `properties` — is rejected 422 ("Expected field: snapshotMode
           to be present").
+      required:
+        - paths
       properties:
         captureMode:
           type: string
@@ -6067,13 +6084,13 @@ components:
             - Never author or modify this field — the platform owns the stream position.
         paths:
           type: array
+          minItems: 1
           items:
             type: string
           description: |-
-            Dot-notation paths within each raw change event to retain in the emitted record. MongoDB
-            listeners default to `["payload"]` (the whole change document); SQL Server, PostgreSQL and
-            MySQL listeners commonly select `payload.after`, `payload.op`, and related fields to expose
-            the changed row and operation type. The MySQL listener form offers `payload.after`,
+            Dot-notation paths within each raw change event to retain in the emitted record, such as
+            `payload.after` (the changed row or document) and `payload.op` (the operation type).
+            The MySQL listener form offers `payload.after`,
             `payload.before`, `schema`, `payload.source`, `payload.op`, `payload.transaction`,
             `payload.ts_ms`, `payload.ts_us` and `payload.ts_ns`, preselecting `payload.after`; it has
             no `updateDescription`-derived options and no `payload.id`. The MySQL listener
@@ -6081,8 +6098,9 @@ components:
             as the row before an update or delete (needs `binlog_row_image=FULL`), `op` as `c` / `u` /
             `d` / `r` (insert / update / delete / snapshot read) and `source` as the database, table,
             binlog file and position.
+          x-celigo-ui-override: 'Required by every listener form (MongoDB, SQL Server, PostgreSQL, and MySQL: cdc.paths is a required:true multiselect with defaultValue [''payload.after'']). Encoded here to mirror the forms so builders produce complete listener configurations.'
           examples:
-            - - payload
+            - - payload.after
             - - payload.after
               - payload.op
             - - payload.after
@@ -6110,7 +6128,9 @@ components:
             serialized first, followed by optional keys such as `field.exclude.list`,
             `column.include.list`, or `snapshot.collection.filter.overrides.<db>.<collection>`.
             On save the API also lifts `snapshot.mode` / `capture.mode` entries into the typed
-            `snapshotMode` / `captureMode` fields.
+            `snapshotMode` / `captureMode` fields. When one body carries both with different values,
+            the `snapshot.mode` entry wins on SQL Server, PostgreSQL and MySQL listeners, and the typed
+            `snapshotMode` wins on a MongoDB listener.
 
             The MySQL listener form offers six keys: `snapshot.mode` (preselected `no_data`) and five
             optional comma-separated regular-expression lists — `table.exclude.list` (matched on
@@ -6125,6 +6145,11 @@ components:
               The API persists any key sent here without validating it against the connector, so a
               MongoDB or PostgreSQL key on a MySQL listener saves cleanly and does nothing — author only
               the keys the listener's form offers.
+            - |-
+              On SQL Server, PostgreSQL, and MySQL listeners every save appends one more
+              `snapshot.mode` entry that repeats the resolved mode, so a GET response lists it twice
+              and each GET-then-PUT round trip adds another copy. Send a single `snapshot.mode`
+              entry: drop the trailing repeats before you PUT a fetched export back.
           items:
             type: object
             required:
@@ -12111,7 +12136,7 @@ components:
         {
           "type": "stream",
           "rdbms": { "tables": "public.orders,public.customers" },
-          "cdc": { "properties": [{ "name": "snapshot.mode", "value": "no_data" }] }
+          "cdc": { "properties": [{ "name": "snapshot.mode", "value": "no_data" }], "paths": ["payload.after"] }
         }
         ```
         A MySQL listener names its tables as `database.table` (MySQL has no schema layer):
@@ -16399,7 +16424,9 @@ components:
         `POST /v1/exports/preview` reads the `mockOutput` in its request body, not the saved one. For
         an export the preview supports (an HTTP export, for example), a body that carries it (as an
         export read back with GET does) returns that snapshot as a lone `parse` stage without calling
-        the source; remove `mockOutput` from the body to preview live records.
+        the source; remove `mockOutput` from the body to preview live records. A body mock with an
+        empty or missing `page_of_records` still skips the source and returns 200 with empty `data`
+        and an empty `parse` stage.
 
         **Limitations**
 
@@ -16754,7 +16781,9 @@ components:
               `stream` is accepted only on MongoDB and RDBMS exports (SQL Server,
               PostgreSQL or MySQL connections) and on Event Streams listeners
               (`adaptorType: TopicExport`); every other adaptor rejects the save
-              with `unsupported_export_type`. A MongoDB or RDBMS stream export
+              with `unsupported_export_type`, and a MariaDB connection is rejected
+              with 422 `missing_required_field` on `type` ("RDBMS stream export not
+              supported for mariadb"). A MongoDB or RDBMS stream export
               must carry `cdc.snapshotMode` (and `cdc.captureMode` on MongoDB) —
               omitting them fails with 422 `missing_required_field` on those paths.
           enum:
@@ -17962,17 +17991,27 @@ components:
         dataURIs:
           type: array
           description: |-
-            URIs for any files produced by the preview (e.g. file-based exports
-            writing to cloud storage). Empty for non-file adaptors.
+            Links to the records in the source system. On an export preview, one
+            entry per record in `data`: a link to the record when one is available
+            (for example the export's `dataURITemplate` rendered for that record),
+            otherwise `null`, as on an HTTP export without a template; absent when
+            the preview returned no records and when a `mockOutput` in the request
+            body answered.
           items:
-            type: string
+            type:
+              - string
+              - 'null'
         dataRecordTraceKeys:
           type: array
           description: |-
             Trace keys for the records in this preview — one per record,
-            correlating stage outputs to their source record.
+            correlating stage outputs to their source record; `null` for a record
+            that has no key. Absent when the preview returned no records and
+            captured no keys, and when a `mockOutput` in the request body answered.
           items:
-            type: string
+            type:
+              - string
+              - 'null'
         stages:
           type: array
           description: |-
@@ -18035,12 +18074,11 @@ components:
             type: object
             additionalProperties: true
         traceKeysDuplicate:
-          type: array
+          type: boolean
           description: |-
-            Trace keys that collided during the preview — a diagnostic for
-            trace-key generation; rarely non-empty in practice.
-          items:
-            type: string
+            When true, two or more records in this preview share a trace key, so
+            the export's `traceKeyTemplate` does not identify records uniquely.
+            Absent whenever `dataRecordTraceKeys` is absent.
     PreviewRequest:
       type: object
       description: Request body for previewing export data

package/dist/flow.yml

@@ -8824,17 +8824,27 @@ components:
         dataURIs:
           type: array
           description: |-
-            URIs for any files produced by the preview (e.g. file-based exports
-            writing to cloud storage). Empty for non-file adaptors.
+            Links to the records in the source system. On an export preview, one
+            entry per record in `data`: a link to the record when one is available
+            (for example the export's `dataURITemplate` rendered for that record),
+            otherwise `null`, as on an HTTP export without a template; absent when
+            the preview returned no records and when a `mockOutput` in the request
+            body answered.
           items:
-            type: string
+            type:
+              - string
+              - 'null'
         dataRecordTraceKeys:
           type: array
           description: |-
             Trace keys for the records in this preview — one per record,
-            correlating stage outputs to their source record.
+            correlating stage outputs to their source record; `null` for a record
+            that has no key. Absent when the preview returned no records and
+            captured no keys, and when a `mockOutput` in the request body answered.
           items:
-            type: string
+            type:
+              - string
+              - 'null'
         stages:
           type: array
           description: |-
@@ -8897,12 +8907,11 @@ components:
             type: object
             additionalProperties: true
         traceKeysDuplicate:
-          type: array
+          type: boolean
           description: |-
-            Trace keys that collided during the preview — a diagnostic for
-            trace-key generation; rarely non-empty in practice.
-          items:
-            type: string
+            When true, two or more records in this preview share a trace key, so
+            the export's `traceKeyTemplate` does not identify records uniquely.
+            Absent whenever `dataRecordTraceKeys` is absent.
     DependencyEntry:
       type: object
       description: A single resource that depends on the queried resource.

package/dist/import.yml

@@ -5681,6 +5681,7 @@ components:
               description: |-
                 Target table for the bulk load.
                 Must reference an existing table accessible with the connection's credentials; schema-qualified names are supported.
+                On Snowflake, the temporary staging table that precedes the load is created in the connection's default schema (`rdbms.snowflake.schema` on the connection), not in this table's schema.
               x-celigo-ai-guidance:
                 - |-
                   The name of the target table within the relational database management system
@@ -8567,9 +8568,23 @@ components:
           description: |-
             Tool resource this import executes. The tool supplies the input schema, routing, page
             processors, and output mapping; the import runs that tool when records reach it. Required —
-            a `ToolImport` has no behavior without a tool to run.
+            a `ToolImport` has no behavior without a tool to run. Saving the import fails with 422 when the
+            tool has no routers, a step still being set up, or a branch that does not merge back; the
+            message names the tool.
           x-celigo-ai-guidance:
             - Reference to the Celigo Tool resource this wrapper invokes.
+            - |-
+              Finish the tool before saving its wrapper: a create or update of this import fails with 422
+              tool_empty_router when the tool has no `routers` (missing or empty; the message reads "…has
+              no steps. Add at least one step to the tool, then save again."), router_setup_in_progress
+              when a step is still being set up (setupInProgress), and tool_dangling_branch when a branch
+              has no nextRouterId ("outputRouter" ends the tool). Fix the tool with PUT /v1/tools/{_id},
+              then save the import again.
+            - |-
+              A save that passes doesn't mean the tool runs: a branch with empty `pageProcessors` passes
+              it, and the tool then fails at invoke with 400 tool_empty_router. Creating a parent tool, or
+              a disabled flow, whose step is this wrapper is not checked either: both saved while the
+              wrapped tool had no routers.
             - |-
               Required.
               The Tool must already exist;
@@ -8973,16 +8988,20 @@ components:
               The `key` + `batchSize` combination has not been probed (it needs a B2B Manager
               account) — treat it as unverified, neither allowed nor forbidden.
         encrypt:
-          type: boolean
+          type: string
+          enum:
+            - pgp
+          x-enumDescriptions:
+            pgp: Encrypt the file with PGP before it is written.
           description: |-
-            Whether to encrypt the output file.
-
-            **Values**
-            - `true`: Encrypt the file (requires PGP configuration)
-            - `false`: No encryption
-
-            **Default:** `false`
-          default: false
+            Encrypts the output file; omit it for an unencrypted file. `pgp` requires
+            `pgp.symmetricKeyAlgorithm` and a connection holding the recipient's public key
+            (`pgp.publicKey`) — without either the save fails with 422 `missing_required_field`.
+            The public-key check runs first: on a connection without one, any `encrypt` value,
+            `false` included, fails with 422 `missing_required_field` "pgp publicKey is required
+            when encrypt is selected to perform file encryption." before the value is checked.
+            Blob (file-transfer) imports follow the same rule and return `encrypt` and `pgp` even
+            without `file.type`.
         csv:
           type: object
           description: CSV-specific configuration. Only used when `type` is `"csv"`.
@@ -9149,8 +9168,8 @@ components:
         pgp:
           type: object
           description: |-
-            PGP encryption settings applied when encrypt is true; selects the symmetric cipher and the
-            signing hash. The connection must hold the recipient's public key.
+            PGP encryption settings applied when `encrypt` is `pgp`; selects the symmetric cipher and
+            the signing hash. The connection must hold the recipient's public key.
           properties:
             symmetricKeyAlgorithm:
               type: string
@@ -9167,9 +9186,10 @@ components:
                 3des: Triple DES block cipher (legacy).
                 aes128: AES with a 128-bit key.
                 aes192: AES with a 192-bit key.
-                aes256: AES with a 256-bit key (default, recommended).
-              default: aes256
-              description: Symmetric cipher used to encrypt the file body; aes256 unless the recipient requires another.
+                aes256: AES with a 256-bit key (recommended).
+              description: |-
+                Symmetric cipher used to encrypt the file body; required when `encrypt` is `pgp` (no
+                server default). Use aes256 unless the recipient requires another.
               examples:
                 - aes256
                 - 3des
@@ -18086,8 +18106,9 @@ components:
       type: object
       description: |-
         The outcome of running one input record through an import — one element
-        per record, in input order — shared by `POST /v1/imports/{_id}/invoke`
-        and the virtual import `POST /v1/connections/{_id}/import`. A record the
+        per record, in input order — shared by `POST /v1/imports/{_id}/invoke`,
+        the virtual import `POST /v1/connections/{_id}/import` and its
+        integration-scoped forms. A record the
         import itself ignored before any request carries `ignored: true` and the
         `stage` that dropped it; a record the destination accepted carries its
         parsed response; a record the destination rejected — or that the

package/dist/mcp-server.yml

@@ -3874,7 +3874,7 @@ components:
           description: |-
             Required label for the limit, echoed verbatim in the 429 error message
             that rejected clients receive — name it the way consumers should read
-            it. A missing or empty name is rejected with 422.
+            it. A missing or empty name is rejected with 422 `missing_required_field`.
           examples:
             - Server-level rate limit
             - Per-user rate limit
@@ -5280,10 +5280,12 @@ components:
                 `targetConcurrencyLevel`. While true, `targetConcurrencyLevel` is the throughput lever: a
                 `concurrencyLevel` sent in a PUT is ignored, and one sent in a PATCH is stored but the
                 recovery machinery moves it back toward the target. Recovery never runs on `ftp`
-                connections: FTP errors aren't treated as rate limits.
+                connections: FTP errors aren't treated as rate limits. A rate limit hit by a Tool
+                invocation (`POST /v1/tools/{_id}/invoke`) or an export preview
+                (`POST /v1/exports/preview`) leaves the connection's concurrency as it is.
               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.
+                - 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` sent on a create that sets this false, or with the write that turns this off, is dropped; on a connection where this is already false, writing one fails with 422 `invalid_concurrency_level`.
                 - 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.
                 - On a create, while this is true, set the level with `targetConcurrencyLevel`: on `http`, `ftp`, `rdbms` and `mongodb` connections the save stores the target sent, or the adaptor's default without one (1 for `ftp`, 5 for `rdbms` and `mongodb`, 25 for `http` where the license's `concurrency` is at least 25), as both fields, whatever `concurrencyLevel` the body carried. A create that sends this as `false` keeps its `concurrencyLevel`.
                 - On an `ftp` connection recovery never runs, and transfer threads are `ftp.multiThreadCount`.
@@ -5920,8 +5922,10 @@ components:
             While `autoRecoverRateLimitErrors` is true, a create sets `concurrencyLevel` to this value, and a
             create that omits it gets 1 for both. Auto-recovery never runs on FTP connections (FTP errors
             aren't treated as rate limits), so nothing climbs back to it.
-            Kept on a `PUT` that omits it, like `concurrencyLevel`; unset by the save while
-            `autoRecoverRateLimitErrors` is false.
+            Kept on a `PUT` that omits it, like `concurrencyLevel`. A create that sends
+            `autoRecoverRateLimitErrors` false, or a write that turns it off, drops it; on a connection
+            where the flag is already false, sending it fails with 422 `invalid_concurrency_level`
+            ("cannot be set when autoRecoverRateLimitErrors is false").
           minimum: 1
           maximum: 50
           examples:
@@ -6662,9 +6666,10 @@ components:
             Higher values increase throughput but may trigger API rate limits.
             Set this based on the target API's rate limit documentation.
             Send no more than the account's licensed maximum (25 standard, 50 with an Environments license).
-            A decimal is rejected with 422 `invalid_field_value` on every write (the same rule applies to every
-            adaptor's `concurrencyLevel` and `targetConcurrencyLevel`, and to `ftp.multiThreadCount`).
-            Platform-managed while `autoRecoverRateLimitErrors` is true — a create or PUT ignores the value (a create without `targetConcurrencyLevel` stores 25 where the license's `concurrency` is at least 25) and the recovery machinery moves it toward the target; set `targetConcurrencyLevel` instead.
+            A create, a PATCH, and a PUT while `autoRecoverRateLimitErrors` is false reject a decimal with 422
+            `invalid_field_value` and a boolean or a non-numeric string with 422 `invalid_concurrency_level`
+            ("must be an integer").
+            Platform-managed while `autoRecoverRateLimitErrors` is true — a create still checks the value but stores the target in its place (25 without a `targetConcurrencyLevel`, where the license's `concurrency` is at least 25), a PUT ignores it without checking it, and the recovery machinery moves it toward the target; set `targetConcurrencyLevel` instead.
             At level 1 an import's pages run one at a time, so a record's existence lookup and write finish before the next record's start (measured on a single import); the import's `idLockTemplate` serializes only same-key records and leaves the rest parallel.
           minimum: 1
           maximum: 50
@@ -6677,7 +6682,9 @@ components:
             Ceiling the platform climbs back to after rate-limit recovery, in steps of 25% of this value.
             Writing it also sets `concurrencyLevel` to the same value and stops any recovery in progress.
 
-            Honored only while `autoRecoverRateLimitErrors` is true; ignored, and unset, when it is false.
+            Honored only while `autoRecoverRateLimitErrors` is true. A create that sends the flag as false, or a
+            write that turns it off, drops it; on a connection where the flag is already false, sending it fails with 422
+            `invalid_concurrency_level` ("cannot be set when autoRecoverRateLimitErrors is false").
           minimum: 1
           maximum: 50
           examples:
@@ -7448,6 +7455,26 @@ components:
               examples:
                 - - rate_limit_exceeded
                   - too_many_requests
+            failHeaders:
+              type: array
+              description: |
+                Response-header rules for detecting rate limiting, each a header `name` with an
+                optional `value`. A rule with an empty `name` fails the save with 422
+                `invalid_header_format`.
+              items:
+                type: object
+                required:
+                  - name
+                properties:
+                  name:
+                    type: string
+                    description: Response header the rule checks.
+                  value:
+                    type: string
+                    description: Header value the rule checks; omit to check the header alone.
+              examples:
+                - - name: X-RateLimit-Remaining
+                    value: '0'
             limit:
               type: number
               minimum: 1
@@ -8076,9 +8103,21 @@ components:
                 - COMPUTE_WH
             schema:
               type: string
-              description: |
-                Default Snowflake schema. If omitted, queries must fully-qualify table names
-                (e.g., DATABASE.SCHEMA.TABLE).
+              description: |-
+                Default schema for the session: unqualified table names in queries resolve here, and
+                optimized bulk load imports create their temporary staging table here even when the
+                destination table is schema-qualified — so the connection's role must be able to
+                create that table in it. When blank, optimized bulk load uses PUBLIC.
+              x-celigo-ai-guidance:
+                - |-
+                  When this names a schema the session cannot resolve — Snowflake reports it as not
+                  existing or not authorized for the role, and the session is left without a current
+                  schema — every optimized bulk load fails at the staging step with code `query_fail`
+                  and the message "Failed to run the bulk load query. Err: [TempTableQuery] The
+                  provided schema is invalid: <this value>" (the connector's rewrite of Snowflake's
+                  "This session does not have a current schema"). Fix: set this to a schema the role
+                  can create the staging table in — normally the destination table's own schema — or
+                  point the import at a second Snowflake connection with that default schema.
               examples:
                 - PUBLIC
             role: