@celigo/api-specs 0.2.169 → 0.2.171

package/dist/ai-agent.yml

@@ -1232,7 +1232,7 @@ components:
                       x-enumDescriptions:
                         text: Free-form text response from the model.
                         json_schema: Structured JSON output conforming to a defined schema.
-                        blob: Binary data output for non-text content.
+                        blob: Image generation — the run calls the image generation tool and returns the stored image's `blobKey`, not `_text` or `_json`.
                       default: text
                       description: Output format type.
                     schemaMode:
@@ -1454,11 +1454,6 @@ components:
                               an object without a non-empty name fails with a
                               missing-required-field error. String entries are the
                               legacy form and stay valid.
-                      allowedPrompts:
-                        type: array
-                        description: Specific prompts to allow from the MCP server (used for MCP prompt entries; all if omitted).
-                        items:
-                          type: string
                   tool:
                     type: object
                     description: |
@@ -1601,7 +1596,7 @@ components:
                   x-enumDescriptions:
                     text: Free-form text response from the model.
                     json_schema: Structured JSON output conforming to a defined schema.
-                    blob: Binary data output for non-text content.
+                    blob: Image generation — the run returns the stored image's `blobKey`, not `_text` or `_json`.
                   default: text
                 schemaMode:
                   type: string
@@ -1770,11 +1765,6 @@ components:
                                       description: Display description shown for the tool.
                                   required:
                                     - name
-                              allowedPrompts:
-                                type: array
-                                description: Specific prompts to allow from the MCP server (used for MCP prompt entries; all if omitted).
-                                items:
-                                  type: string
                           tool:
                             type: object
                             description: Reference to a Celigo Tool resource, used when type is "tool".
@@ -4398,192 +4388,6 @@ components:
                   - lookupName
               - required:
                   - hardCodedValue
