@celigo/api-specs 0.2.172 → 0.2.173

package/dist/ai-agent.yml

@@ -4860,7 +4860,9 @@ components:
               x-celigo-refModel: scripts
               description: |
                 Reference to the Script resource that contains the filtering logic. This must be a valid
-                ObjectId of a Script resource that exists in the system.
+                ObjectId of a Script resource in this account: any other id fails the save with 422
+                ("Only a script owned by the user or a script shared by the Integration App can be used
+                at filter.script._scriptId.").
 
                 The referenced script must contain the function specified in the `function` field
                 and must be written to handle filtering specifically. The script receives
@@ -5597,7 +5599,9 @@ components:
                 Reference to a predefined script resource containing the transformation logic.
 
                 The referenced script should contain the function specified in the
-                'function' property.
+                'function' property. It must be a script in this account: any other id fails the save
+                with 422 ("Only a script owned by the user or a script shared by the Integration App can
+                be used at transform.script._scriptId.").
               format: objectid
               x-celigo-refModel: scripts
               examples:
@@ -5630,7 +5634,11 @@ components:
           type: string
           format: objectId
           x-celigo-refModel: scripts
-          description: Script containing the hook function named in `function`. Send this or `_stackId`, not both.
+          description: |-
+            Script containing the hook function named in `function`. Send this or `_stackId`, not both.
+            Must be a script in this account: any other id fails the save with 422, naming the hook,
+            such as "Only a script owned by the user or a script shared by the Integration App can
+            be used at hooks.preMap._scriptId." on an import's `preMap`.
         _stackId:
           type: string
           format: objectId

package/dist/api.yml

@@ -2560,8 +2560,12 @@ components:
     Script:
       type: object
       description: |-
-        Script-mode configuration. The referenced function receives the request object
-        and must return a response with `statusCode`, `headers`, and `body`.
+        Script-mode configuration. Callers reach the API at `/v1/apis/{_id}/request`, and the
+        referenced function is called with one `options` object: `method`, `headers` (the
+        request's headers, without `Authorization`), `queryString` (the parsed query string),
+        `body`, and `rawBody` (the body as received, a string). On a GET, `body` is absent and
+        `rawBody` is empty. It returns `{statusCode, headers, body}`: `headers` is optional,
+        and `body` may be any JSON value, an array included.
       properties:
         _scriptId:
           type: string
@@ -2581,8 +2585,15 @@ components:
         - function
       x-celigo-ai-guidance:
         - |-
-          In script mode, you provide a custom JavaScript function that receives the request
-          object and returns the response. This gives you complete control over the API behavior.
+          In script mode, you provide a custom JavaScript function that receives the `options`
+          object (`method`, `headers` without `Authorization`, `queryString`, `body`, `rawBody`)
+          and returns the response. This gives you complete control over the API behavior.
+        - |-
+          The function gets no `pathParams` or `queryParams`: read the query from `queryString`.
+          A return without `statusCode`, or with a `null` or missing `body`, answers the caller
+          501 ("'StatusCode' returned by the script cannot be undefined." or "'body' returned by
+          the script cannot be undefined or null."), and an error the function throws answers
+          422 with its message. Any other `statusCode` is sent as returned.
     items:
       type: object
       required:

package/dist/asynchelper.yml

@@ -3323,7 +3323,9 @@ components:
                 Reference to a predefined script resource containing the transformation logic.
 
                 The referenced script should contain the function specified in the
-                'function' property.
+                'function' property. It must be a script in this account: any other id fails the save
+                with 422 ("Only a script owned by the user or a script shared by the Integration App can
+                be used at transform.script._scriptId.").
               format: objectid
               x-celigo-refModel: scripts
               examples:

package/dist/enduser.yml

@@ -29,7 +29,11 @@ tags:
       routes shared with workspace users. The account owner is never an end
       user: owners already have MCP access without an end-user record, the
       invite refuses the owner's address (`owner_self_invite_not_allowed`),
-      and the owner never appears in these lists.
+      and the owner never appears in these lists. Workspace administrators
+      need no record either: under Celigo OAuth they reach every MCP server in
+      the environment, and everything on it. Other workspace users need an
+      end-user record with grants. Anyone who also holds an end-user record,
+      an administrator included, is judged by that record's grants.
 
       ## End user schema
 

package/dist/export.yml

@@ -3223,7 +3223,9 @@ components:
               x-celigo-refModel: scripts
               description: |
                 Reference to the Script resource that contains the filtering logic. This must be a valid
-                ObjectId of a Script resource that exists in the system.
+                ObjectId of a Script resource in this account: any other id fails the save with 422
+                ("Only a script owned by the user or a script shared by the Integration App can be used
+                at filter.script._scriptId.").
 
                 The referenced script must contain the function specified in the `function` field
                 and must be written to handle filtering specifically. The script receives
@@ -15346,7 +15348,9 @@ components:
                 Reference to a predefined script resource containing the transformation logic.
 
                 The referenced script should contain the function specified in the
-                'function' property.
+                'function' property. It must be a script in this account: any other id fails the save
+                with 422 ("Only a script owned by the user or a script shared by the Integration App can
+                be used at transform.script._scriptId.").
               format: objectid
               x-celigo-refModel: scripts
               examples:
@@ -16865,7 +16869,10 @@ components:
                   type: string
                   format: objectId
                   x-celigo-refModel: scripts
-                  description: Script containing the hook function named in `function`.
+                  description: |-
+                    Script containing the hook function named in `function`. Must be a script in this
+                    account: any other id fails the save with 422 ("Only a script owned by the user or
+                    a script shared by the Integration App can be used at hooks.preSavePage._scriptId.").
                   examples:
                     - 60a2c4e6f321d800129a1a3c
                     - 5f8e7d2c1b54e6003a9c7e12
@@ -16976,7 +16983,10 @@ components:
           type: string
           format: objectId
           x-celigo-refModel: connectors
-          description: Connector this export was created from, set when the export is part of an installed integration app.
+          description: |-
+            Connector this export was created from, set when the export is part of an installed
+            integration app. The app's install sets it: a create that sends it is refused with 403
+            ("Cannot create an Integration App resource").
         unencrypted:
           type: object
           description: Custom configuration values stored without encryption and returned in API responses.

package/dist/flow.yml

@@ -440,8 +440,10 @@ paths:
         PATCH is safer than PUT for toggling `disabled` or arming debug logging because it won't
         accidentally reset other fields. To arm debug logging, `replace` `/logging/debugUntil` with
         a future ISO timestamp (up to the plan's cap, `logging.maxDebugDuration` minutes on the license
-        from `GET /v1/licenses`); to
-        disarm, set it to a past timestamp or null.
+        from `GET /v1/licenses`). To disarm it, `remove` `/logging/debugUntil`. A `replace` with a
+        past timestamp is refused with 422 ("Debug logging end time must be in the future.") and
+        leaves the window open, so to end a window early with `replace` alone, set a time a few
+        seconds ahead.
       operationId: patchFlow
       tags:
         - Flows
@@ -475,6 +477,11 @@ paths:
                   - op: replace
                     path: /logging/debugUntil
                     value: '2026-05-02T16:00:00.000Z'
+              disable_debug:
+                summary: Turn debug logging off before the window ends
+                value:
+                  - op: remove
+                    path: /logging/debugUntil
               update_schedule:
                 summary: Change Celigo 6-field schedule cron
                 value:
@@ -1996,7 +2003,7 @@ paths:
                   value:
                     errors:
                       - code: inactive_flow
-                        message: The flow is currently disabled and cannot process retries.
+                        message: The flow is inactive. Please enable the flow before retrying.
                 missing_last_error_at:
                   summary: selectAll without lastErrorAt
                   value:
@@ -3523,7 +3530,22 @@ paths:
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '404':
-          $ref: '#/components/responses/404-not-found'
+          description: |-
+            Flow not found ("The flow <_id> does not belong to the user <userId>."). The
+            same answer comes back for a flow that exists and has page generators but no page
+            processor or router yet, even when `_exportId` names one of its page generators: give it
+            a step after the export before test-running it. (An `_exportId` that isn't one of the
+            flow's page generators is the 400.)
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not_found:
+                  summary: Unknown flow id, or a flow with no page processor or router
+                  value:
+                    errors:
+                      - message: The flow 5f8d43a1b9e5a80011a35f2c does not belong to the user 60a2c4e6f321d800129a1a3c.
         '422':
           $ref: '#/components/responses/422-unprocessable-entity'
   /v1/flows/{_id}/test/run/{runId}/{_stepId}:
@@ -4577,7 +4599,22 @@ components:
           properties:
             postResponseMap:
               type: object
-              description: Hook that runs after the step's response mapping completes.
+              description: |-
+                Hook that runs after the step's response mapping completes. The function receives
+                `options.postResponseMapData` (the records, with response mapping applied) and
+                `options.responseData` (the step's per-record results, in the same order) and returns
+                `postResponseMapData`, same length. A record an import step failed is in neither array
+                unless `proceedOnFailure` is true. Then it is included, without the fields response
+                mapping would have added, and its `responseData` entry has `statusCode` 422 and
+                `errors` as an object keyed by index (`"0"`, `"1"`, ...) rather than an array. A
+                successful entry has no `errors`.
+              x-celigo-ai-guidance:
+                - |-
+                  Verified live 2026-10-22 in flow runs of an HTTP import, three records with one
+                  answered 404: with `proceedOnFailure` unset, both arrays held the two written
+                  records; with `proceedOnFailure: true` they held all three, and a hook that called
+                  `.map` on each entry's `errors` threw on the failed one, failing the page. Read
+                  errors with `Object.values(entry.errors || {})`.
               properties:
                 function:
                   type: string
@@ -6668,7 +6705,12 @@ components:
             - '500'
         message:
           type: string
-          description: Human-readable message. Frequently a JSON string that the adaptor received as a response body.
+          description: |-
+            Human-readable message. Frequently a JSON string that the adaptor received as a response body.
+            Stored cut to 500 characters: a longer message keeps its first 497 characters followed by
+            `...`. A template parse error (`handlebars_template_parse_error`) repeats the whole template
+            before its parse detail, so in a long template the detail is cut off; invoking the import
+            (`POST /v1/imports/{_id}/invoke`) with the record returns the full message.
           examples:
             - '{"error":"Internal Server Error"}'
         oIndex:

package/dist/httpconnector.yml

@@ -1613,7 +1613,9 @@ components:
               x-celigo-refModel: scripts
               description: |
                 Reference to the Script resource that contains the filtering logic. This must be a valid
-                ObjectId of a Script resource that exists in the system.
+                ObjectId of a Script resource in this account: any other id fails the save with 422
+                ("Only a script owned by the user or a script shared by the Integration App can be used
+                at filter.script._scriptId.").
 
                 The referenced script must contain the function specified in the `function` field
                 and must be written to handle filtering specifically. The script receives

package/dist/httpconnectorresource.yml

@@ -1059,7 +1059,9 @@ components:
               x-celigo-refModel: scripts
               description: |
                 Reference to the Script resource that contains the filtering logic. This must be a valid
-                ObjectId of a Script resource that exists in the system.
+                ObjectId of a Script resource in this account: any other id fails the save with 422
+                ("Only a script owned by the user or a script shared by the Integration App can be used
+                at filter.script._scriptId.").
 
                 The referenced script must contain the function specified in the `function` field
                 and must be written to handle filtering specifically. The script receives

package/dist/import.yml

@@ -12617,7 +12617,9 @@ components:
               x-celigo-refModel: scripts
               description: |
                 Reference to the Script resource that contains the filtering logic. This must be a valid
-                ObjectId of a Script resource that exists in the system.
+                ObjectId of a Script resource in this account: any other id fails the save with 422
+                ("Only a script owned by the user or a script shared by the Integration App can be used
+                at filter.script._scriptId.").
 
                 The referenced script must contain the function specified in the `function` field
                 and must be written to handle filtering specifically. The script receives
@@ -12676,7 +12678,11 @@ components:
           type: string
           format: objectId
           x-celigo-refModel: scripts
-          description: Script containing the hook function named in `function`. Send this or `_stackId`, not both.
+          description: |-
+            Script containing the hook function named in `function`. Send this or `_stackId`, not both.
+            Must be a script in this account: any other id fails the save with 422, naming the hook,
+            such as "Only a script owned by the user or a script shared by the Integration App can
+            be used at hooks.preMap._scriptId." on an import's `preMap`.
         _stackId:
           type: string
           format: objectId
@@ -15249,7 +15255,9 @@ components:
                 Reference to a predefined script resource containing the transformation logic.
 
                 The referenced script should contain the function specified in the
-                'function' property.
+                'function' property. It must be a script in this account: any other id fails the save
+                with 422 ("Only a script owned by the user or a script shared by the Integration App can
+                be used at transform.script._scriptId.").
               format: objectid
               x-celigo-refModel: scripts
               examples:
@@ -16872,6 +16880,15 @@ components:
                 plus whatever this step's response mapping merges back. A value later steps need
                 belongs in the source export's `preSavePage`, in this step's `postResponseMap` hook on
                 the flow, or in the later import's own `preMap`.
+
+                The function returns one element per record in `options.data`, in order:
+                `{ data: <record> }` sends the record and `{ errors: [{ code, message }] }` fails it.
+                An element without `data` — `{}`, or the record itself returned unwrapped — skips that
+                record with no error: nothing is sent and the record is reported `ignored: true` at
+                stage `preMapHook`. A return with more or fewer elements fails every record on the page
+                with `invalid_extension_response` ("Extension result doesn't contain the same number
+                of elements as the request object. Expected 2, got 1. Extension returned statusCode
+                200"), source `pre_map_hook`.
               x-celigo-ai-guidance:
                 - |-
                   Pre-map JavaScript hook — runs once per page BEFORE the
@@ -16883,7 +16900,18 @@ components:
                   renames — mappings handle those.
 
                   Runtime contract: ``options.data[]`` (the page of upstream
-                  records) → array of the same length.
+                  records) → array of the same length, each element
+                  ``{data: record}`` or ``{errors: [...]}``.  A bare record in
+                  the returned array is skipped without an error, so
+                  ``options.data.map(r => { r.total = t; return r })`` sends
+                  nothing.
+                - |-
+                  Verified live 2026-10-22 by invoking an HTTP import with a
+                  Mapper 2.0 number mapping: one ``{data: record}`` per record
+                  sent both records; the bare records sent nothing and both
+                  came back ``ignored: true``, ``stage: preMapHook``, with no
+                  error; one element for two records failed both with 422
+                  ``invalid_extension_response``.
               allOf:
                 - $ref: '#/components/schemas/Hook'
             postMap:

package/dist/mcp-oauth-provider.yml

@@ -329,15 +329,22 @@ components:
             - https://mcp.example.com
         scopes:
           type: array
-          description: Required OAuth scopes. Incoming tokens must carry every listed scope.
+          description: |-
+            The MCP operations OAuth callers may use on every server that references this
+            provider, and the scopes those servers advertise as `scopes_supported`. Calling a
+            tool (`tools/call`) needs `mcp:write`; listing tools, prompts and resources, and
+            reading prompts and resources, accept either scope. Listing only `mcp:read` refuses
+            every tool call with 403 `insufficient_scope`, whatever the token carries; an empty
+            list allows both. Each request also needs its scope in the caller's token, so a
+            token issued with only `mcp:read` can list and read but can't call a tool.
           items:
             type: string
             enum:
               - mcp:read
               - mcp:write
             x-enumDescriptions:
-              mcp:read: Grants read-only access to MCP server resources.
-              mcp:write: Grants write access to MCP server resources.
+              mcp:read: Lists tools, prompts and resources and reads prompts and resources; can't call a tool.
+              mcp:write: Calls tools (`tools/call`); also lists and reads.
           examples:
             - - mcp:read
               - mcp:write

package/dist/mcp-server.yml

@@ -3082,7 +3082,15 @@ components:
         scopes:
           type: array
           description: |-
-            Required OAuth scopes. Incoming tokens must carry every listed scope.
+            For an external provider or inline OAuth: the MCP operations OAuth callers may use on
+            this server, and the scopes its OAuth metadata advertises as `scopes_supported`.
+            Calling a tool (`tools/call`) needs `mcp:write`; listing tools, prompts and resources,
+            and reading prompts and resources, accept either scope. A server that lists only
+            `mcp:read` refuses every tool call with 403 `insufficient_scope`, whatever the token
+            carries; an empty list allows both. Under Celigo OAuth (`useCeligoOauth`) this list
+            isn't used: the server allows both scopes. Either way each request also needs its
+            scope in the caller's token, so a token issued with only `mcp:read` can list and read
+            but can't call a tool. API-token callers aren't scope-checked.
 
             Rejected values return `enum` / `invalid_field_value` on
             `oauth.scopes.<index>`.
@@ -3092,8 +3100,8 @@ components:
               - mcp:read
               - mcp:write
             x-enumDescriptions:
-              mcp:read: Grants read-only access to MCP server resources.
-              mcp:write: Grants write access to MCP server resources.
+              mcp:read: Lists tools, prompts and resources and reads prompts and resources; can't call a tool.
+              mcp:write: Calls tools (`tools/call`); also lists and reads.
           examples:
             - - mcp:read
               - mcp:write

package/dist/tool.yml

@@ -6358,7 +6358,9 @@ components:
                 Reference to a predefined script resource containing the transformation logic.
 
                 The referenced script should contain the function specified in the
-                'function' property.
+                'function' property. It must be a script in this account: any other id fails the save
+                with 422 ("Only a script owned by the user or a script shared by the Integration App can
+                be used at transform.script._scriptId.").
               format: objectid
               x-celigo-refModel: scripts
               examples:
@@ -24176,7 +24178,9 @@ components:
               x-celigo-refModel: scripts
               description: |
                 Reference to the Script resource that contains the filtering logic. This must be a valid
-                ObjectId of a Script resource that exists in the system.
+                ObjectId of a Script resource in this account: any other id fails the save with 422
+                ("Only a script owned by the user or a script shared by the Integration App can be used
+                at filter.script._scriptId.").
 
                 The referenced script must contain the function specified in the `function` field
                 and must be written to handle filtering specifically. The script receives
@@ -24235,7 +24239,11 @@ components:
           type: string
           format: objectId
           x-celigo-refModel: scripts
-          description: Script containing the hook function named in `function`. Send this or `_stackId`, not both.
+          description: |-
+            Script containing the hook function named in `function`. Send this or `_stackId`, not both.
+            Must be a script in this account: any other id fails the save with 422, naming the hook,
+            such as "Only a script owned by the user or a script shared by the Integration App can
+            be used at hooks.preMap._scriptId." on an import's `preMap`.
         _stackId:
           type: string
           format: objectId
@@ -25862,6 +25870,15 @@ components:
                 plus whatever this step's response mapping merges back. A value later steps need
                 belongs in the source export's `preSavePage`, in this step's `postResponseMap` hook on
                 the flow, or in the later import's own `preMap`.
+
+                The function returns one element per record in `options.data`, in order:
+                `{ data: <record> }` sends the record and `{ errors: [{ code, message }] }` fails it.
+                An element without `data` — `{}`, or the record itself returned unwrapped — skips that
+                record with no error: nothing is sent and the record is reported `ignored: true` at
+                stage `preMapHook`. A return with more or fewer elements fails every record on the page
+                with `invalid_extension_response` ("Extension result doesn't contain the same number
+                of elements as the request object. Expected 2, got 1. Extension returned statusCode
+                200"), source `pre_map_hook`.
               x-celigo-ai-guidance:
                 - |-
                   Pre-map JavaScript hook — runs once per page BEFORE the
@@ -25873,7 +25890,18 @@ components:
                   renames — mappings handle those.
 
                   Runtime contract: ``options.data[]`` (the page of upstream
-                  records) → array of the same length.
+                  records) → array of the same length, each element
+                  ``{data: record}`` or ``{errors: [...]}``.  A bare record in
+                  the returned array is skipped without an error, so
+                  ``options.data.map(r => { r.total = t; return r })`` sends
+                  nothing.
+                - |-
+                  Verified live 2026-10-22 by invoking an HTTP import with a
+                  Mapper 2.0 number mapping: one ``{data: record}`` per record
+                  sent both records; the bare records sent nothing and both
+                  came back ``ignored: true``, ``stage: preMapHook``, with no
+                  error; one element for two records failed both with 422
+                  ``invalid_extension_response``.
               allOf:
                 - $ref: '#/components/schemas/Hook'
             postMap:
@@ -38163,7 +38191,10 @@ components:
                   type: string
                   format: objectId
                   x-celigo-refModel: scripts
-                  description: Script containing the hook function named in `function`.
+                  description: |-
+                    Script containing the hook function named in `function`. Must be a script in this
+                    account: any other id fails the save with 422 ("Only a script owned by the user or
+                    a script shared by the Integration App can be used at hooks.preSavePage._scriptId.").
                   examples:
                     - 60a2c4e6f321d800129a1a3c
                     - 5f8e7d2c1b54e6003a9c7e12
@@ -38274,7 +38305,10 @@ components:
           type: string
           format: objectId
           x-celigo-refModel: connectors
-          description: Connector this export was created from, set when the export is part of an installed integration app.
+          description: |-
+            Connector this export was created from, set when the export is part of an installed
+            integration app. The app's install sets it: a create that sends it is refused with 403
+            ("Cannot create an Integration App resource").
         unencrypted:
           type: object
           description: Custom configuration values stored without encryption and returned in API responses.

package/dist/tradingpartnerconnector.yml

@@ -928,7 +928,9 @@ components:
               x-celigo-refModel: scripts
               description: |
                 Reference to the Script resource that contains the filtering logic. This must be a valid
-                ObjectId of a Script resource that exists in the system.
+                ObjectId of a Script resource in this account: any other id fails the save with 422
+                ("Only a script owned by the user or a script shared by the Integration App can be used
+                at filter.script._scriptId.").
 
                 The referenced script must contain the function specified in the `function` field
                 and must be written to handle filtering specifically. The script receives

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.172",
+  "version": "0.2.173",
   "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": "a3b6728d",
+		"iasCommit": "752a338e",
 		"generatedAt": "2026-10-22"
 	},
 	"roots": {