@celigo/api-specs 0.2.168 → 0.2.170

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
@@ -10094,9 +10113,12 @@ components:
           type: array
           description: |-
             Errors recorded for the record. `source: application` with
-            `stage: apiCall` means the request reached the destination and its
-            answer was the failure; the destination's response body rides in
-            `message`.
+            `stage: apiCall` marks the import's call to the destination. Usually
+            the destination's answer was the failure, and its response body rides
+            in `message`; but a request the import couldn't build carries the same
+            pair and was never sent, such as a URL template that failed to render
+            (`code: handlebars_template_parse_error`, "Failed to generate request
+            url from template ...").
           items:
             type: object
             properties:

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/export.yml

@@ -6273,9 +6273,12 @@ components:
             request fields are interpreted. When omitted, the standard HTTP form is used.
           x-celigo-ai-guidance:
             - |-
-              The value changes only the editor, never the request: the same `http.body` is sent
-              identically under `http` and `graph_ql`, and the value can be changed on an existing
-              export without touching the body.
+              The value picks the editor and changes one thing in a GraphQL request: under `graph_ql`
+              and `assistant_graphql`, a `variables` member stored as a JSON string is parsed and sent
+              as an object, while under `http` it is sent as the string. A body whose `variables` is
+              already an object goes out unchanged under `graph_ql` and `http`. Live-verified 2026-10-22 with
+              export previews against an echo endpoint: a string `variables` under `graph_ql`,
+              `assistant_graphql` and `http`, and an object `variables` under `graph_ql` and `http`.
             - |-
               The GraphQL form reads `http.body` as the JSON envelope `{"query", "operationName",
               "variables"}` and shows each member in its own editor, recompiling the envelope on save
@@ -6492,9 +6495,15 @@ components:
               XML, etc.).
             - |-
               A GraphQL request is this field holding the stringified JSON envelope `{"query":
-              "<document>", "operationName": "...", "variables": ...}` whatever `formType` says;
-              `variables` may be an object or a JSON-encoded string, and a templated variables value
-              must stay inside a string so the body remains parseable JSON at rest (see `formType`).
+              "<document>", "operationName": "...", "variables": ...}`. `variables` may be an object
+              or a JSON-encoded string, and a string is sent as an object only under the GraphQL
+              form types (see `formType`). Variables with unquoted Handlebars (a number, `null`, an
+              `{{#if}}` block) must be a string so the body remains parseable JSON at rest; string
+              values inside that string sit two JSON levels deep, so write them as
+              `\"{{jsonEncode record.x}}\"` with double braces: a plain `{{record.x}}`, or a
+              triple-brace `jsonEncode`, fails a value holding a quote with 422 `invalid_json`.
+              An object or array there is `{{jsonSerialize record.x}}`, also with double braces;
+              triple braces fail the same way.
             - |-
               You can use handlebars expressions to create dynamic content:
               ```
@@ -7318,7 +7327,7 @@ components:
                 - response.records
             lastPageStatusCode:
               type: integer
-              description: HTTP status code that signals the last page, replacing the default behavior of treating 404 as the end of pagination. When this status is received, paging stops and the response is not treated as an error. Set only when the API uses a non-404 code (such as 204 or 400) to indicate no more pages.
+              description: 'HTTP status code that signals the last page, replacing the default behavior of treating 404 as the end of pagination. When this status is received (any code but `200` paired with `lastPagePath`), paging stops and the response is not treated as an error. Set it when the API uses a non-404 code (such as 204 or 400) to indicate no more pages, or to `200` together with `lastPagePath` when the last page is an ordinary 200 response: then the response is parsed, its records are kept, and paging stops only when `lastPagePath` matches `lastPageValues`.'
               x-celigo-ai-guidance:
                 - Specifies a custom HTTP status code that indicates the last page of results.
                 - |-
@@ -7353,36 +7362,45 @@ components:
                 - |-
                   ## TECHNICAL DETAILS
 
-                  When this status code is received, the system:
+                  When this status code is received (any code but `200` paired with
+                  `lastPagePath`), the system:
                   - Stops the pagination process
                   - Considers the data collection complete
                   - Does not treat the response as an error
                   - Does not attempt to process any response body
 
                   IMPORTANT: Only set this if your API explicitly uses a non-404 status code
-                  to indicate the end of pagination. Setting this incorrectly could cause
-                  premature termination of data collection or error handling issues.
+                  to indicate the end of pagination, or to `200` with `lastPagePath` (below).
+                  Setting this incorrectly could cause premature termination of data
+                  collection or error handling issues.
+                - |-
+                  `200` is the exception, for an API whose last page is an ordinary 200 response:
+                  together with `lastPagePath`, paging stops on the first 200 whose `lastPagePath`
+                  value matches `lastPageValues`, and that page's records are kept. Live-verified
+                  2026-10-22 with token paging.
               examples:
                 - 204
                 - 400
                 - 500
             lastPagePath:
               type: string
-              description: JSON path to a response-body field that signals the end of pagination, such as a "has more" flag or a cursor that empties on the last page. Must be used with `lastPageValues`, which lists the values at this path that stop paging. If the path does not exist in a response, the condition is not considered met.
+              description: 'JSON path to a response-body field that signals the end of pagination, such as a "has more" flag or a cursor that empties on the last page. Must be used with `lastPageValues`, which lists the values at this path that stop paging. If the path does not exist in a response, the condition is not considered met. With `method: token` the path is read only on a response whose status code equals `lastPageStatusCode`, so pair it with `lastPageStatusCode: 200` for an ordinary last page; with `method: body` it is read on every response.'
               x-celigo-ai-guidance:
                 - |-
                   ## FIELD BEHAVIOR
 
                   - OPTIONAL: Only needed for APIs with field-based pagination completion signals
-                  - Works with all pagination methods
+                  - Accepted on all pagination methods; when it is read depends on the method (see
+                    the method note below)
                   - Used in conjunction with lastPageValues
                   - JSON path notation to a field in the response body
                 - |-
                   ## IMPLEMENTATION GUIDANCE
 
                   This field is used when an API indicates the last page through a field
-                  in the response body rather than using HTTP status codes. The system
-                  checks this path in each response to determine if pagination is complete.
+                  in the response body rather than using HTTP status codes. Which responses
+                  the system checks it on depends on the paging method (see the method note
+                  below).
 
                   Common patterns include:
 
@@ -7416,8 +7434,19 @@ components:
                   "lastPageValues": ["false", "0"]
                   ```
 
-                  IMPORTANT: The path is evaluated against each response using JSON path notation.
-                  If the path doesn't exist in the response, the condition is not considered met.
+                  IMPORTANT: The path is evaluated using JSON path notation, on the responses the
+                  method note below describes. If the path doesn't exist in the response, the
+                  condition is not considered met.
+                - |-
+                  On `method: token` the path is checked only on a response whose status code equals
+                  `lastPageStatusCode`. For an API whose last page is an ordinary 200 (a GraphQL
+                  `pageInfo.hasNextPage: false`), set `lastPageStatusCode: 200` with it; without that,
+                  paging goes on while the token at `path` is non-empty, so a last page that still
+                  carries a cursor costs one more request. On `method: body` the path is read on
+                  every response, with no status code needed. Live-verified 2026-10-22 against an echo
+                  endpoint for `token` (two requests without `lastPageStatusCode`, one with 200) and
+                  `body` (stopped on the second response); `page`, `skip` and `url` paging were not
+                  verified.
               examples:
                 - meta.isLastPage
                 - pagination.hasMore
@@ -7841,22 +7870,30 @@ components:
                   - '201'
             errorPath:
               type: string
-              description: Path to the error message in the response body. The value at this path is included in error logs and error records when the API returns an error.
+              description: Path to the error message in the response body. The value at this path is included in error logs and error records when the API returns an error; without it, the message is the whole response body.
               examples:
                 - error.message
                 - errorMessage
                 - errors[0].detail
+                - errors[0].message
             failPath:
               type: string
-              description: Path to a response field that signals failure even when the HTTP status code is 200 — the inverse of `successPath`. Must be used with `failValues`.
+              description: Path to a response field that signals failure even when the HTTP status code is 200 — the inverse of `successPath`. With `failValues`, the response fails when the value there matches one of them; without, when the path holds a truthy value. A path that resolves to an array matches only when the array has exactly one element.
               x-celigo-ai-guidance:
+                - Similar to `successPath` but inverted logic — checks for failure indicators.
                 - |-
-                  Similar to `successPath` but inverted logic — checks for failure indicators.
-                  Must be used together with `failValues`.
+                  A path that resolves to an array matches only when the array has exactly one
+                  element. GraphQL APIs usually report a failed query with HTTP 200 and an `errors` array:
+                  `failPath: errors` fails the response for one error and lets two or more through,
+                  so set `failPath` (and `errorPath`) to `errors[0].message`. Without a fail path the
+                  response counts as a success, and an export whose `resourcePath` points into
+                  `data` returns zero records with no error. Live-verified 2026-10-22 with export
+                  and import previews against an echo endpoint.
               examples:
                 - error
                 - status
                 - result.error
+                - errors[0].message
             failValues:
               type: array
               items:
@@ -10674,8 +10711,9 @@ components:
                 Number of records the RESTlet returns per request (default 1000). This, not the
                 export's `pageSize`, sizes each NetSuite call; the export keeps requesting until the
                 search is exhausted. Larger batches reduce round-trips but raise NetSuite governance
-                and memory use per call; tune to the record's size. In a test run or preview the
-                request is capped at the export's `pageSize` (default 20) instead.
+                and memory use per call; tune to the record's size. The RESTlet caps a call at 1000,
+                so a larger value acts as 1000. In a test run or preview the request is capped at the
+                export's `pageSize` (default 20) instead.
               examples:
                 - 100
                 - 200
@@ -10954,8 +10992,9 @@ components:
               type: array
               description: |-
                 Search columns the RESTlet returns for each matching record. With a saved search,
-                omit this to return the search's own result columns; an ad-hoc search (no
-                `searchId`) must list its columns here.
+                the RESTlet returns the search's own result columns followed by any listed here: a
+                list adds columns and never removes one of the search's, so remove a column in the
+                saved search itself. An ad-hoc search (no `searchId`) must list its columns here.
               x-celigo-ai-guidance:
                 - |-
                   Entries are objects keyed by `name` — `[{"name": "internalid"}, {"name":

package/dist/flow.yml

@@ -6637,9 +6637,12 @@ components:
         source:
           type: string
           description: |-
-            Step stage or system the error came from, such as `application` (raised from the
-            destination's response), `connection`, a hook (`pre_save_page_hook`,
-            `post_response_map_hook`) or a filter (`output_filter`). `GET /v1/errors/filterMetadata`
+            Step stage or system the error came from, such as `application`, `connection`, a hook
+            (`pre_save_page_hook`, `post_response_map_hook`) or a filter (`output_filter`).
+            `application` covers the step's whole call to the external system, not only its answer:
+            besides errors the destination returned, it marks a request that never got an answer,
+            such as a URL template that failed to render (`handlebars_template_parse_error`) or a
+            refused connection, so read `code` and `message` with it. `GET /v1/errors/filterMetadata`
             lists the source values the errors filter accepts.
           examples:
             - application

package/dist/import.yml

@@ -1572,12 +1572,25 @@ components:
               Use `assistant_graphql` as the default value if there is a connector available
               for the system and the connector supports GraphQL.
             - |-
-              The value selects the editor only. Each `http.body[]` entry stays a template STRING — a
+              The value selects the editor and changes one thing in a GraphQL request: under
+              `graph_ql` and `assistant_graphql`, a `variables` member stored as a JSON string is
+              parsed and sent as an object, while under `http` it is sent as the string; an object
+              `variables` goes out unchanged under `graph_ql` and `http`. Live-verified 2026-10-22 with import
+              previews against an echo endpoint: a string `variables` under `graph_ql`,
+              `assistant_graphql` and `http`, and an object `variables` under `graph_ql` and `http`.
+            - |-
+              Each `http.body[]` entry stays a template STRING — a
               stringified `{"query", "operationName", "variables"}` envelope, one per operation for the
               update/create pair (`http.body[0]` / `http.body[1]`); never an object entry, which is stored
               as-is and does not render. The GraphQL form parses that string to show each member in its
               own field and re-stringifies it on save; an entry that is not parseable JSON at rest renders
-              those fields empty, so keep templated variables inside a JSON string value.
+              those fields empty, so keep templated variables inside a JSON string value. When
+              `variables` is itself a JSON string, the string values inside it sit two JSON levels
+              deep: write them as `\"{{jsonEncode record.x}}\"` with double braces, because a plain
+              `{{record.x}}`, or a triple-brace `jsonEncode`, fails a record whose value holds a quote
+              with 422 `invalid_json` before the request is sent. An object or array there is
+              `{{jsonSerialize record.x}}`, also with double braces; `{{{jsonSerialize record.x}}}`
+              fails the same way (live-verified 2026-10-22).
             - |-
               Create GraphQL imports on a `graph_ql` connection (or a connector connection bound to its
               GraphQL API): that setup offers the Form view toggle between the GraphQL editor and the
@@ -2394,13 +2407,20 @@ components:
 
                 Each entry is a DOT-PATH STRING, or null for an operation
                 with no ID path configured. When not specified, the platform
-                looks for standard `id` or `_id` fields automatically.
+                looks for standard `id` or `_id` fields automatically. When
+                set, a response with no value at the path fails the record
+                with `missing_id`, quoting the response.
               x-celigo-ai-guidance:
                 - |-
                   Common LLM mistake:
                   splitting a single dot-path like ``"data.id"`` into array segments ``["data",
                   "id"]`` — DO NOT do this.
                   See the ``response`` object docs above.
+                - |-
+                  For a GraphQL mutation, point it at the id only a successful call returns
+                  (``["data.customerCreate.customer.id"]``): a 200 that carries top-level ``errors``
+                  or the mutation's ``userErrors`` then fails the record with ``missing_id`` instead
+                  of counting as written. Live-verified 2026-10-22 against an echo endpoint.
               examples:
                 - - id
                 - - data.id
@@ -2474,11 +2494,23 @@ components:
                 available, set both — the platform evaluates ``successPath``
                 first and falls through to ``failPath`` only when the
                 success check is inconclusive.
+
+                Without ``failValues``, a truthy value at the path fails
+                the response. A path that resolves to an array matches only
+                when the array has exactly one element.
+              x-celigo-ai-guidance:
+                - |-
+                  A GraphQL API usually reports a failed mutation with HTTP 200 and an ``errors`` array, which
+                  counts as written when no rule catches it. ``failPath: ["errors"]`` fails the record
+                  for one error and lets two or more through; use ``["errors[0].message"]`` with
+                  ``errorPath: "errors[0].message"`` so the record fails with the server's message.
+                  Live-verified 2026-10-22 with import runs against an echo endpoint.
               examples:
                 - - error
                 - - success
                 - - error
                   - error
+                - - errors[0].message
             failValues:
               type: array
               items:
@@ -17547,9 +17579,12 @@ components:
           type: array
           description: |-
             Errors recorded for the record. `source: application` with
-            `stage: apiCall` means the request reached the destination and its
-            answer was the failure; the destination's response body rides in
-            `message`.
+            `stage: apiCall` marks the import's call to the destination. Usually
+            the destination's answer was the failure, and its response body rides
+            in `message`; but a request the import couldn't build carries the same
+            pair and was never sent, such as a URL template that failed to render
+            (`code: handlebars_template_parse_error`, "Failed to generate request
+            url from template ...").
           items:
             type: object
             properties:

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
@@ -13378,12 +13387,25 @@ components:
               Use `assistant_graphql` as the default value if there is a connector available
               for the system and the connector supports GraphQL.
             - |-
-              The value selects the editor only. Each `http.body[]` entry stays a template STRING — a
+              The value selects the editor and changes one thing in a GraphQL request: under
+              `graph_ql` and `assistant_graphql`, a `variables` member stored as a JSON string is
+              parsed and sent as an object, while under `http` it is sent as the string; an object
+              `variables` goes out unchanged under `graph_ql` and `http`. Live-verified 2026-10-22 with import
+              previews against an echo endpoint: a string `variables` under `graph_ql`,
+              `assistant_graphql` and `http`, and an object `variables` under `graph_ql` and `http`.
+            - |-
+              Each `http.body[]` entry stays a template STRING — a
               stringified `{"query", "operationName", "variables"}` envelope, one per operation for the
               update/create pair (`http.body[0]` / `http.body[1]`); never an object entry, which is stored
               as-is and does not render. The GraphQL form parses that string to show each member in its
               own field and re-stringifies it on save; an entry that is not parseable JSON at rest renders
-              those fields empty, so keep templated variables inside a JSON string value.
+              those fields empty, so keep templated variables inside a JSON string value. When
+              `variables` is itself a JSON string, the string values inside it sit two JSON levels
+              deep: write them as `\"{{jsonEncode record.x}}\"` with double braces, because a plain
+              `{{record.x}}`, or a triple-brace `jsonEncode`, fails a record whose value holds a quote
+              with 422 `invalid_json` before the request is sent. An object or array there is
+              `{{jsonSerialize record.x}}`, also with double braces; `{{{jsonSerialize record.x}}}`
+              fails the same way (live-verified 2026-10-22).
             - |-
               Create GraphQL imports on a `graph_ql` connection (or a connector connection bound to its
               GraphQL API): that setup offers the Form view toggle between the GraphQL editor and the
@@ -14200,13 +14222,20 @@ components:
 
                 Each entry is a DOT-PATH STRING, or null for an operation
                 with no ID path configured. When not specified, the platform
-                looks for standard `id` or `_id` fields automatically.
+                looks for standard `id` or `_id` fields automatically. When
+                set, a response with no value at the path fails the record
+                with `missing_id`, quoting the response.
               x-celigo-ai-guidance:
                 - |-
                   Common LLM mistake:
                   splitting a single dot-path like ``"data.id"`` into array segments ``["data",
                   "id"]`` — DO NOT do this.
                   See the ``response`` object docs above.
+                - |-
+                  For a GraphQL mutation, point it at the id only a successful call returns
+                  (``["data.customerCreate.customer.id"]``): a 200 that carries top-level ``errors``
+                  or the mutation's ``userErrors`` then fails the record with ``missing_id`` instead
+                  of counting as written. Live-verified 2026-10-22 against an echo endpoint.
               examples:
                 - - id
                 - - data.id
@@ -14280,11 +14309,23 @@ components:
                 available, set both — the platform evaluates ``successPath``
                 first and falls through to ``failPath`` only when the
                 success check is inconclusive.
+
+                Without ``failValues``, a truthy value at the path fails
+                the response. A path that resolves to an array matches only
+                when the array has exactly one element.
+              x-celigo-ai-guidance:
+                - |-
+                  A GraphQL API usually reports a failed mutation with HTTP 200 and an ``errors`` array, which
+                  counts as written when no rule catches it. ``failPath: ["errors"]`` fails the record
+                  for one error and lets two or more through; use ``["errors[0].message"]`` with
+                  ``errorPath: "errors[0].message"`` so the record fails with the server's message.
+                  Live-verified 2026-10-22 with import runs against an echo endpoint.
               examples:
                 - - error
                 - - success
                 - - error
                   - error
+                - - errors[0].message
             failValues:
               type: array
               items:
@@ -30946,9 +30987,12 @@ components:
             request fields are interpreted. When omitted, the standard HTTP form is used.
           x-celigo-ai-guidance:
             - |-
-              The value changes only the editor, never the request: the same `http.body` is sent
-              identically under `http` and `graph_ql`, and the value can be changed on an existing
-              export without touching the body.
+              The value picks the editor and changes one thing in a GraphQL request: under `graph_ql`
+              and `assistant_graphql`, a `variables` member stored as a JSON string is parsed and sent
+              as an object, while under `http` it is sent as the string. A body whose `variables` is
+              already an object goes out unchanged under `graph_ql` and `http`. Live-verified 2026-10-22 with
+              export previews against an echo endpoint: a string `variables` under `graph_ql`,
+              `assistant_graphql` and `http`, and an object `variables` under `graph_ql` and `http`.
             - |-
               The GraphQL form reads `http.body` as the JSON envelope `{"query", "operationName",
               "variables"}` and shows each member in its own editor, recompiling the envelope on save
@@ -31165,9 +31209,15 @@ components:
               XML, etc.).
             - |-
               A GraphQL request is this field holding the stringified JSON envelope `{"query":
-              "<document>", "operationName": "...", "variables": ...}` whatever `formType` says;
-              `variables` may be an object or a JSON-encoded string, and a templated variables value
-              must stay inside a string so the body remains parseable JSON at rest (see `formType`).
+              "<document>", "operationName": "...", "variables": ...}`. `variables` may be an object
+              or a JSON-encoded string, and a string is sent as an object only under the GraphQL
+              form types (see `formType`). Variables with unquoted Handlebars (a number, `null`, an
+              `{{#if}}` block) must be a string so the body remains parseable JSON at rest; string
+              values inside that string sit two JSON levels deep, so write them as
+              `\"{{jsonEncode record.x}}\"` with double braces: a plain `{{record.x}}`, or a
+              triple-brace `jsonEncode`, fails a value holding a quote with 422 `invalid_json`.
+              An object or array there is `{{jsonSerialize record.x}}`, also with double braces;
+              triple braces fail the same way.
             - |-
               You can use handlebars expressions to create dynamic content:
               ```
@@ -31991,7 +32041,7 @@ components:
                 - response.records
             lastPageStatusCode:
               type: integer
-              description: HTTP status code that signals the last page, replacing the default behavior of treating 404 as the end of pagination. When this status is received, paging stops and the response is not treated as an error. Set only when the API uses a non-404 code (such as 204 or 400) to indicate no more pages.
+              description: 'HTTP status code that signals the last page, replacing the default behavior of treating 404 as the end of pagination. When this status is received (any code but `200` paired with `lastPagePath`), paging stops and the response is not treated as an error. Set it when the API uses a non-404 code (such as 204 or 400) to indicate no more pages, or to `200` together with `lastPagePath` when the last page is an ordinary 200 response: then the response is parsed, its records are kept, and paging stops only when `lastPagePath` matches `lastPageValues`.'
               x-celigo-ai-guidance:
                 - Specifies a custom HTTP status code that indicates the last page of results.
                 - |-
@@ -32026,36 +32076,45 @@ components:
                 - |-
                   ## TECHNICAL DETAILS
 
-                  When this status code is received, the system:
+                  When this status code is received (any code but `200` paired with
+                  `lastPagePath`), the system:
                   - Stops the pagination process
                   - Considers the data collection complete
                   - Does not treat the response as an error
                   - Does not attempt to process any response body
 
                   IMPORTANT: Only set this if your API explicitly uses a non-404 status code
-                  to indicate the end of pagination. Setting this incorrectly could cause
-                  premature termination of data collection or error handling issues.
+                  to indicate the end of pagination, or to `200` with `lastPagePath` (below).
+                  Setting this incorrectly could cause premature termination of data
+                  collection or error handling issues.
+                - |-
+                  `200` is the exception, for an API whose last page is an ordinary 200 response:
+                  together with `lastPagePath`, paging stops on the first 200 whose `lastPagePath`
+                  value matches `lastPageValues`, and that page's records are kept. Live-verified
+                  2026-10-22 with token paging.
               examples:
                 - 204
                 - 400
                 - 500
             lastPagePath:
               type: string
-              description: JSON path to a response-body field that signals the end of pagination, such as a "has more" flag or a cursor that empties on the last page. Must be used with `lastPageValues`, which lists the values at this path that stop paging. If the path does not exist in a response, the condition is not considered met.
+              description: 'JSON path to a response-body field that signals the end of pagination, such as a "has more" flag or a cursor that empties on the last page. Must be used with `lastPageValues`, which lists the values at this path that stop paging. If the path does not exist in a response, the condition is not considered met. With `method: token` the path is read only on a response whose status code equals `lastPageStatusCode`, so pair it with `lastPageStatusCode: 200` for an ordinary last page; with `method: body` it is read on every response.'
               x-celigo-ai-guidance:
                 - |-
                   ## FIELD BEHAVIOR
 
                   - OPTIONAL: Only needed for APIs with field-based pagination completion signals
-                  - Works with all pagination methods
+                  - Accepted on all pagination methods; when it is read depends on the method (see
+                    the method note below)
                   - Used in conjunction with lastPageValues
                   - JSON path notation to a field in the response body
                 - |-
                   ## IMPLEMENTATION GUIDANCE
 
                   This field is used when an API indicates the last page through a field
-                  in the response body rather than using HTTP status codes. The system
-                  checks this path in each response to determine if pagination is complete.
+                  in the response body rather than using HTTP status codes. Which responses
+                  the system checks it on depends on the paging method (see the method note
+                  below).
 
                   Common patterns include:
 
@@ -32089,8 +32148,19 @@ components:
                   "lastPageValues": ["false", "0"]
                   ```
 
-                  IMPORTANT: The path is evaluated against each response using JSON path notation.
-                  If the path doesn't exist in the response, the condition is not considered met.
+                  IMPORTANT: The path is evaluated using JSON path notation, on the responses the
+                  method note below describes. If the path doesn't exist in the response, the
+                  condition is not considered met.
+                - |-
+                  On `method: token` the path is checked only on a response whose status code equals
+                  `lastPageStatusCode`. For an API whose last page is an ordinary 200 (a GraphQL
+                  `pageInfo.hasNextPage: false`), set `lastPageStatusCode: 200` with it; without that,
+                  paging goes on while the token at `path` is non-empty, so a last page that still
+                  carries a cursor costs one more request. On `method: body` the path is read on
+                  every response, with no status code needed. Live-verified 2026-10-22 against an echo
+                  endpoint for `token` (two requests without `lastPageStatusCode`, one with 200) and
+                  `body` (stopped on the second response); `page`, `skip` and `url` paging were not
+                  verified.
               examples:
                 - meta.isLastPage
                 - pagination.hasMore
@@ -32514,22 +32584,30 @@ components:
                   - '201'
             errorPath:
               type: string
-              description: Path to the error message in the response body. The value at this path is included in error logs and error records when the API returns an error.
+              description: Path to the error message in the response body. The value at this path is included in error logs and error records when the API returns an error; without it, the message is the whole response body.
               examples:
                 - error.message
                 - errorMessage
                 - errors[0].detail
+                - errors[0].message
             failPath:
               type: string
-              description: Path to a response field that signals failure even when the HTTP status code is 200 — the inverse of `successPath`. Must be used with `failValues`.
+              description: Path to a response field that signals failure even when the HTTP status code is 200 — the inverse of `successPath`. With `failValues`, the response fails when the value there matches one of them; without, when the path holds a truthy value. A path that resolves to an array matches only when the array has exactly one element.
               x-celigo-ai-guidance:
-                - |-
-                  Similar to `successPath` but inverted logic — checks for failure indicators.
-                  Must be used together with `failValues`.
+                - Similar to `successPath` but inverted logic — checks for failure indicators.
+                - |-
+                  A path that resolves to an array matches only when the array has exactly one
+                  element. GraphQL APIs usually report a failed query with HTTP 200 and an `errors` array:
+                  `failPath: errors` fails the response for one error and lets two or more through,
+                  so set `failPath` (and `errorPath`) to `errors[0].message`. Without a fail path the
+                  response counts as a success, and an export whose `resourcePath` points into
+                  `data` returns zero records with no error. Live-verified 2026-10-22 with export
+                  and import previews against an echo endpoint.
               examples:
                 - error
                 - status
                 - result.error
+                - errors[0].message
             failValues:
               type: array
               items:
@@ -35347,8 +35425,9 @@ components:
                 Number of records the RESTlet returns per request (default 1000). This, not the
                 export's `pageSize`, sizes each NetSuite call; the export keeps requesting until the
                 search is exhausted. Larger batches reduce round-trips but raise NetSuite governance
-                and memory use per call; tune to the record's size. In a test run or preview the
-                request is capped at the export's `pageSize` (default 20) instead.
+                and memory use per call; tune to the record's size. The RESTlet caps a call at 1000,
+                so a larger value acts as 1000. In a test run or preview the request is capped at the
+                export's `pageSize` (default 20) instead.
               examples:
                 - 100
                 - 200
@@ -35627,8 +35706,9 @@ components:
               type: array
               description: |-
                 Search columns the RESTlet returns for each matching record. With a saved search,
-                omit this to return the search's own result columns; an ad-hoc search (no
-                `searchId`) must list its columns here.
+                the RESTlet returns the search's own result columns followed by any listed here: a
+                list adds columns and never removes one of the search's, so remove a column in the
+                saved search itself. An ad-hoc search (no `searchId`) must list its columns here.
               x-celigo-ai-guidance:
                 - |-
                   Entries are objects keyed by `name` — `[{"name": "internalid"}, {"name":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.168",
+  "version": "0.2.170",
   "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": "f57db462",
 		"generatedAt": "2026-10-22"
 	},
 	"roots": {