-    ResponseMapping:
-      type: object
-      description: |
-        Merges fields from a step's response back onto the in-flight record so
-        downstream steps can read them. Applies to both lookup steps
-        (`type: "export"`) and import steps (`type: "import"`); without it, the
-        step's response is discarded after the call.
-
-        `fields` and `lists` are plain arrays — exactly the shape GET returns.
-
-        Extract paths do NOT read the raw application response — the platform
-        wraps every response in a canonical per-record envelope first, and
-        extracts evaluate against that envelope:
-
-        - **Lookup steps**: `{"statusCode": 200, "data": [<result records>],
-          "errors": []}` — `data` holds the records the lookup step returns,
-          AFTER the export's own `transform` and output `filter` have run, so
-          extracts must start from it and name transformed fields by their
-          transformed name: `data[0].name` copies a field of the first result,
-          `data` copies the whole result array. A bare result-record field name
-          (e.g. `name`) resolves to nothing and merges nothing, and so does the
-          raw response path a transform consumed. A lookup that groups its
-          results returns each group as an array inside `data`
-          (`"data": [[<row>, <row>]]`): `data[0][0].name` (or `data.0.0.name`)
-          reads the first row of the first group, and `data[0]` copies the group.
-        - **Import steps**: `{"id": "<destination record id>", "statusCode": 200,
-          "ignored": false, "errors": [], "_json": <raw destination response>,
-          ...<response body fields flattened at the root>}` — use `id` for the
-          destination-assigned id and `_json.<path>` (or the flattened
-          `<path>`) for fields inside the destination's response body. The full
-          envelope (including `id`) is present on real runs and in flow-builder
-          previews; flow TEST runs never execute imports, and their envelope is
-          built from the import's saved `mockResponse`, or from the placeholder
-          `{"id": "1234567890", "mockResponse": "replace me"}` (numbered
-          `1234567890-1`, `1234567890-2`, … when a page holds several records)
-          — an `extract: "id"` in a test run merges that mock id, never a
-          destination record id.
-
-        An `extract` may also be a Handlebars expression. It evaluates against
-        the same envelope as a plain path, so every path inside `{{ }}` starts
-        where the plain paths start — `{{data.0.name}}`,
-        `{{#compare data.0.count "==" 1}}yes{{else}}no{{/compare}}`,
-        `{{#if data.length}}found{{/if}}` on a lookup; `{{_json.order.id}}` or
-        `{{id}}` on an import. Index arrays with dots inside Handlebars
-        (`data.0.name` or `data.[0].name`; `data[0].name` renders nothing), and
-        expect a string result (`"1"`, `"false"`). There is no `record` object in
-        this context: `{{record.<anything>}}` renders nothing. Prefer a plain
-        path when the value is simply copied.
-      x-celigo-ai-guidance:
-        - |-
-          Handlebars is allowed in `extract` but only rooted at the envelope —
-          `{{data.0.x}}` on a lookup, `{{_json.x}}` / `{{id}}` on an import. The
-          `record.` root belongs to import-mapping templates; here every
-          `{{record.…}}` form renders nothing, silently, and `{{data[0].x}}`
-          (bracket index inside Handlebars) renders nothing too. Use Handlebars
-          only for a derived value (a flag, a concatenation); copy values with a
-          plain path.
-        - |-
-          A lookup's `data[]` is the step's output after its `transform` and
-          `filter`, so author extracts against the transformed records — never
-          against the raw response the transform consumed, and never against a
-          saved `mockOutput` as stored (it is the raw response; the transform
-          runs on top of it in a test run).
-        - |-
-          Send `fields` and `lists` as bare arrays, exactly as GET returns them.
-          Never wrap either in an object (e.g. `"fields": {"type": [...]}`): the
-          API does not reject that shape — it returns 200 and silently persists
-          `fields: [null]` / `lists: [{"fields": []}]`, erasing the step's
-          response mappings.
-        - |-
-          responseMapping is fully replaced on PUT: omitting it resets the step
-          to empty `{"fields": [], "lists": []}`. Always send the complete
-          intended mapping for every step.
-        - |-
-          To carry several lookup results onto the record, use `extract: "data"`
-          (the whole result array) or a `lists` entry whose extracts use
-          `data[*].x` — never `data[*].x` in `fields[].extract`, which merges
-          nothing: the record simply never gains the field.
-      examples:
-        - fields:
-            - extract: id
-              generate: ContactId
-          lists: []
-        - fields:
-            - extract: data[0].customer.name
-              generate: customerName
-          lists:
-            - generate: matchedOrders
-              fields:
-                - extract: data[*].id
-                  generate: orderId
-                - extract: data[*].total
-                  generate: amount
-      properties:
-        fields:
-          type: array
-          description: |
-            Field mappings that copy individual values from the response
-            envelope onto the in-flight record.
-          items:
-            type: object
-            properties:
-              extract:
-                type: string
-                x-celigo-agent:
-                  - handlebars
-                description: |
-                  Path within the canonical response envelope to copy the value
-                  from, or a Handlebars expression over that same envelope. For
-                  lookup steps, paths start from the envelope's `data` array
-                  (`data[0].x` and `data.0.x` are equivalent; `data` alone
-                  copies every result) — a lookup result field written without
-                  the `data` prefix resolves to nothing. For import steps, use
-                  the envelope fields `id`, `statusCode`, `ignored`, `_json.<path>`
-                  for the raw response body, or the body field itself at the
-                  envelope root (`orderNumber` and `_json.orderNumber` read the
-                  same value). A `[*]` wildcard is not honored here — `data[*].x`
-                  merges nothing; iterate arrays with `lists` instead. Inside
-                  Handlebars, index with dots (`{{data.0.x}}`, never
-                  `{{data[0].x}}`) and never use a `record.` root.
-                examples:
-                  - data[0].customer.name
-                  - data.0.fields.Product Name
-                  - data
-                  - id
-                  - _json.orderNumber
-                  - '{{#if data.length}}found{{else}}missing{{/if}}'
-              generate:
-                type: string
-                description: |
-                  Field path on the in-flight record where the extracted value
-                  is stored, using dot notation for nesting. Downstream steps
-                  read the value at this path.
-                examples:
-                  - customerName
-                  - supplierDetails.supplierName
-                  - netsuite_order_id
-        lists:
-          type: array
-          description: |
-            Array mappings that build a target array on the in-flight record
-            from an array inside the response envelope — one output item per
-            element of the array the item extracts mark with `[*]` (`data[*].x`
-            for lookups, `_json.<arrayPath>[*].x` for imports); an empty source
-            array yields an empty target array. Not needed for one-to-many
-            (fan-out) merge-back, which uses plain field mappings.
-          items:
-            type: object
-            properties:
-              generate:
-                type: string
-                description: |
-                  Array field created on the in-flight record to hold the
-                  mapped items.
-                examples:
-                  - orderItems
-                  - addresses
-                  - contacts
-              fields:
-                type: array
-                description: |
-                  Field mappings applied to each item of the source array to
-                  produce the corresponding target-array item.
-                items:
-                  type: object
-                  properties:
-                    extract:
-                      type: string
-                      description: |
-                        Full envelope path to the source value, with `[*]`
-                        marking the array to iterate — `data[*].productId` for a
-                        lookup, `_json.items[*].sku` for an import. A path without
-                        `[*]` (e.g. `statusCode`) repeats the same envelope value
-                        on every item; an item-relative name (`productId`)
-                        resolves to nothing and produces empty objects.
-                      examples:
-                        - data[*].productId
-                        - data[*].quantity
-                        - _json.items[*].sku
-                    generate:
-                      type: string
-                      description: Target field within each mapped array item.
-                      examples:
-                        - itemId
-                        - qty
-                        - unitPrice
     Filter:
       type: object
       description: |
