@celigo/api-specs 0.2.149 → 0.2.151

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" %}
@@ -906,12 +914,17 @@ components:
                   run at `default` regardless of what's set here.
             output:
               type: object
-              description: Output format configuration
+              description: |-
+                Output format configuration. A guardrail stores `format` but doesn't use it: the
+                request to the model always carries the guardrail's own `validation_result` JSON
+                schema (`flagged`, `reasoning`, `confidence`), and the result returns `flagged` and
+                `reasoning` whatever `format` holds.
               properties:
                 format:
                   type: object
                   description: |
-                    Controls the structure of the model's output.
+                    Stored output structure. The request to the model uses the guardrail's own
+                    verdict schema instead (see `output`).
                   properties:
                     type:
                       type: string
@@ -920,10 +933,10 @@ components:
                         - json_schema
                         - blob
                       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.
-                      description: Output format type.
+                        text: Stored format type; the model request still uses the guardrail's verdict schema.
+                        json_schema: A stored JSON schema (`jsonSchema`); the model request still uses the guardrail's verdict schema.
+                        blob: Stored format type; the model request still uses the guardrail's verdict schema.
+                      description: Output format type, as stored.
                     schemaMode:
                       type: string
                       enum:
@@ -933,9 +946,9 @@ components:
                         manual: The schema editor opens `jsonSchema` in the visual field-by-field view
                         json: The schema editor opens `jsonSchema` in the raw JSON view
                       description: |-
-                        Which view a schema editor opens `jsonSchema` in; the schema sent to the
-                        provider is the same either way. Stored and echoed on guardrails for parity
-                        with the AI-agent format block — the guardrail form does not set it today.
+                        Which view a schema editor opens `jsonSchema` in. Stored and echoed on
+                        guardrails for parity with the AI-agent format block — the guardrail form
+                        does not set it today, and neither view changes the model request.
                       x-celigo-ai-guidance:
                         - |-
                           Resend the stored value on every update — a full PUT that omits the field
@@ -947,18 +960,20 @@ components:
                       x-celigo-ui-override: Required by the AI agent form when output format type is json_schema. Encoded here to mirror the form so builders produce connectable configurations.
                     strict:
                       type: boolean
-                      description: When true, enforces strict schema validation on output.
+                      description: Stored strict-validation flag for `jsonSchema`. A guardrail's model request uses its own verdict schema, so this doesn't apply there.
                       x-celigo-ai-guidance:
-                        - Whether to enforce strict schema validation on output
+                        - Stored only on a guardrail; it doesn't change the guardrail's verdict.
                     jsonSchema:
                       type: object
                       description: |
-                        JSON Schema for structured output. Required when `format.type` is "json_schema".
+                        Stored JSON Schema. Required when `format.type` is "json_schema". A guardrail
+                        doesn't send it to the model; the request carries the `validation_result`
+                        verdict schema instead.
                       x-celigo-ui-override: Required by the AI agent form when output format type is json_schema. Encoded here to mirror the form so builders produce connectable configurations.
                       properties:
                         type:
                           type: string
-                          description: Root JSON Schema type of the structured output; use "object" for record-shaped results.
+                          description: Root type of the stored JSON Schema.
                           enum:
                             - object
                             - array
@@ -976,15 +991,15 @@ components:
                         properties:
                           type: object
                           additionalProperties: true
-                          description: JSON Schema definitions for each field the structured output may contain.
+                          description: Field definitions in the stored JSON Schema.
                         required:
                           type: array
-                          description: Property names the model must include in the structured output.
+                          description: Property names the stored JSON Schema marks as required.
                           items:
                             type: string
                         additionalproperties:
                           type: boolean
-                          description: When true, the structured output may include properties beyond those defined in `properties`.
+                          description: Whether the stored JSON Schema allows properties beyond those in `properties`.
                     schema:
                       type: object
                       readOnly: true
@@ -1762,10 +1777,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 +2172,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 +2233,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 +2251,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 +2346,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

@@ -10968,12 +10968,17 @@ components:
                   run at `default` regardless of what's set here.
             output:
               type: object
-              description: Output format configuration
+              description: |-
+                Output format configuration. A guardrail stores `format` but doesn't use it: the
+                request to the model always carries the guardrail's own `validation_result` JSON
+                schema (`flagged`, `reasoning`, `confidence`), and the result returns `flagged` and
+                `reasoning` whatever `format` holds.
               properties:
                 format:
                   type: object
                   description: |
-                    Controls the structure of the model's output.
+                    Stored output structure. The request to the model uses the guardrail's own
+                    verdict schema instead (see `output`).
                   properties:
                     type:
                       type: string
@@ -10982,10 +10987,10 @@ components:
                         - json_schema
                         - blob
                       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.
-                      description: Output format type.
+                        text: Stored format type; the model request still uses the guardrail's verdict schema.
+                        json_schema: A stored JSON schema (`jsonSchema`); the model request still uses the guardrail's verdict schema.
+                        blob: Stored format type; the model request still uses the guardrail's verdict schema.
+                      description: Output format type, as stored.
                     schemaMode:
                       type: string
                       enum:
