@celigo/api-specs 0.2.148 → 0.2.150

package/dist/ai-agent.yml

@@ -5689,19 +5689,27 @@ components:
       properties:
         function:
           type: string
-          description: Function to invoke within the referenced script.
+          description: |-
+            Function to invoke: one in the script named by `_scriptId`, or one the code deployed on
+            the stack named by `_stackId` exposes.
           examples:
             - transformRecords
         _scriptId:
           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`. Send this or `_stackId`, not both.
         _stackId:
           type: string
           format: objectId
           x-celigo-refModel: stacks
-          description: Stack that hosts the hook logic, used instead of a script for stack-based deployments.
+          description: |-
+            Stack that hosts the hook logic, used instead of a script for stack-based deployments.
+            The API doesn't enforce the either/or: a save carrying both `_scriptId` and `_stackId`
+            answers 200 and stores both, and the script and the stack then each list the step as a
+            dependent.
+          x-celigo-ai-guidance:
+            - When moving a hook onto a stack, remove `_scriptId` and set `function` to the stack's function in the same update.
         configuration:
           type:
             - object

package/dist/api.yml

@@ -1683,12 +1683,19 @@ paths:
 
         The response carries a `metadata` map keyed by step id (each value is the ordered list of
         stage names that ran for that step), the parent `flowJob`, and the per-step `childJobs[]`.
-        Inspect a specific step's stages with `GET /v1/apis/{_id}/test/run/{runId}/{_stepId}`, where
-        `runId` is the parent `flowJob._id`.
+        The response the run selected appears in `metadata` too, keyed by its `id` (`success`,
+        `fail`, or a custom response's `id`). Inspect a specific step's stages with
+        `GET /v1/apis/{_id}/test/run/{runId}/{_stepId}`, where `runId` is the parent `flowJob._id`.
 
         Test-run invocations do **not** surface in `GET /v1/apis/{_id}/logs`.
 
-        A test run is not free of outside calls: lookups call their sources live. Imports never
+        A test run is not free of outside calls: a lookup export with no saved `mockOutput` calls
+        its source live, and the run then saves that response on the export as its `mockOutput`
+        (the export's `lastModified` changes). Every later test run that uses the export, from any
+        API or Tool and whatever its request, answers that lookup from the saved `mockOutput`
+        instead of calling the source: the lookup's `request` stage shows the request rendered
+        from the new record, and its `response` stage holds the saved records. Remove `mockOutput`
+        from the export to call the source again. Real calls to the API don't read it. Imports never
         send; each returns its saved `mockResponse`, or a placeholder response when none is saved
         (see `mockResponse` on imports).
 
@@ -1748,10 +1755,10 @@ paths:
                 summary: Run without test input (the first step gets an empty record)
                 value: {}
               withMockRequest:
-                summary: Run with an explicit test request
+                summary: Run with an explicit test request (only the body reaches the first step)
                 value:
                   mockRequest:
-                    queryParams:
+                    body:
                       sku: SKU-001
       responses:
         '200':
@@ -1765,7 +1772,8 @@ paths:
                     type: object
                     description: |-
                       Map keyed by step id; each value is the ordered list of stage names that ran for
-                      that step.
+                      that step. The selected response is one of the keys (`success`, `fail`, or a
+                      custom response's `id`), so it names the response the run returned.
                     additionalProperties:
                       type: array
                       items:
@@ -1787,6 +1795,11 @@ paths:
                         - parse
                       main:
                         - router
+                      apiRouter:
+                        - router
+                      success:
+                        - mapping
+                        - response
                     flowJob:
                       _id: 6a2e23bbcf5b64ca6b93b757
                       type: flow
@@ -2793,8 +2806,9 @@ components:
           type: object
           description: |-
             Sample request saved with the API for testing. `POST /v1/apis/{_id}/test/run` doesn't
-            read it; send it as that call's `mockRequest`. A test run still makes outside calls:
-            its lookups call their sources live.
+            read it; send it as that call's `mockRequest`. A test run still makes outside calls: a
+            lookup with no saved `mockOutput` calls its source live, and the run saves that response
+            as the lookup's `mockOutput`, which later test runs answer from.
           properties:
             body:
               type: object
@@ -2813,9 +2827,10 @@ components:
             - |-
               Saving a mockRequest doesn't make test runs use it: a test run without its own
               mockRequest starts from an empty record. A test run isn't free of outside calls
-              either: lookups run live, and only imports are kept from sending (each returns its
-              mockResponse or a placeholder). Can include body, headers, pathParams, and
-              queryParams.
+              either: a lookup without a saved mockOutput runs live (and the run then saves its
+              response as that mockOutput), and only imports are kept from sending (each returns
+              its mockResponse or a placeholder). Can include body, headers, pathParams, and
+              queryParams; only the body reaches the record the steps see.
         transform:
           type: object
           description: |-
@@ -3269,17 +3284,19 @@ components:
             - fail
             - custom
           x-enumDescriptions:
-            success: Default response returned when the API operation completes successfully.
-            fail: Default response returned when the API operation encounters an error.
-            custom: Additional response for specific scenarios, routed via the response router.
-          description: Response type.
+            success: The happy-path response; returned when it's the first response, in list order, whose `inputFilter` matches.
+            fail: The error response; returned when a step fails and that step's `proceedOnFailure` is off.
+            custom: Additional response for specific scenarios, selected by its own `inputFilter`.
+          description: |-
+            Response type. `success` isn't a fallback checked after the `custom` responses: list
+            `custom` responses before it (see `inputFilter`).
           examples:
             - success
           x-celigo-ai-guidance:
             - |-
-              - **success**: Default response for successful operations (required, exactly one)
-              - **fail**: Default response for errors (required, exactly one)
-              - **custom**: Additional responses for specific scenarios (optional, multiple allowed)
+              - **success**: Response for successful operations (required, exactly one)
+              - **fail**: Response for errors (required, exactly one)
+              - **custom**: Additional responses for specific scenarios (optional, multiple allowed), listed before `success`
         statusCode:
           type: integer
           minimum: 100
@@ -3320,7 +3337,13 @@ components:
                   - Content type of the response body
         inputFilter:
           type: object
-          description: Filter criteria for response selection by the response router.
+          description: |-
+            Filter criteria for response selection by the response router, which returns the first
+            response in `responses` whose filter matches. A response without an `inputFilter` matches
+            every request, so a `success` listed first answers requests a later `custom` filter
+            matches; the typed `context.success` filter doesn't prevent that, because
+            `context.success` is true whenever no step failed, including when a lookup found nothing.
+            A step that fails with `proceedOnFailure` off selects the `fail` response.
           properties:
             version:
               type: string
@@ -3334,19 +3357,20 @@ components:
               description: Celigo expression-based filter rules.
               items: {}
               examples:
-                - - equals
-                  - - boolean
-                    - - context
-                      - success
-                  - true
+                - - empty
+                  - - string
+                    - - extract
+                      - customerId
                 - - and
-                  - - equals
-                    - - get
-                      - statusCode
-                    - 200
-                  - - exists
-                    - - get
-                      - data
+                  - - notempty
+                    - - string
+                      - - extract
+                        - orderId
+                  - - greaterthan
+                    - - number
+                      - - extract
+                        - amount
+                    - 1000
               x-celigo-ai-guidance:
                 - |-
                   Array-based DSL where the first element is an operator (e.g., "equals", "and", "or"),
@@ -3552,6 +3576,9 @@ components:
           - Exactly one 'success' response (for successful operations)
           - Exactly one 'fail' response (for errors)
           - Zero or more 'custom' responses (for specific scenarios)
+          The response router returns the first response whose `inputFilter` matches, and a
+          response without one matches every request, so list the 'custom' responses ahead of
+          'success'.
     Builder:
       type: object
       description: Builder-mode configuration defining request structure, routing, and response mapping.
@@ -3573,13 +3600,16 @@ components:
           type: array
           description: |-
             Response configurations. Must include exactly one `success` and one `fail`
-            response; additional `custom` responses are optional.
+            response; additional `custom` responses are optional. Order matters: the response
+            router returns the first response whose `inputFilter` matches, and a response without
+            one matches every request.
           items:
             $ref: '#/components/schemas/ApiResponse'
           x-celigo-ai-guidance:
             - |-
               Must include exactly one 'success' response and one 'fail' response.
-              Additional custom responses can be added for specific scenarios.
+              Additional custom responses can be added for specific scenarios; list them before
+              'success', which otherwise answers the requests their filters match.
       x-celigo-ai-guidance:
         - |-
           The builder mode allows you to define your API using visual configuration:

package/dist/export.yml

@@ -16405,8 +16405,11 @@ components:
                 filter, before the page is sent to downstream steps; commonly used to flatten
                 structures, drop unwanted records, or add computed fields. It receives the page as
                 `options.data` (with `errors`, `pageIndex`, `configuration` and `settings`) and returns
-                `{data, errors, abort, newErrorsAndRetryData}`. An exception thrown here fails every
-                record on that page, each with its own retry data, and later pages still run.
+                `{data, errors, abort, newErrorsAndRetryData}`. Return that object, not the array: a
+                hook that returns `options.data` itself, or a filtered copy, drops the page without an
+                error, and the run completes with 0 records, 0 errors and 0 pages. An exception thrown
+                here fails every record on that page, each with its own retry data, and later pages
+                still run.
               properties:
                 function:
                   type: string

package/dist/filedefinition.yml

@@ -207,6 +207,11 @@ paths:
           For EDI formats (`delimited/x12` or `delimited/edifact`), a valid `globalId`
           is required when the account has an EDI license enabled. The `globalId` must
           reference a known standard document definition.
+        - |-
+          For `format: fixed`, send `version`, `fixed.rowDelimiter` and `fixed.paddingChar`;
+          without them the create fails with 422 and nothing is saved. Columns are read in
+          element order, so declare every column (a placeholder element for a gap) and parse a
+          sample with `POST /v1/processors/structuredFileParser` before linking the definition.
   /v1/filedefinitions/{_id}:
     get:
       x-internal: false
@@ -1016,7 +1021,7 @@ components:
           description: |
             Configuration specific to fixed-width format files.
 
-            Used when `format` is "fixed".
+            Used when `format` is "fixed", which requires `rowDelimiter` and `paddingChar`.
           properties:
             rowSuffix:
               type: string
@@ -1028,14 +1033,20 @@ components:
             rowDelimiter:
               type: string
               description: |
-                Character(s) used to delimit rows during parsing.
+                Character(s) used to delimit rows during parsing. Required when `format` is "fixed".
+
+                A delimiter after the last row is read as one more, empty row: a required row
+                rule then fails the parse at that line ("Required rule must have the respective
+                row in the source file"), and an optional one adds an empty `{}` record. Set
+                `skipIntermittentEmptyLines: true` to drop it.
               examples:
                 - \n
                 - \r\n
             paddingChar:
               type: string
               description: |
-                Character used to pad fixed-width fields to their required length.
+                Character used to pad fixed-width fields to their required length. Required when
+                `format` is "fixed".
               examples:
                 - ' '
                 - '0'
@@ -1090,7 +1101,8 @@ components:
         skipIntermittentEmptyLines:
           type: boolean
           description: |
-            Whether to remove empty rows found in the file content during parsing.
+            Whether to remove empty rows found in the file content during parsing. On a
+            fixed-width definition this includes the empty row a trailing line break adds.
         escapeReleaseChar:
           type: boolean
           description: |
@@ -1213,6 +1225,11 @@ components:
       type: object
       description: |
         Request schema for creating or updating a file definition.
+
+        A fixed-width definition (`format: fixed`) also needs `fixed.rowDelimiter` and
+        `fixed.paddingChar`: a create or full update without either fails with 422
+        ("rowDelimiter is a required field for fixed file definitions.", "paddingChar is a
+        required field for fixed width file definitions.") and saves nothing.
       required:
         - name
         - version
@@ -1220,6 +1237,20 @@ components:
         - rules
       allOf:
         - $ref: '#/components/schemas/FileDefinitionBase'
+      if:
+        properties:
+          format:
+            const: fixed
+        required:
+          - format
+      then:
+        required:
+          - fixed
+        properties:
+          fixed:
+            required:
+              - rowDelimiter
+              - paddingChar
       x-celigo-ai-guidance:
         - |-
           File definitions describe the structure and parsing/generation rules for

package/dist/flow.yml

@@ -4226,7 +4226,10 @@ components:
           type: string
           description: |-
             Cron expression for this specific generator, overriding the flow's main schedule.
-            When omitted, the generator inherits the flow's schedule.
+            When omitted, the generator inherits the flow's schedule. It is read in the flow's
+            `timezone`, and a flow with no flow-level `schedule` still runs on it. PATCH reaches
+            the flow-level `/schedule` and `/timezone` but not this field, so changing it is a full
+            update of the flow.
           examples:
             - '? 5 0,6,12,18 ? * *'
             - '? 30 2 ? * *'
@@ -4236,6 +4239,10 @@ components:
               - Overrides the flow's main schedule for this generator
               - Allows different data sources to refresh at different intervals
               - Useful for sources with varying update frequencies
+            - |-
+              Check for one before rescheduling a flow: a flow-level `schedule` change succeeds
+              but leaves a generator that has its own `schedule` running at its old times. Change
+              the generator's `schedule` instead, with a PUT of the whole flow.
         skipRetries:
           type: boolean
           default: false
@@ -4650,7 +4657,16 @@ components:
             Filter criteria that determines which records match this branch.
 
             Only used when the router's `routeRecordsUsing` is `input_filters`.
-            Records matching these criteria will be routed to this branch.
+            Records matching these criteria will be routed to this branch. A branch
+            without an `inputFilter` matches every record, so under
+            `first_matching_branch` the catch-all branch goes last.
+
+            Send `version` and `rules` directly on `inputFilter` — not inside the
+            `{type: "expression", expression: {...}}` wrapper that export and import
+            filters use. A wrapped filter is saved without an error, but the branch is
+            stored with no `inputFilter` and takes every record.
+          x-celigo-ai-guidance:
+            - Read the flow back after saving a branching router and check that each filtered branch still has its `inputFilter`; a filter sent in the export-filter wrapper is dropped on save without an error.
           properties:
             version:
               type: string
@@ -4679,6 +4695,11 @@ components:
                 logical operators (`and`, `or`, `not`), field access (`extract`, `settings`)
                 and type conversions (`string`, `number`, `boolean`, `epochtime`).
 
+                Every `extract` must be wrapped in a type conversion. A bare
+                `["extract", "<field>"]` is refused when the flow is saved, with 422 "Field
+                operation extract must be called by a Type Conversion Operation but was called
+                by equals." (the message names the operator that held it).
+
                 Example — route records whose `isDeleted` field is the string "false":
                 ```json
                 ["equals", ["string", ["extract", "isDeleted"]], "false"]