@@ -5956,8 +5760,14 @@ components:
         mappings:
           allOf:
             - $ref: '#/components/schemas/Mappings'
-        responseMapping:
-          $ref: '#/components/schemas/ResponseMapping'
+          x-celigo-ai-guidance:
+            - |-
+              The mapped record is the agent's input: its `text` is sent as text, `record` as
+              its JSON, and `files` (`[{name, blobKey}]`, blob keys from earlier in the same
+              flow) as attachments. `conversationHistoryId` (at most 200
+              characters) keeps one conversation per agent and id across runs. A record with
+              none of `text`, `record` or `files` is sent whole, as JSON, so with no mappings a
+              record's own top-level `text`, `record` or `files` field is its only input.
         inputContext:
           type: string
           enum:
@@ -5968,7 +5778,9 @@ components:
             envelope: The agent receives records wrapped in an envelope with metadata.
           description: |-
             Selects the data context that `mappings[].extract` evaluates against. With no
-            mappings the agent receives the entire record and `inputContext` is moot. `record`
+            mappings the agent receives the entire record as JSON (or only the record's own
+            top-level `text`, `record` or `files` fields, when it has any) and `inputContext`
+            is moot. `record`
             (the default) extracts against the flat record; `envelope` extracts against the
             runtime envelope, which exposes the record alongside job, settings, and other
             run-time metadata (`$.record.field`, `$.settings.field`, etc.). Same contract as
@@ -6068,6 +5880,13 @@ components:
               _headers:
                 type: object
                 description: Mock response headers.
+              blobKey:
+                type: string
+                description: |-
+                  Mock output of an agent with `blob` output (image generation:
+                  `openai.output.format.type` or `litellm.responseFormat.type` set to `blob`),
+                  which returns the stored image's key here. Unrelated to the import-level `blob`
+                  flag, which agents refuse.
     ResourceResponse:
       type: object
       description: Response

package/dist/audit.yml

@@ -49,6 +49,12 @@ paths:
         exact resource only — to include descendants (e.g. an integration's
         flows and exports), use `GET /v1/{resourceType}/{_id}/audit` instead.
         `_resourceId` requires `resourceType` to also be set.
+
+        Only the account owner and administrators can query the account-wide
+        log: manage, monitor and integration-level users get 403, and an API
+        token with limited scope gets 401 `token_restricted_access`. Those
+        users can still read the history of a resource they can see, through
+        `GET /v1/{resourceType}/{_id}/audit`.
       parameters:
         - name: limit
           in: query
@@ -311,7 +317,9 @@ paths:
         '400':
           $ref: '#/components/responses/400-bad-request'
         '401':
-          $ref: '#/components/responses/401-unauthorized'
+          $ref: '#/components/responses/401-unauthorized-or-scoped-token'
+        '403':
+          $ref: '#/components/responses/403-administrator-only'
         '422':
           $ref: '#/components/responses/422-unprocessable-entity'
     post:
@@ -328,7 +336,8 @@ paths:
         identical to `GET /v1/audit`.
 
         Pagination, sorting, and time bounds stay in the query string — sending