@@ -10995,9 +11000,9 @@ components:
                         manual: The schema editor opens `jsonSchema` in the visual field-by-field view
                         json: The schema editor opens `jsonSchema` in the raw JSON view
                       description: |-
-                        Which view a schema editor opens `jsonSchema` in; the schema sent to the
-                        provider is the same either way. Stored and echoed on guardrails for parity
-                        with the AI-agent format block — the guardrail form does not set it today.
+                        Which view a schema editor opens `jsonSchema` in. Stored and echoed on
+                        guardrails for parity with the AI-agent format block — the guardrail form
+                        does not set it today, and neither view changes the model request.
                       x-celigo-ai-guidance:
                         - |-
                           Resend the stored value on every update — a full PUT that omits the field
@@ -11009,18 +11014,20 @@ components:
                       x-celigo-ui-override: Required by the AI agent form when output format type is json_schema. Encoded here to mirror the form so builders produce connectable configurations.
                     strict:
                       type: boolean
-                      description: When true, enforces strict schema validation on output.
+                      description: Stored strict-validation flag for `jsonSchema`. A guardrail's model request uses its own verdict schema, so this doesn't apply there.
                       x-celigo-ai-guidance:
-                        - Whether to enforce strict schema validation on output
+                        - Stored only on a guardrail; it doesn't change the guardrail's verdict.
                     jsonSchema:
                       type: object
                       description: |
-                        JSON Schema for structured output. Required when `format.type` is "json_schema".
+                        Stored JSON Schema. Required when `format.type` is "json_schema". A guardrail
+                        doesn't send it to the model; the request carries the `validation_result`
+                        verdict schema instead.
                       x-celigo-ui-override: Required by the AI agent form when output format type is json_schema. Encoded here to mirror the form so builders produce connectable configurations.
                       properties:
                         type:
                           type: string
-                          description: Root JSON Schema type of the structured output; use "object" for record-shaped results.
+                          description: Root type of the stored JSON Schema.
                           enum:
                             - object
                             - array
@@ -11038,15 +11045,15 @@ components:
                         properties:
                           type: object
                           additionalProperties: true
-                          description: JSON Schema definitions for each field the structured output may contain.
+                          description: Field definitions in the stored JSON Schema.
                         required:
                           type: array
-                          description: Property names the model must include in the structured output.
+                          description: Property names the stored JSON Schema marks as required.
                           items:
                             type: string
                         additionalproperties:
                           type: boolean
-                          description: When true, the structured output may include properties beyond those defined in `properties`.
+                          description: Whether the stored JSON Schema allows properties beyond those in `properties`.
                     schema:
                       type: object
                       readOnly: true
@@ -11854,10 +11861,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 +12504,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/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/mcp-server.yml

@@ -5139,7 +5139,12 @@ components:
           type: boolean
           description: |
             When true, uses iClient-managed OAuth credentials (clientId/clientSecret)
-            instead of the values in this configuration.
+            instead of the values in this configuration. The iClient is the connection's
+            `_iClientId` — on an HTTP connection `http._iClientId`, beside `auth`, not inside it —
+            and it also supplies the grant type and the authorization and token endpoints, so a
+            create needs only `auth.type: "oauth"`, `auth.oauth.useIClientFields: true` and the
+            iClient id. The connection holds no tokens until a person completes the authorization
+            in a browser.
         oauth1:
           type: object
           description: |-
@@ -5268,7 +5273,7 @@ components:
       x-celigo-ai-guidance:
         - |-
           ## OAUTH 2.0 GRANT TYPES
-          - "authorizationcode" — Authorization Code flow (browser-based user consent).
+          - "authorizecode" — Authorization Code flow (browser-based user consent).
             Requires authURI, tokenURI, and user authorization via browser.
           - "clientcredentials" — Client Credentials flow (server-to-server, no user).
             Requires tokenURI, clientId, clientSecret.
@@ -5859,7 +5864,11 @@ components:
                   description: |
                     The API key or bearer token value (encrypted at rest); returned masked as `"******"`.
                     On update, the mask sent back keeps the stored token; a new value replaces it.
-                    Required unless automatic token refresh is configured.
+                    Required unless automatic token refresh is configured: a token block without a
+                    token must carry a `refreshMethod`, so a create or update that sends neither fails
+                    with 422 `Expected field: refreshMethod to be present.` To create a static-token
+                    connection before the real token is available, send a placeholder value and
+                    replace it later.
                   examples:
                     - my-api-token-EXAMPLE
                 location:
@@ -8065,7 +8074,11 @@ components:
           description: |
             The API key or bearer token value (encrypted at rest); returned masked as `"******"`.
             On update, the mask sent back keeps the stored token; a new value replaces it.
-            Required unless automatic token refresh is configured.
+            Required unless automatic token refresh is configured: a token block without a
+            token must carry a `refreshMethod`, so a create or update that sends neither fails
+            with 422 `Expected field: refreshMethod to be present.` To create a static-token
+            connection before the real token is available, send a placeholder value and
+            replace it later.
           examples:
             - my-api-token-EXAMPLE
         location:

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: