@celigo/api-specs 0.2.168 → 0.2.169

package/dist/api.yml

@@ -5932,6 +5932,14 @@ components:
             Do NOT include the protocol prefix (e.g., use "ftp.example.com", not "sftp://ftp.example.com").
           examples:
             - sftp.example.com
+          x-celigo-ai-guidance:
+            - |-
+              Don't point a connection at this environment's own Celigo file server (its
+              `endpoint.hostname`, with a username ending in `@<identifier>`, the server's own
+              `identifier`): a flow reads those files from Celigo Storage directly, and the save
+              refuses that pairing with 422 `fileserver_loopback_not_supported`. Another
+              environment's file server on the same host, such as a trading partner's, is an
+              ordinary connection.
         port:
           type: number
           description: |
@@ -6055,7 +6063,8 @@ components:
           description: |
             Maximum number of concurrent file transfer operations.
             FTP servers often have low connection limits — keep this value conservative.
-            Send no more than the account's licensed maximum (25 standard, 50 with an Environments license).
+            Send no more than the account's licensed maximum, the license's `concurrency` (25 standard,
+            50 with an Environments license).
             Unlike the rest of the `ftp` object, a `PUT` that omits this field keeps the stored value instead of clearing it.
           minimum: 1
           maximum: 50
@@ -6079,7 +6088,7 @@ components:
           description: |-
             Number of parallel transfer threads for this FTP connection. Must be a
             whole number — decimals are rejected on save. Send no more than the
-            account's licensed concurrency maximum. On
+            account's licensed concurrency maximum, the same as for `concurrencyLevel`. On
             save the value is mirrored into `userConcurrencyLevel` (and into
             `userTargetConcurrencyLevel` when auto-recovery of rate-limit errors
             is active with `targetConcurrencyLevel` set); clearing it clears the

package/dist/connection.yml

@@ -1185,7 +1185,8 @@ paths:
         `POST /v1/connections/{_id}/ping`, with no request body to send. Runs the adaptor's ping
         routine against the connection identified by `_id` to verify its credentials and network
         configuration still work; no data is read, written, or modified. An `http` connection with
-        no `http.ping` answers `{code: 200}` without sending any request.
+        no `http.ping` answers `{code: 200}` without sending any request, unless it authorizes with
+        an authorization code and holds no token yet: that one answers `missing_token`.
 
         Inspect the response body, not the HTTP status, to determine the outcome: success and
         adaptor-level failures both return HTTP 200 — success is `{code: 200}`, failures are
@@ -1259,8 +1260,10 @@ paths:
           whichever verb the client supports. Both verbs return HTTP 200 with {code: 200} on
           success and HTTP 200 with {errors: [...]} on adaptor-level failure, so inspect the body,
           not the status code. On an `http` connection, {code: 200} shows reachability only once
-          `http.ping` is set: with no ping configured, nothing is sent and the answer is always
-          {code: 200}.
+          `http.ping` is set: with no ping configured, nothing is sent and the answer is
+          {code: 200}, or `missing_token` for an authorization-code OAuth connection that holds no
+          token yet. An OAuth connection requests a token only when the target answers 401, so a
+          ping of an endpoint that needs no authentication passes without testing the OAuth setup.
     post:
       x-internal: false
       summary: Ping an existing connection
@@ -1270,8 +1273,11 @@ paths:
         adaptor-specific (HTTP sends the `http.ping` request, RDBMS/JDBC open a driver session,
         MCP issues a tools/list, NetSuite/Salesforce do a token or session validation). An `http`
         connection with no `http.ping` passes with `{code: 200}` without sending any request, so
-        the ping proves nothing about it until a ping is configured. The request body is optional
-        and ignored.
+        the ping proves nothing about it until a ping is configured; one that authorizes with an
+        authorization code and holds no token yet answers `missing_token` instead. An OAuth
+        connection requests a token only when the target answers 401, so a ping of an endpoint
+        that needs no authentication passes without testing the OAuth setup. The request body
+        is optional and ignored.
 
         Inspect the response body, not the HTTP status, to determine the outcome: success and
         adaptor-level failures both return HTTP 200 — success is `{code: 200}`, failures are
@@ -1383,8 +1389,10 @@ paths:
           - Return connection status and any error details
 
           Exception: an `http` connection with no `http.ping` answers {code: 200} without sending