-        them in the body fails with 400 `invalid_request_body`.
+        them in the body fails with 400 `invalid_request_body`. The same callers
+        are refused as on `GET /v1/audit`.
       parameters:
         - name: limit
           in: query
@@ -472,7 +481,9 @@ paths:
                       - code: invalid_request_body
                         message: 'The request body should not contain pagination parameter(s): limit. Pagination values (after, before, limit, sort_order, sort_by) must be provided as query parameters. The request body should only contain filter fields.'
         '401':
-          $ref: '#/components/responses/401-unauthorized'
+          $ref: '#/components/responses/401-unauthorized-or-scoped-token'
+        '403':
+          $ref: '#/components/responses/403-administrator-only'
         '422':
           description: |-
             A filter value is invalid, a filter that must be an array was sent as
@@ -502,7 +513,9 @@ paths:
       description: |-
         Generates a signed URL for downloading a CSV export of audit logs across all
         documents. The CSV columns are: Time, Source, User, Resource, Name/ID, Action,
-        Field, Old value, New value, Support.
+        Field, Old value, New value, Support. The same callers are refused as on
+        `GET /v1/audit`: only the account owner and administrators can export the
+        account-wide log.
 
         The signed URL expires after 15 minutes. When `hasMore` is true, pass
         the last CSV row's timestamp as `to` to fetch the next batch.
@@ -686,7 +699,9 @@ paths:
                     signedURL: https://integrator-userdata-delete-30.s3.us-east-1.amazonaws.com/audit/624cb034630.../audit-export.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&...
                     hasMore: false
         '401':
-          $ref: '#/components/responses/401-unauthorized'
+          $ref: '#/components/responses/401-unauthorized-or-scoped-token'
+        '403':
+          $ref: '#/components/responses/403-administrator-only'
         '422':
           $ref: '#/components/responses/422-unprocessable-entity'
     post:
@@ -766,7 +781,9 @@ paths:
               schema:
                 $ref: '#/components/schemas/Error'
         '401':
-          $ref: '#/components/responses/401-unauthorized'
+          $ref: '#/components/responses/401-unauthorized-or-scoped-token'
+        '403':
+          $ref: '#/components/responses/403-administrator-only'
         '422':
           $ref: '#/components/responses/422-unprocessable-entity'
   /v1/{resourceType}/{_id}/audit:
@@ -1997,6 +2014,65 @@ components:
                 errors:
                   - code: invalid_request
                     message: The request body failed validation.
+    401-unauthorized-or-scoped-token:
+      description: |-
+        Unauthorized: the request has no valid bearer token (a bare `{message}` body, as on every
+        route), or the token is an API token with limited scope. The account-wide audit query
+        takes only a full-access API token, a personal access token, or a signed-in session; a
+        scoped token is refused with `token_restricted_access` in the standard `{errors: [...]}`
+        envelope.
+      content:
+        application/json:
+          schema:
+            oneOf:
+              - $ref: '#/components/schemas/Error'
+              - type: object
+                description: The auth middleware's bare body for a missing or invalid token.
+                properties:
+                  message:
+                    type: string
+                    description: '`Unauthorized` (no Authorization header) or `Bearer Authentication Failed`.'
+                required:
+                  - message
+          examples:
+            scopedToken:
+              summary: An API token scoped to specific resources
+              value:
+                errors:
+                  - code: token_restricted_access
+                    message: This action is not allowed using API tokens with limited scope.
+            invalidToken:
+              summary: Bearer token invalid or revoked
+              value:
+                message: Bearer Authentication Failed
+    403-administrator-only:
+      description: |-
+        The caller is a manage, monitor or integration-level user. The account-wide audit log is
+        for the account owner and administrators; other users read one resource's history with
+        `GET /v1/{resourceType}/{_id}/audit` instead.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            notAdministrator:
+              value:
+                errors:
+                  - code: access_restricted
+                    message: The role which you are associated with doesn't have the required permissions to perform the action.
+    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.
     401-unauthorized:
       description: |-
         Unauthorized. The request lacks a valid bearer token, or the provided token
@@ -2031,19 +2107,6 @@ components:
               summary: Bearer token invalid or revoked
               value:
                 message: Bearer Authentication Failed
-    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/connection.yml

@@ -10113,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/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":