@@ -4782,7 +4803,7 @@ components:
           examples:
             - first_matching_branch
           x-celigo-ai-guidance:
-            - Set this and `routeRecordsUsing` together on every router that decides between branches; setting only one of the two is rejected with 422 `invalid_flow_router_config`.
+            - Set this and `routeRecordsUsing` together on every router that decides between branches; setting only one of the two is rejected with 422 `invalid_flow_router_config` ("Either both the routeRecordsTo and routeRecordsUsing fields or none of them should be defined on the router.").
             - Leave both unset on a one-branch pass-through router (the steps before the first branching router, or a merge point). Setting them there still runs, but Flow Builder shows a router node with one branch and no rules. A router with neither field and more than one branch is rejected with 422 `invalid_flow_router_branch`.
         routeRecordsUsing:
           type: string
@@ -5432,7 +5453,9 @@ components:
         Writable flow fields shared by the request and response schemas.
 
         Use `pageProcessors` for simple linear flows or `routers` for conditional branching — never
-        include both: a flow with both arrays non-empty is rejected with 422 `invalid_branched_flow_config`.
+        include both: a flow with both arrays non-empty is rejected with 422 `invalid_branched_flow_config`
+        ("Either routers or pageProcessors should be present in the flow configuration and not both.").
+        Turning a linear flow into a branching one moves its top-level steps into the branches.
         The same import can be a step only once per flow: a second `pageProcessors` entry with its
         `_importId`, in the same array or another branch, fails with 422 `invalid_flow` ("… already
         included as a pageProcessor"). The `schedule` field uses Celigo's 6-field cron format (not
@@ -5491,7 +5514,15 @@ components:
               Build `schedule` as a Celigo 6-field cron:
               `? minute hour day-of-month month day-of-week`.
               The seconds field is always `?`; day-of-month is usually `?`, month `*`,
-              and day-of-week `*` (or specific days, 0=Sun..6=Sat).
+              and day-of-week `*` (or specific days, 0=Sun..6=Sat — weekdays are `1-5`,
+              `1,2,3,4,5` or `MON-FRI`; `2-6` is Tuesday to Saturday).
+            - |-
+              The hours are read in the flow's `timezone`. Keep a user's local times as
+              they are and set their IANA zone; never convert them to UTC, which is an hour
+              off for half the year in a zone with daylight saving and shifts them twice
+              when paired with the local `timezone`. Before changing when a flow runs, read
+              `pageGenerators[]`: a generator with its own `schedule` keeps it after a
+              flow-level change.
             - |-
               Disabling a flow does not bypass schedule validation: POST, PUT, and PATCH
               all reject free text or a sub-minute expression (`not a cron`, `* * * * * *`)
@@ -5526,7 +5557,10 @@ components:
           type:
             - string
             - 'null'
-          description: IANA timezone for the schedule (e.g. `America/New_York`). Defaults to UTC.
+          description: |-
+            IANA timezone for the schedule (e.g. `America/New_York`). Defaults to UTC. The flow's
+            `schedule` and each page generator's own `schedule` are read in this timezone; a page
+            generator has no timezone of its own.
           examples:
             - America/New_York
             - Europe/London

package/dist/guardrail.yml

@@ -25,6 +25,14 @@ tags:
       CRUD operations use the `/v1/imports` endpoints. The `guardrail` object
       holds the type-specific configuration.
 
+      A guardrail returns a verdict for each record and never changes the
+      record. The verdict fields are at the top level of the result:
+      `flagged`, plus `masked` (a `pii` guardrail with `mask: true`) or
+      `reasoning` (an `ai_agent` guardrail), while `_json` is empty when a saved
+      guardrail is invoked by id. In a flow, the guardrail step's response
+      mapping copies them onto the record (`{"extract": "masked", "generate":
+      "description"}`), and routers branch on the mapped `flagged`.
+
       ## Guardrail schema
 
       {% openapi-schemas spec="guardrail" schemas="Guardrail" grouped="true" %}
@@ -1762,10 +1770,15 @@ components:
               type: boolean
               default: false
               description: |-
-                When true, detected PII is replaced with masked values.
-                When false, PII is flagged without modification.
+                When true, the result also carries `masked`: the evaluated input with each detected
+                value replaced by asterisks. The record itself is unchanged. With whole-record input
+                (no `mapping`, and no top-level `text` field on the record), `masked` is the record
+                serialized as one JSON string. When false, PII is flagged only.
               x-celigo-ai-guidance:
-                - Whether to mask detected PII values in the output.
+                - |-
+                  Masking doesn't rewrite the record. To pass masked text on, select the field as the
+                  `text` input (`mapping`) and response-map `masked` back onto that field on the
+                  guardrail's flow step (`{"extract": "masked", "generate": "<field>"}`).
         moderation:
           type: object
           required:
@@ -2152,8 +2165,10 @@ components:
             mapping:
               type: object
               description: |-
-                Mapper 1.0 input mapping. Served only when populated — a
-                guardrail created without one has no `mapping` in responses.
+                Mapper 1.0 input mapping that selects the field evaluated as `text`.
+                Served only when populated — a guardrail created without one has no
+                `mapping` in responses, and evaluates the whole record (or the
+                record's own top-level `text` field, when it has one).
               properties:
                 fields:
                   type: array
@@ -2211,7 +2226,11 @@ components:
                 - []
             mockResponse:
               type: array
-              description: Sample evaluation results stored with the guardrail. The UI populates these from a preview run; accepted on create and update.
+              description: |-
+                Sample evaluation results stored with the guardrail. The UI populates these from a
+                preview run; accepted on create and update. Each item has the shape of the result a
+                run produces for one record, with the verdict fields (`flagged`, `masked`,
+                `reasoning`) at the top level.
               items:
                 type: object
                 properties:
@@ -2225,6 +2244,23 @@ components:
                     description: When true, the sample input tripped the guardrail.
                     examples:
                       - true
+                  reasoning:
+                    type: string
+                    description: |-
+                      The model's explanation of the verdict. Returned by `ai_agent` guardrails,
+                      whatever output format the guardrail stores.
+                    examples:
+                      - The discount is 45% on an account opened 30 days ago, so the order is flagged.
+                  _json:
+                    type: object
+                    description: |-
+                      Empty (`{}`) in the result of a saved guardrail invoked by id. A preview's result
+                      carries the raw verdict under `_json.data`: `flagged`, `reasoning` and
+                      `confidence` for `ai_agent`, or `flagged`, `masked` and `entities_detected`
+                      for `pii`. Read the top-level fields, not `_json`.
+                    additionalProperties: true
+                    examples:
+                      - {}
                   ignored:
                     type: boolean
                     description: When true, the result fell below `confidenceThreshold` and was disregarded.
@@ -2303,9 +2339,17 @@ components:
             Mapper 1.0 mapping that selects the guardrail's input from the
             incoming record. The UI writes a single field entry that maps a
             record field to the `text` input (e.g.
-            `{"fields": [{"extract": "employeeSummary", "generate": "text"}]}`).
-            Optional — when omitted the whole record is evaluated. The server
+            `{"fields": [{"extract": "employeeSummary", "generate": "text"}]}`);
+            only that field is evaluated, and fields outside it are neither
+            scanned nor masked. Optional — when omitted the whole record is
+            evaluated, serialized as JSON, unless the record has its own
+            top-level `text` field, which is then evaluated alone. The server
             serves this field only when populated.
+          x-celigo-ai-guidance:
+            - |-
+              Send the input selection here as `mapping`, not as Mapper 2.0
+              `mappings` rows. Map the field explicitly when records carry their
+              own `text` field.
           properties:
             fields:
               type: array

package/dist/import.yml

@@ -11854,10 +11854,15 @@ components:
               type: boolean
               default: false
               description: |-
-                When true, detected PII is replaced with masked values.
-                When false, PII is flagged without modification.
+                When true, the result also carries `masked`: the evaluated input with each detected
+                value replaced by asterisks. The record itself is unchanged. With whole-record input
+                (no `mapping`, and no top-level `text` field on the record), `masked` is the record
+                serialized as one JSON string. When false, PII is flagged only.
               x-celigo-ai-guidance:
-                - Whether to mask detected PII values in the output.
+                - |-
+                  Masking doesn't rewrite the record. To pass masked text on, select the field as the
+                  `text` input (`mapping`) and response-map `masked` back onto that field on the
+                  guardrail's flow step (`{"extract": "masked", "generate": "<field>"}`).
         moderation:
           type: object
           required:
@@ -12492,19 +12497,27 @@ components:
       properties:
         function:
           type: string
-          description: Function to invoke within the referenced script.
+          description: |-
+            Function to invoke: one in the script named by `_scriptId`, or one the code deployed on
+            the stack named by `_stackId` exposes.
           examples:
             - transformRecords
         _scriptId:
           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`. Send this or `_stackId`, not both.
         _stackId:
           type: string
           format: objectId
           x-celigo-refModel: stacks
-          description: Stack that hosts the hook logic, used instead of a script for stack-based deployments.
+          description: |-
+            Stack that hosts the hook logic, used instead of a script for stack-based deployments.
+            The API doesn't enforce the either/or: a save carrying both `_scriptId` and `_stackId`
+            answers 200 and stores both, and the script and the stack then each list the step as a
+            dependent.
+          x-celigo-ai-guidance:
+            - When moving a hook onto a stack, remove `_scriptId` and set `function` to the stack's function in the same update.
         configuration:
           type:
             - object
@@ -16408,7 +16421,11 @@ components:
                 - script
               description: |-
                 Hook that runs on each page of records before the import's mappings are applied.
-                Commonly used to reshape or filter records ahead of mapping.
+                Commonly used to reshape or filter records ahead of mapping. Its changes shape only
+                the request this import sends: the next step receives the record as it arrived here,
+                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`.
               x-celigo-ai-guidance:
                 - |-
                   Pre-map JavaScript hook — runs once per page BEFORE the
@@ -16430,7 +16447,8 @@ components:
               description: |-
                 Hook that runs after the import's mappings are applied but before records are sent
                 to the destination system. Commonly used for adjustments that need the mapped
-                (destination-shaped) record.
+                (destination-shaped) record. Like `preMap`, its changes shape only the request this
+                import sends; the next step never sees them.
               x-celigo-ai-guidance:
                 - |-
                   Post-map JavaScript hook — runs once per page AFTER the
@@ -16453,7 +16471,11 @@ components:
               description: |-
                 Hook that runs after the destination system responds, with access to both the
                 submitted records and the destination's responses. Commonly used to inspect results
-                or adjust the response data passed downstream.
+                or adjust the response data passed downstream. Each `options.responseData` entry is
+                one submitted record's result, in order: `statusCode`, `errors` (`{code, message,
+                source}`, empty on success), `ignored`, `id`, and `_json` — the destination's parsed
+                response body, where its own error detail sits (`_headers` holds the response
+                headers).
               x-celigo-ai-guidance:
                 - |-
                   Post-submit JavaScript hook — runs AFTER each batch of

package/dist/integration.yml

@@ -547,6 +547,8 @@ paths:
       description: |-
         Returns every revision entry (snapshots, pulls, reverts) for the integration, newest first.
         An integration with no revision history returns an empty response (204), not `[]`.
+      x-celigo-ai-guidance:
+        - To roll back a pull, find its revision here (its diff shows what it changed) and have the user revert it in the integration's Revisions tab with **Revert to before this revision**. The API can't start a revert, and writing old values back to the resources by hand misses what the pull created or deleted and records no revert.
       parameters:
         - name: _id
           in: path
@@ -4698,8 +4700,8 @@ components:
             - pull
             - revert
           x-enumDescriptions:
-            snapshot: Point-in-time capture of the current integration state.
-            pull: Changes pulled in from a related integration in another environment or clone.
+            snapshot: Point-in-time capture of the current integration state, taken when a user (or `POST /v1/integrations/{_id}/revisions/create`) asks for one.
+            pull: Changes pulled in from a related integration in another environment or clone. The pull's own revision keeps the state from before and after the merge (`beforeRevisionHash`, `afterRevisionHash`); no separate snapshot revisions are written for it.
             revert: Restoration of the integration to a prior revision state.
         status:
           type: string
@@ -4724,7 +4726,11 @@ components:
             - Stable baseline before deploying v2
         beforeRevisionHash:
           type: string
-          description: Content hash of the integration state prior to this revision.
+          description: |-
+            Content hash of the integration state prior to this revision. On a `pull` it is the
+            restore point that the Revisions tab's **Revert to before this revision** returns to:
+            the revert names the pull in `_revertToRevisionId` and copies this hash into
+            `revertToRevisionHash`.
           examples:
             - 34b7ae8d56563e242bc0bd42fd28874442657e58
         transactionHash:

package/dist/template.yml

@@ -331,9 +331,20 @@ paths:
         Check `type` on the `GET /v1/templates/{_id}/preview` response first.
 
         This one-shot install doesn't run a template's own install steps. A
-        template whose preview `Integration` object lists `installSteps` is
-        refused with nothing created; install it from the integrator.io
-        marketplace, whose installer runs those steps.
+        template whose preview `Integration` object lists a `template_zip`
+        install step (most published templates have one) is refused with 422
+        and nothing is created; install it from the integrator.io marketplace,
+        whose installer runs those steps.
+
+        Every request that reaches the platform starts a new install — there is
+        no idempotency key, so a retry after a timeout or an ambiguous failure
+        creates a second integration with its own flows, exports and imports.
+        Before retrying, look for the integration the first request created: one
+        carrying this template's `_templateId`, named like the preview's
+        `Integration` object, with a `createdAt` near the request.
+      x-celigo-ai-guidance:
+        - Read `GET /v1/templates/{_id}/preview` first. Every `Connection` object's `_id` must be a key of `connectionMap`, and an `installSteps` entry with `type` `template_zip` on the `Integration` object means this endpoint refuses the template — send the user to the marketplace installer instead.
+        - Never retry this POST after a timeout or an ambiguous failure without first listing integrations for one carrying this template's `_templateId`, created by the earlier request. If it exists, the install went through; a second request installs a duplicate.
       parameters:
         - name: _id
           in: path
@@ -446,8 +457,8 @@ paths:
         '422':
           description: |-
             Connection IDs in `connectionMap` do not match the template's
-            expected connection IDs, or the template has its own install steps
-            (a `template_zip` step this install doesn't run). Nothing is created.
+            expected connection IDs, or the template's install steps include a
+            `template_zip` step, which this install doesn't run. Nothing is created.
           content:
             application/json:
               schema:

package/dist/tool.yml

@@ -1124,7 +1124,13 @@ paths:
                   properties:
                     connections:
                       type: array
-                      description: Connection bindings, one per connection the Tool's steps reference.
+                      description: |-
+                        Connection bindings, one per connection the Tool's steps reference. Name the
+                        connection to run with in `_id`: a binding with only `_abstractId`, or with
+                        the connection in `_connectionId` instead, is refused with 422 "Invalid
+                        override at overrides.connections[0]. Connection override must include at
+                        least one of: _id, _borrowConcurrencyFromConnectionId,
+                        requiresEndUserCredentials."
                       items:
                         type: object
                         required:
@@ -1224,9 +1230,12 @@ paths:
           $ref: '#/components/responses/404-not-found'
         '422':
           description: |-
-            A step failed, or the Tool was refused before any step ran because its branches
-            don't all merge back (`tool_dangling_branch`). Either way the response includes
-            `invocationId` when logging is active, so the run can be opened in the run history.
+            A step failed, or the Tool was refused before any step ran: a connection binding is
+            missing (`connection_not_overridden`) or has no `_id`, or its branches don't all merge
+            back (`tool_dangling_branch`). A failed step answers 422 even when it has
+            `proceedOnFailure: true`: the later steps still run, but the response carries the error,
+            not the output. Either way the response includes `invocationId` when logging is active,
+            so the run can be opened in the run history.
           content:
             application/json:
               schema:
@@ -1256,6 +1265,11 @@ paths:
                         code: connection_not_overridden
                         message: 'Missing connection overrides. The following connection IDs must be overridden: 6ab1f5657b3d01a9084253a5.'
                     invocationId: 6ab1f5877cd5cdd66da1cc8b
+                binding_without_id:
+                  summary: A connection binding without `_id`
+                  value:
+                    errors:
+                      - message: 'Invalid override at overrides.connections[0]. Connection override must include at least one of: _id, _borrowConcurrencyFromConnectionId, requiresEndUserCredentials.'
   /v1/tools/{_id}/invocations:
     get:
       x-internal: false
@@ -2399,10 +2413,16 @@ paths:
         `GET /v1/tools/{_id}/test/run/{runId}/{_stepId}` to inspect stage-by-stage
         results. The run id for follow-up calls is the `flowJob._id` value.
 
-        A test run is not free of outside calls: lookups call their sources live. Imports never
-        send; each returns its saved `mockResponse`, or a placeholder response when none is saved
-        (see `mockResponse` on imports). A second test run started while one is still running is
-        refused with `test_run_not_allowed`.
+        A test run is not free of outside calls: a lookup export with no saved `mockOutput` calls
+        its source live, and the run then saves that response on the export as its `mockOutput`
+        (the export's `lastModified` changes). Every later test run that uses the export, from any
+        Tool or API and whatever its input, answers that lookup from the saved `mockOutput` instead
+        of calling the source: the lookup's `request` stage shows the request rendered from the new
+        input, and its `response` stage holds the saved records. Remove `mockOutput` from the export
+        to call the source again. `POST /v1/tools/{_id}/invoke` neither reads nor writes it. Imports
+        never send; each returns its saved `mockResponse`, or a placeholder response when none is
+        saved (see `mockResponse` on imports). A second test run started while one is still running
+        is refused with `test_run_not_allowed`.
 
         Test runs are a separate, short-lived history from normal runs — capture
         any follow-up step or log details soon after the run completes.
@@ -6373,10 +6393,9 @@ components:
         mockInput:
           type: object
           description: |
-            Mock data for testing the tool's input processing.
-
-            Provides sample input to test transformation logic and routing
-            without requiring live data. Maximum size: 1MB.
+            Sample input saved with the tool. `POST /v1/tools/{_id}/test/run` doesn't read it:
+            send it as that call's `input`, or the run starts from an empty record. Maximum
+            size: 1MB.
           additionalProperties: true
     Output:
       type: object
@@ -6720,16 +6739,19 @@ components:
                     items: {}
                     examples:
                       - - equals
-                        - - get
-                          - customerType
+                        - - string
+                          - - extract
+                            - customerType
                         - premium
                       - - and
-                        - - exists
-                          - - get
-                            - orderId
-                        - - greaterThan
-                          - - get
-                            - amount
+                        - - notempty
+                          - - string
+                            - - extract
+                              - orderId
+                        - - greaterthan
+                          - - number
+                            - - extract
+                              - amount
                           - 1000
               nextRouterId:
                 type: string
@@ -6780,9 +6802,11 @@ components:
                         - 60a2c4e6f321d800129a1a3c
                     proceedOnFailure:
                       type: boolean
-                      description: |
-                        Whether to continue processing subsequent steps if this
-                        processor fails.
+                      description: |-
+                        When true, the later steps and the output stage still run after this
+                        processor fails; when false, they're skipped. Either way a direct
+                        `POST /v1/tools/{_id}/invoke` answers 422 with the failed step's error,
+                        without the output.
                     setupInProgress:
                       type: boolean
                       description: |
@@ -23242,10 +23266,15 @@ components:
               type: boolean
               default: false
               description: |-
-                When true, detected PII is replaced with masked values.
-                When false, PII is flagged without modification.
+                When true, the result also carries `masked`: the evaluated input with each detected
+                value replaced by asterisks. The record itself is unchanged. With whole-record input
+                (no `mapping`, and no top-level `text` field on the record), `masked` is the record
+                serialized as one JSON string. When false, PII is flagged only.
               x-celigo-ai-guidance:
-                - Whether to mask detected PII values in the output.
+                - |-
+                  Masking doesn't rewrite the record. To pass masked text on, select the field as the
+                  `text` input (`mapping`) and response-map `masked` back onto that field on the
+                  guardrail's flow step (`{"extract": "masked", "generate": "<field>"}`).
         moderation:
           type: object
           required:
@@ -23880,19 +23909,27 @@ components:
       properties:
         function:
           type: string
-          description: Function to invoke within the referenced script.
+          description: |-
+            Function to invoke: one in the script named by `_scriptId`, or one the code deployed on
+            the stack named by `_stackId` exposes.
           examples:
             - transformRecords
         _scriptId:
           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`. Send this or `_stackId`, not both.
         _stackId:
           type: string
           format: objectId
           x-celigo-refModel: stacks