-          any request, so it proves nothing until a ping (ideally one that needs the connection's
-          credentials) is configured.
+          any request (or `missing_token`, for an authorization-code OAuth connection that holds no
+          token yet), so it proves nothing until a ping is configured — one that needs the
+          connection's credentials, since an OAuth connection requests a token only when the target
+          answers 401.
   /v1/connections/{_id}/proxy:
     post:
       x-internal: false
@@ -2942,6 +2950,8 @@ paths:
         `/v1/connections/{_id}/oauth2` is an alias that answers identically. The URL's
         `state` token is one-time and expires quickly, so request a fresh one if the flow is
         interrupted, then poll `GET /v1/connections/{_id}` until `needsAuthorization` is `false`.
+        On a connection that uses PKCE (an iClient with `oauth2.pkceCodeChallengeMethod`), each call
+        issues a new `code_challenge`, so send the user to the most recent URL only.
 
         The URL's `redirect_uri` is the account's Celigo callback
         (`https://integrator.io/connection/oauth2callback` on North America), which the provider's
@@ -4780,6 +4790,14 @@ components:
             Do NOT include the protocol prefix (e.g., use "ftp.example.com", not "sftp://ftp.example.com").
           examples:
             - sftp.example.com
+          x-celigo-ai-guidance:
+            - |-
+              Don't point a connection at this environment's own Celigo file server (its
+              `endpoint.hostname`, with a username ending in `@<identifier>`, the server's own
+              `identifier`): a flow reads those files from Celigo Storage directly, and the save
+              refuses that pairing with 422 `fileserver_loopback_not_supported`. Another
+              environment's file server on the same host, such as a trading partner's, is an
+              ordinary connection.
         port:
           type: number
           description: |
@@ -4903,7 +4921,8 @@ components:
           description: |
             Maximum number of concurrent file transfer operations.
             FTP servers often have low connection limits — keep this value conservative.
-            Send no more than the account's licensed maximum (25 standard, 50 with an Environments license).
+            Send no more than the account's licensed maximum, the license's `concurrency` (25 standard,
+            50 with an Environments license).
             Unlike the rest of the `ftp` object, a `PUT` that omits this field keeps the stored value instead of clearing it.
           minimum: 1
           maximum: 50
@@ -4927,7 +4946,7 @@ components:
           description: |-
             Number of parallel transfer threads for this FTP connection. Must be a
             whole number — decimals are rejected on save. Send no more than the
-            account's licensed concurrency maximum. On
+            account's licensed concurrency maximum, the same as for `concurrencyLevel`. On
             save the value is mirrored into `userConcurrencyLevel` (and into
             `userTargetConcurrencyLevel` when auto-recovery of rate-limit errors
             is active with `targetConcurrencyLevel` set); clearing it clears the

package/dist/enduser.yml

@@ -2847,6 +2847,14 @@ components:
             Do NOT include the protocol prefix (e.g., use "ftp.example.com", not "sftp://ftp.example.com").
           examples:
             - sftp.example.com
+          x-celigo-ai-guidance:
+            - |-
+              Don't point a connection at this environment's own Celigo file server (its
+              `endpoint.hostname`, with a username ending in `@<identifier>`, the server's own
+              `identifier`): a flow reads those files from Celigo Storage directly, and the save
+              refuses that pairing with 422 `fileserver_loopback_not_supported`. Another
+              environment's file server on the same host, such as a trading partner's, is an
+              ordinary connection.
         port:
           type: number
           description: |
@@ -2970,7 +2978,8 @@ components:
           description: |
             Maximum number of concurrent file transfer operations.
             FTP servers often have low connection limits — keep this value conservative.
-            Send no more than the account's licensed maximum (25 standard, 50 with an Environments license).
+            Send no more than the account's licensed maximum, the license's `concurrency` (25 standard,
+            50 with an Environments license).
             Unlike the rest of the `ftp` object, a `PUT` that omits this field keeps the stored value instead of clearing it.
           minimum: 1
           maximum: 50
@@ -2994,7 +3003,7 @@ components:
           description: |-
             Number of parallel transfer threads for this FTP connection. Must be a
             whole number — decimals are rejected on save. Send no more than the
-            account's licensed concurrency maximum. On
+            account's licensed concurrency maximum, the same as for `concurrencyLevel`. On
             save the value is mirrored into `userConcurrencyLevel` (and into
             `userTargetConcurrencyLevel` when auto-recovery of rate-limit errors
             is active with `targetConcurrencyLevel` set); clearing it clears the

package/dist/eventreport.yml

@@ -43,8 +43,9 @@ paths:
         `startTime` must be within the last 30 days and the span to `endTime` must not exceed 3 days.
         If `endTime` is omitted, the server defaults it to the current time. Poll
         `GET /v1/eventreports/{_id}` until `status` is `completed`, then download the CSV via
-        `GET /v1/eventreports/{_id}/signedURL`. The create response includes `_requestedByUserId`;
-        subsequent GET responses replace this with the `requestedByUser` object (name + email).
+        `GET /v1/eventreports/{_id}/signedURL`; generation can take several minutes. The create
+        response includes `_requestedByUserId`; subsequent GET responses replace this with the
+        `requestedByUser` object (name + email).
       requestBody:
         required: true
         content:
@@ -94,7 +95,42 @@ paths:
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '422':
-          $ref: '#/components/responses/422-unprocessable-entity'
+          description: |-
+            The window is out of bounds -- `startTime` more than 30 days back, `endTime` before
+            `startTime`, or a span over 3 days -- or `_flowIds` is empty. No report is created.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                span_over_three_days:
+                  summary: Window longer than 3 days
+                  value:
+                    errors:
+                      - field: endTime
+                        code: invalid_range
+                        message: For event report, the time gap between start and end time can't exceed 3 days.
+                start_over_thirty_days:
+                  summary: Start more than 30 days back
+                  value:
+                    errors:
+                      - field: startTime
+                        code: invalid_starttime
+                        message: The start time for the event report can't go beyond 30 days.
+                end_before_start:
+                  summary: endTime before startTime
+                  value:
+                    errors:
+                      - field: startTime
+                        code: invalid_range
+                        message: The end time can't be before than start time.
+                no_flows:
+                  summary: Empty _flowIds
+                  value:
+                    errors:
+                      - field: type
+                        code: invalid_flowevents
+                        message: Please select the flows for which the flow event report needs to be generated.
     get:
       x-internal: false
       operationId: listEventReports
@@ -227,6 +263,10 @@ paths:
         The URL is valid for approximately 15 minutes. Only works when the report `status` is
         `completed` -- requesting it in any other status returns 400. If the URL has expired,
         call this endpoint again to get a fresh one.
+
+        The file is served with `Content-Encoding: gzip`, so download it with a client that decodes
+        it (`curl --compressed`) or gunzip it afterwards. Its columns start `traceKey`, `time`,
+        `type`, `timeTaken`, `_flowJobId`.
       parameters:
         - name: _id
           in: path
@@ -670,19 +710,6 @@ components:
                 errors:
                   - code: invalid_request
                     message: The request body failed validation.
-    422-unprocessable-entity:
-      description: |
-        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/Error'
-          examples:
-            default:
-              value:
-                errors:
-                  - code: unprocessable_entity
-                    message: The request could not be processed due to a semantic error.
     404-not-found:
       description: |
         Not found. The requested resource does not exist or is not visible to the caller.

package/dist/mcp-server.yml

@@ -4679,6 +4679,14 @@ components:
             Do NOT include the protocol prefix (e.g., use "ftp.example.com", not "sftp://ftp.example.com").
           examples:
             - sftp.example.com
+          x-celigo-ai-guidance:
+            - |-
+              Don't point a connection at this environment's own Celigo file server (its
+              `endpoint.hostname`, with a username ending in `@<identifier>`, the server's own
+              `identifier`): a flow reads those files from Celigo Storage directly, and the save
+              refuses that pairing with 422 `fileserver_loopback_not_supported`. Another
+              environment's file server on the same host, such as a trading partner's, is an
+              ordinary connection.
         port:
           type: number
           description: |
@@ -4802,7 +4810,8 @@ components:
           description: |
             Maximum number of concurrent file transfer operations.
             FTP servers often have low connection limits — keep this value conservative.
-            Send no more than the account's licensed maximum (25 standard, 50 with an Environments license).
+            Send no more than the account's licensed maximum, the license's `concurrency` (25 standard,
+            50 with an Environments license).
             Unlike the rest of the `ftp` object, a `PUT` that omits this field keeps the stored value instead of clearing it.
           minimum: 1
           maximum: 50
@@ -4826,7 +4835,7 @@ components:
           description: |-
             Number of parallel transfer threads for this FTP connection. Must be a
             whole number — decimals are rejected on save. Send no more than the