-          description: Stack that hosts the hook logic, used instead of a script for stack-based deployments.
+          description: |-
+            Stack that hosts the hook logic, used instead of a script for stack-based deployments.
+            The API doesn't enforce the either/or: a save carrying both `_scriptId` and `_stackId`
+            answers 200 and stores both, and the script and the stack then each list the step as a
+            dependent.
+          x-celigo-ai-guidance:
+            - When moving a hook onto a stack, remove `_scriptId` and set `function` to the stack's function in the same update.
         configuration:
           type:
             - object
@@ -25289,7 +25326,11 @@ components:
                 - script
               description: |-
                 Hook that runs on each page of records before the import's mappings are applied.
-                Commonly used to reshape or filter records ahead of mapping.
+                Commonly used to reshape or filter records ahead of mapping. Its changes shape only
+                the request this import sends: the next step receives the record as it arrived here,
+                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`.
               x-celigo-ai-guidance:
                 - |-
                   Pre-map JavaScript hook — runs once per page BEFORE the
@@ -25311,7 +25352,8 @@ components:
               description: |-
                 Hook that runs after the import's mappings are applied but before records are sent
                 to the destination system. Commonly used for adjustments that need the mapped
-                (destination-shaped) record.
+                (destination-shaped) record. Like `preMap`, its changes shape only the request this
+                import sends; the next step never sees them.
               x-celigo-ai-guidance:
                 - |-
                   Post-map JavaScript hook — runs once per page AFTER the
@@ -25334,7 +25376,11 @@ components:
               description: |-
                 Hook that runs after the destination system responds, with access to both the
                 submitted records and the destination's responses. Commonly used to inspect results
-                or adjust the response data passed downstream.
+                or adjust the response data passed downstream. Each `options.responseData` entry is
+                one submitted record's result, in order: `statusCode`, `errors` (`{code, message,
+                source}`, empty on success), `ignored`, `id`, and `_json` — the destination's parsed
+                response body, where its own error detail sits (`_headers` holds the response
+                headers).
               x-celigo-ai-guidance:
                 - |-
                   Post-submit JavaScript hook — runs AFTER each batch of
@@ -37412,8 +37458,11 @@ components:
                 filter, before the page is sent to downstream steps; commonly used to flatten
                 structures, drop unwanted records, or add computed fields. It receives the page as
                 `options.data` (with `errors`, `pageIndex`, `configuration` and `settings`) and returns
-                `{data, errors, abort, newErrorsAndRetryData}`. An exception thrown here fails every
-                record on that page, each with its own retry data, and later pages still run.
+                `{data, errors, abort, newErrorsAndRetryData}`. Return that object, not the array: a
+                hook that returns `options.data` itself, or a filtered copy, drops the page without an
+                error, and the run completes with 0 records, 0 errors and 0 pages. An exception thrown
+                here fails every record on that page, each with its own retry data, and later pages
+                still run.
               properties:
                 function:
                   type: string

package/dist/user.yml

@@ -577,13 +577,14 @@ paths:
                     - user2@example.com
                   accessLevel: monitor
               integrationOnly:
-                summary: Invite with per-integration access
+                summary: Invite with access to one integration only, MFA required
                 value:
                   emails:
                     - contractor@example.com
                   integrationAccessLevel:
                     - _integrationId: 68f52162f00a35a1b26eaafb
                       accessLevel: manage
+                  accountMFARequired: true
       responses:
         '200':
           description: Array of results, one per email.
@@ -666,6 +667,11 @@ components:
             yourself — omit `accessLevel` and use `integrationAccessLevel` for integration-only access.
           x-celigo-ai-guidance:
             - Choose the `accessLevel` value based on what the user should be able to do across the account.
+            - |-
+              For access to specific integrations only, omit `accessLevel` entirely. Any account-wide
+              value, `monitor` included, covers every integration in the account, including ones
+              created later, so pairing it with `integrationAccessLevel` widens access rather than
+              limiting it.
             - |-
               On PUT, "omit" means "clear" for integrationAccessLevel and accountMFARequired — GET the
               record first and resend both with the new accessLevel. accountSSORequired keeps its stored
@@ -731,6 +737,7 @@ components:
             omitted on update — resend it with every `PUT /v1/ashares/{_id}`.
           x-celigo-ai-guidance:
             - Whether the invited user must use MFA to access this account.
+            - The invite body takes it too, so require MFA in the invite itself rather than with a follow-up update, which must resend `integrationAccessLevel` and this flag or clears them.
         allowAccessToAPIM:
           type: boolean
           description: When true, the user can access API Management (APIM) features for this account.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.148",
+  "version": "0.2.150",
   "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": "c5f16e90",
+		"iasCommit": "4f24ed04",
 		"generatedAt": "2026-10-21"
 	},
 	"roots": {
@@ -1563,11 +1563,13 @@
 				"object"
 			],
 			"p": {
+				"_json": 10,
 				"dataURI": 1,
 				"errors": 132,
 				"flagged": 9,
 				"ignored": 9,
 				"masked": 1,
+				"reasoning": 1,
 				"statusCode": 124
 			}
 		},