-            account's licensed concurrency maximum. On
+            account's licensed concurrency maximum, the same as for `concurrencyLevel`. On
             save the value is mirrored into `userConcurrencyLevel` (and into
             `userTargetConcurrencyLevel` when auto-recovery of rate-limit errors
             is active with `targetConcurrencyLevel` set); clearing it clears the

package/dist/state.yml

@@ -35,6 +35,10 @@ tags:
       Values must be non-empty JSON objects or arrays. Bare primitives,
       `null`, and empty containers (`{}`, `[]`) are rejected.
 
+      Each export, import or integration holds at most 10 keys, and the
+      global scope at most 100. A new key past the limit is refused with 422
+      `limit_reached`; replacing an existing key still works.
+
       Prefer resource-scoped state over global state when the data belongs
       to a specific export, import, or integration. State keys are upserted —
       PUT creates if absent, replaces if present. There is no PATCH; send the
@@ -243,15 +247,25 @@ paths:
         '422':
           description: |-
             The request body is empty, or is an empty container (`{}` or
-            `[]`).
+            `[]`), or the key is new and the account already holds 100 global
+            keys.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
-              example:
-                errors:
-                  - code: missing_request_body
-                    message: Please send state as request body in the PUT request.
+              examples:
+                missing_request_body:
+                  summary: Empty body or empty container
+                  value:
+                    errors:
+                      - code: missing_request_body
+                        message: Please send state as request body in the PUT request.
+                limit_reached:
+                  summary: The account already holds 100 global keys
+                  value:
+                    errors:
+                      - code: limit_reached
+                        message: 'Cannot save state, allowed number of states already reached for user : 60f1a2b3c4d5e6f7a8b9c0d1'
     delete:
       x-internal: false
       operationId: deleteGlobalStateKey
@@ -710,15 +724,24 @@ paths:
         '422':
           description: |-
             The request body is empty, or is an empty container (`{}` or
-            `[]`).
+            `[]`), or the key is new and the resource already holds 10 keys.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
-              example:
-                errors:
-                  - code: missing_request_body
-                    message: Please send state as request body in the PUT request.
+              examples:
+                missing_request_body:
+                  summary: Empty body or empty container
+                  value:
+                    errors:
+                      - code: missing_request_body
+                        message: Please send state as request body in the PUT request.
+                limit_reached:
+                  summary: The resource already holds 10 keys
+                  value:
+                    errors:
+                      - code: limit_reached
+                        message: 'Cannot save state, allowed number of states already reached for export : 66a1f2c3b4d5e6f7a8b9c0d1'
     delete:
       x-internal: false
       operationId: deleteResourceStateKey

package/dist/tool.yml

@@ -8187,6 +8187,14 @@ components:
             Do NOT include the protocol prefix (e.g., use "ftp.example.com", not "sftp://ftp.example.com").
           examples:
             - sftp.example.com
+          x-celigo-ai-guidance:
+            - |-
+              Don't point a connection at this environment's own Celigo file server (its
+              `endpoint.hostname`, with a username ending in `@<identifier>`, the server's own
+              `identifier`): a flow reads those files from Celigo Storage directly, and the save
+              refuses that pairing with 422 `fileserver_loopback_not_supported`. Another
+              environment's file server on the same host, such as a trading partner's, is an
+              ordinary connection.
         port:
           type: number
           description: |
@@ -8310,7 +8318,8 @@ components:
           description: |
             Maximum number of concurrent file transfer operations.
             FTP servers often have low connection limits — keep this value conservative.
-            Send no more than the account's licensed maximum (25 standard, 50 with an Environments license).
+            Send no more than the account's licensed maximum, the license's `concurrency` (25 standard,
+            50 with an Environments license).
             Unlike the rest of the `ftp` object, a `PUT` that omits this field keeps the stored value instead of clearing it.
           minimum: 1
           maximum: 50
@@ -8334,7 +8343,7 @@ components:
           description: |-
             Number of parallel transfer threads for this FTP connection. Must be a
             whole number — decimals are rejected on save. Send no more than the
-            account's licensed concurrency maximum. On
+            account's licensed concurrency maximum, the same as for `concurrencyLevel`. On
             save the value is mirrored into `userConcurrencyLevel` (and into
             `userTargetConcurrencyLevel` when auto-recovery of rate-limit errors
             is active with `targetConcurrencyLevel` set); clearing it clears the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.168",
+  "version": "0.2.169",
   "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": "80cddc9b",
+		"iasCommit": "750b2035",
 		"generatedAt": "2026-10-22"
 	},
 	"roots": {