@celigo/api-specs 0.2.169 → 0.2.171

package/dist/fileserver.yml

@@ -9,7 +9,9 @@ info:
       (`GET`/`PUT /v1/mft/fileserver`) and the partner accounts that log in to it
       (`/v1/mft/fileserver/accounts`), each chrooted to a Celigo Storage folder. Requires a
       full-access API token — folder-path-scoped and other restricted tokens answer 403
-      FILESERVER_FULL_ACCESS_TOKEN_REQUIRED on every route.
+      FILESERVER_FULL_ACCESS_TOKEN_REQUIRED on every route, and so does every personal access
+      token, whatever its creator's role. Only the account owner and administrators may manage
+      the server.
 servers:
   - url: https://api.integrator.io
     description: Production (US / default region)
@@ -24,7 +26,7 @@ security:
 tags:
   - name: File Server
     description: |-
-      Each environment can run a Celigo-hosted SFTP file server. Enabling it claims a permanent `identifier` that becomes part of every partner login (`<username>@<identifier>`) and exposes the shared endpoint and host-key fingerprints partners need to connect. Partner accounts are created under the server, each with its own password and a Celigo Storage folder that becomes the account's root, so files a partner uploads appear in that folder and files placed there are what the partner can download. The account's license must include the file server add-on (`fileserver.enabled`), and every call needs a full-access API token.
+      Each environment can run a Celigo-hosted SFTP file server. Enabling it claims a permanent `identifier` that becomes part of every partner login (`<username>@<identifier>`) and exposes the shared endpoint and host-key fingerprints partners need to connect. Partner accounts are created under the server, each with its own password and a Celigo Storage folder that becomes the account's root, so files a partner uploads appear in that folder and files placed there are what the partner can download. The account's license must include the file server add-on (`fileserver.enabled`), and every call needs a full-access API token: scoped tokens and personal access tokens are refused, and so are manage, monitor and integration-level users.
 
       ## File server and account schemas
 
@@ -87,7 +89,11 @@ paths:
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '403':
-          description: The token is not a full-access API token (`FILESERVER_FULL_ACCESS_TOKEN_REQUIRED`).
+          description: |-
+            The token is not a full-access API token (`FILESERVER_FULL_ACCESS_TOKEN_REQUIRED`). A
+            personal access token is refused the same way as a scoped token, and a manage, monitor
+            or integration-level user gets `access_restricted`: only the owner and administrators
+            manage the file server.
           content:
             application/json:
               schema:
@@ -98,6 +104,12 @@ paths:
                     errors:
                       - code: FILESERVER_FULL_ACCESS_TOKEN_REQUIRED
                         message: The file server management APIs require an API token with full access
+                notAdministrator:
+                  summary: A manage, monitor or integration-level user
+                  value:
+                    errors:
+                      - code: access_restricted
+                        message: The role which you are associated with doesn't have the required permissions to perform the action.
         '404':
           description: The environment is entitled but its server has never been enabled (`FILESERVER_NOT_FOUND`).
           content:
@@ -220,7 +232,7 @@ paths:
           description: |-
             The token is not a full-access API token (`FILESERVER_FULL_ACCESS_TOKEN_REQUIRED`),
             the account's license lacks the file server add-on or the environment is a
-            sandbox (`FILESERVER_NOT_ENTITLED`).
+            sandbox (`FILESERVER_NOT_ENTITLED`). A personal access token is refused the same way as a scoped token, and a manage, monitor or integration-level user gets `access_restricted`: only the owner and administrators manage the file server.
           content:
             application/json:
               schema:
@@ -231,6 +243,12 @@ paths:
                     errors:
                       - code: FILESERVER_NOT_ENTITLED
                         message: The file server add-on is not enabled for this account
+                notAdministrator:
+                  summary: A manage, monitor or integration-level user
+                  value:
+                    errors:
+                      - code: access_restricted
+                        message: The role which you are associated with doesn't have the required permissions to perform the action.
         '404':
           description: A disable was sent for an environment whose server was never enabled (`FILESERVER_NOT_FOUND`).
           content:
@@ -396,7 +414,11 @@ paths:
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '403':
-          description: The token is not a full-access API token (`FILESERVER_FULL_ACCESS_TOKEN_REQUIRED`), or the environment is a sandbox (`FILESERVER_NOT_ENTITLED`).
+          description: |-
+            The token is not a full-access API token (`FILESERVER_FULL_ACCESS_TOKEN_REQUIRED`), or
+            the environment is a sandbox (`FILESERVER_NOT_ENTITLED`). A personal access token is
+            refused the same way as a scoped token, and a manage, monitor or integration-level user
+            gets `access_restricted`: only the owner and administrators manage the file server.
           content:
             application/json:
               schema:
@@ -407,6 +429,12 @@ paths:
                     errors:
                       - code: FILESERVER_FULL_ACCESS_TOKEN_REQUIRED
                         message: The file server management APIs require an API token with full access
+                notAdministrator:
+                  summary: A manage, monitor or integration-level user
+                  value:
+                    errors:
+                      - code: access_restricted
+                        message: The role which you are associated with doesn't have the required permissions to perform the action.
         '422':
           description: The environment's server has never been enabled (`FILESERVER_NOT_ENABLED`); a disabled server is still manageable.
           content:
@@ -487,7 +515,7 @@ paths:
             The token is not a full-access API token (`FILESERVER_FULL_ACCESS_TOKEN_REQUIRED`);
             the license lacks the add-on or the environment is a sandbox
             (`FILESERVER_NOT_ENTITLED`); or the environment already holds
-            `limits.maxAccounts` enabled accounts (`FILESERVER_MAX_ACCOUNTS_EXCEEDED`).
+            `limits.maxAccounts` enabled accounts (`FILESERVER_MAX_ACCOUNTS_EXCEEDED`). A personal access token is refused the same way as a scoped token, and a manage, monitor or integration-level user gets `access_restricted`: only the owner and administrators manage the file server.
           content:
             application/json:
               schema:
@@ -498,6 +526,12 @@ paths:
                     errors:
                       - code: FILESERVER_MAX_ACCOUNTS_EXCEEDED
                         message: The maximum number of enabled accounts for this environment has been reached
+                notAdministrator:
+                  summary: A manage, monitor or integration-level user
+                  value:
+                    errors:
+                      - code: access_restricted
+                        message: The role which you are associated with doesn't have the required permissions to perform the action.
         '409':
           description: Another account in this environment already has that username, enabled or not (`FILESERVER_USERNAME_TAKEN`).
           content:
@@ -688,7 +722,7 @@ paths:
             The token is not a full-access API token (`FILESERVER_FULL_ACCESS_TOKEN_REQUIRED`);
             the license lacks the add-on or the environment is a sandbox
             (`FILESERVER_NOT_ENTITLED`); or re-enabling would exceed `limits.maxAccounts`
-            (`FILESERVER_MAX_ACCOUNTS_EXCEEDED`).
+            (`FILESERVER_MAX_ACCOUNTS_EXCEEDED`). A personal access token is refused the same way as a scoped token, and a manage, monitor or integration-level user gets `access_restricted`: only the owner and administrators manage the file server.
           content:
             application/json:
               schema:
@@ -699,6 +733,12 @@ paths:
                     errors:
                       - code: FILESERVER_MAX_ACCOUNTS_EXCEEDED
                         message: The maximum number of enabled accounts for this environment has been reached
+                notAdministrator:
+                  summary: A manage, monitor or integration-level user
+                  value:
+                    errors:
+                      - code: access_restricted
+                        message: The role which you are associated with doesn't have the required permissions to perform the action.
         '404':
           $ref: '#/components/responses/404-account-not-found'
         '409':
@@ -1407,7 +1447,12 @@ components:
               value:
                 message: Bearer Authentication Failed
     403-full-access-required:
-      description: The token is not a full-access API token (`FILESERVER_FULL_ACCESS_TOKEN_REQUIRED`), or the license lacks the add-on / the environment is a sandbox (`FILESERVER_NOT_ENTITLED`).
+      description: |-
+        The token is not a full-access API token (`FILESERVER_FULL_ACCESS_TOKEN_REQUIRED`) --
+        a scoped API token, or any personal access token, which never counts as full access --
+        or the license lacks the add-on / the environment is a sandbox (`FILESERVER_NOT_ENTITLED`).
+        A manage, monitor or integration-level user is refused with `access_restricted`: only the
+        account owner and administrators manage the file server.
       content:
         application/json:
           schema:
@@ -1418,6 +1463,12 @@ components:
                 errors:
                   - code: FILESERVER_FULL_ACCESS_TOKEN_REQUIRED
                     message: The file server management APIs require an API token with full access
+            notAdministrator:
+              summary: A manage, monitor or integration-level user
+              value:
+                errors:
+                  - code: access_restricted
+                    message: The role which you are associated with doesn't have the required permissions to perform the action.
     404-account-not-found:
       description: No account with this id in the caller's environment, or the id is not a valid identifier (`FILESERVER_ACCOUNT_NOT_FOUND`).
       content:

package/dist/flow.yml

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

package/dist/guardrail.yml

@@ -594,9 +594,9 @@ components:
         LLM configuration for an `ai_agent` guardrail — which provider and model evaluate each
         record, with instructions, parameter tuning, and output format. Guardrails never invoke
         tools, so unlike an AI agent import no block here accepts a `tools` array. MCP `prompts`
-        and `resources` are accepted on save, but an unreachable MCP server doesn't fail the
-        run (verified on OpenAI), so put the policy the guardrail must apply in its
-        instructions. Providers come in two families with two configuration formats:
+        and `resources` are accepted on save but never used at run time, so put the policy the
+        guardrail must apply in its instructions. Providers come in two families with two
+        configuration formats:
 
         - **Built-in providers** — each has its own configuration block.
           - **openai**: OpenAI models (GPT-4.1, GPT-5, etc.). Configure via the `openai` object.
@@ -761,7 +761,7 @@ components:
           type: array
           description: |-
             MCP prompt entries saved with a catalog-provider guardrail (generic flat format).
-            Each entry references one MCP connection and the prompt names allowed from it.
+            Each entry references one MCP connection and prompt names; a guardrail's run never fetches them.
           items:
             type: object
             properties:
@@ -782,7 +782,7 @@ components:
                     description: Connection to the MCP server that exposes the prompts.
                   allowedPrompts:
                     type: array
-                    description: Prompt names the model may fetch from the server.
+                    description: Prompt names saved with the entry; a guardrail's run never fetches them.
                     items:
                       type: string
           x-celigo-ai-guidance:
@@ -1039,7 +1039,7 @@ components:
               type: array
               description: |-
                 MCP prompt entries saved with the guardrail. Each item references one
-                MCP connection and the prompt names allowed from it.
+                MCP connection and prompt names; a guardrail's run never fetches them.
               items:
                 type: object
                 properties:
@@ -1061,7 +1061,7 @@ components:
                         description: Connection to the MCP server.
                       allowedPrompts:
                         type: array
-                        description: Prompt names to allow from the MCP server.
+                        description: Prompt names saved with the entry; a guardrail's run never fetches them.
                         items:
                           type: string
             resources:
@@ -1228,7 +1228,7 @@ components:
                       type: array
                       description: |-
                         MCP prompt entries saved with a Gemini guardrail. Each item references one
-                        MCP connection and the prompt names allowed from it.
+                        MCP connection and prompt names; a guardrail's run never fetches them.
                       items:
                         type: object
                         properties:
@@ -1250,7 +1250,7 @@ components:
                                 description: Connection to the MCP server.
                               allowedPrompts:
                                 type: array
-                                description: Prompt names to allow from the MCP server.
+                                description: Prompt names saved with the entry; a guardrail's run never fetches them.
                                 items:
                                   type: string
                     resources:
@@ -1450,7 +1450,7 @@ components:
                       type: array
                       description: |-
                         MCP prompt entries saved with a Claude guardrail. Each item references one
-                        MCP connection and the prompt names allowed from it.
+                        MCP connection and prompt names; a guardrail's run never fetches them.
                       items:
                         type: object
                         properties:
@@ -1472,7 +1472,7 @@ components:
                                 description: Connection to the MCP server.
                               allowedPrompts:
                                 type: array
-                                description: Prompt names to allow from the MCP server.
+                                description: Prompt names saved with the entry; a guardrail's run never fetches them.
                                 items:
                                   type: string
                     resources:
@@ -1544,10 +1544,9 @@ components:
           (`aiAgent.tools`, `aiAgent.openai.tools`, `aiAgent.litellm._overrides.gemini.tools`,
           `aiAgent.litellm._overrides.anthropic.tools`) fails the save with 422
           `guardrail_tools_not_allowed`. MCP `prompts` and `resources` are still accepted on
-          save, but don't rely on them for the check: with their MCP server unreachable, a
-          guardrail runs on its instructions and input alone, with no error, where an AI agent's
-          run fails (verified on OpenAI). Put the policy the guardrail must apply in its
-          instructions.
+          save, but a guardrail's run never uses them: it gives the model only its instructions
+          and input, whether the MCP server can be reached or not. Put the policy the guardrail
+          must apply in its instructions.
       properties:
         type:
           type: string
@@ -2177,7 +2176,8 @@ components:
             mapping:
               type: object
               description: |-
-                Mapper 1.0 input mapping that selects the field evaluated as `text`.
+                Mapper 1.0 input mapping that selects what is evaluated: a field mapped
+                to `text`, or an object mapped to `record` (evaluated as its JSON).
                 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).
@@ -2353,7 +2353,8 @@ components:
             record field to the `text` input (e.g.
             `{"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
+            scanned nor masked. A mapping can also generate `record`, an object
+            evaluated as its JSON. 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.
@@ -2362,10 +2363,13 @@ components:
               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.
+            - |-
+              A guardrail keeps no conversation history, so a mapped
+              `conversationHistoryId` changes nothing.
           properties:
             fields:
               type: array
-              description: Field-level mapping entries; `generate` targets the guardrail input (typically `text`).
+              description: Field-level mapping entries; `generate` targets the guardrail input (`text`, or `record` for an object).
               items:
                 $ref: '#/components/schemas/MappingField'
             lists:

package/dist/import.yml

@@ -1572,12 +1572,25 @@ components:
               Use `assistant_graphql` as the default value if there is a connector available
               for the system and the connector supports GraphQL.
             - |-
-              The value selects the editor only. Each `http.body[]` entry stays a template STRING — a
+              The value selects the editor and changes one thing in a GraphQL request: under
+              `graph_ql` and `assistant_graphql`, a `variables` member stored as a JSON string is
+              parsed and sent as an object, while under `http` it is sent as the string; an object
+              `variables` goes out unchanged under `graph_ql` and `http`. Live-verified 2026-10-22 with import
+              previews against an echo endpoint: a string `variables` under `graph_ql`,
+              `assistant_graphql` and `http`, and an object `variables` under `graph_ql` and `http`.
+            - |-
+              Each `http.body[]` entry stays a template STRING — a
               stringified `{"query", "operationName", "variables"}` envelope, one per operation for the
               update/create pair (`http.body[0]` / `http.body[1]`); never an object entry, which is stored
               as-is and does not render. The GraphQL form parses that string to show each member in its
               own field and re-stringifies it on save; an entry that is not parseable JSON at rest renders
-              those fields empty, so keep templated variables inside a JSON string value.
+              those fields empty, so keep templated variables inside a JSON string value. When
+              `variables` is itself a JSON string, the string values inside it sit two JSON levels
+              deep: write them as `\"{{jsonEncode record.x}}\"` with double braces, because a plain
+              `{{record.x}}`, or a triple-brace `jsonEncode`, fails a record whose value holds a quote
+              with 422 `invalid_json` before the request is sent. An object or array there is
+              `{{jsonSerialize record.x}}`, also with double braces; `{{{jsonSerialize record.x}}}`
+              fails the same way (live-verified 2026-10-22).
             - |-
               Create GraphQL imports on a `graph_ql` connection (or a connector connection bound to its
               GraphQL API): that setup offers the Form view toggle between the GraphQL editor and the
@@ -2394,13 +2407,20 @@ components:
 
                 Each entry is a DOT-PATH STRING, or null for an operation
                 with no ID path configured. When not specified, the platform
-                looks for standard `id` or `_id` fields automatically.
+                looks for standard `id` or `_id` fields automatically. When
+                set, a response with no value at the path fails the record
+                with `missing_id`, quoting the response.
               x-celigo-ai-guidance:
                 - |-
                   Common LLM mistake:
                   splitting a single dot-path like ``"data.id"`` into array segments ``["data",
                   "id"]`` — DO NOT do this.
                   See the ``response`` object docs above.
+                - |-
+                  For a GraphQL mutation, point it at the id only a successful call returns
+                  (``["data.customerCreate.customer.id"]``): a 200 that carries top-level ``errors``
+                  or the mutation's ``userErrors`` then fails the record with ``missing_id`` instead
+                  of counting as written. Live-verified 2026-10-22 against an echo endpoint.
               examples:
                 - - id
                 - - data.id
@@ -2474,11 +2494,23 @@ components:
                 available, set both — the platform evaluates ``successPath``
                 first and falls through to ``failPath`` only when the
                 success check is inconclusive.
+
+                Without ``failValues``, a truthy value at the path fails
+                the response. A path that resolves to an array matches only
+                when the array has exactly one element.
+              x-celigo-ai-guidance:
+                - |-
+                  A GraphQL API usually reports a failed mutation with HTTP 200 and an ``errors`` array, which
+                  counts as written when no rule catches it. ``failPath: ["errors"]`` fails the record
+                  for one error and lets two or more through; use ``["errors[0].message"]`` with
+                  ``errorPath: "errors[0].message"`` so the record fails with the server's message.
+                  Live-verified 2026-10-22 with import runs against an echo endpoint.
               examples:
                 - - error
                 - - success
                 - - error
                   - error
+                - - errors[0].message
             failValues:
               type: array
               items:
@@ -9642,7 +9674,7 @@ components:
                       x-enumDescriptions:
                         text: Free-form text response from the model.
                         json_schema: Structured JSON output conforming to a defined schema.
-                        blob: Binary data output for non-text content.
+                        blob: Image generation — the run calls the image generation tool and returns the stored image's `blobKey`, not `_text` or `_json`.
                       default: text
                       description: Output format type.
                     schemaMode:
@@ -9864,11 +9896,6 @@ components:
                               an object without a non-empty name fails with a
                               missing-required-field error. String entries are the
                               legacy form and stay valid.
-                      allowedPrompts:
-                        type: array
-                        description: Specific prompts to allow from the MCP server (used for MCP prompt entries; all if omitted).
-                        items:
-                          type: string
                   tool:
                     type: object
                     description: |
@@ -10011,7 +10038,7 @@ components:
                   x-enumDescriptions:
                     text: Free-form text response from the model.
                     json_schema: Structured JSON output conforming to a defined schema.
-                    blob: Binary data output for non-text content.
+                    blob: Image generation — the run returns the stored image's `blobKey`, not `_text` or `_json`.
                   default: text
                 schemaMode:
                   type: string
@@ -10180,11 +10207,6 @@ components:
                                       description: Display description shown for the tool.
                                   required:
                                     - name
-                              allowedPrompts:
-                                type: array
-                                description: Specific prompts to allow from the MCP server (used for MCP prompt entries; all if omitted).
-                                items:
-                                  type: string
                           tool:
                             type: object
                             description: Reference to a Celigo Tool resource, used when type is "tool".
@@ -10697,9 +10719,9 @@ components:
         LLM configuration for an `ai_agent` guardrail — which provider and model evaluate each
         record, with instructions, parameter tuning, and output format. Guardrails never invoke
         tools, so unlike an AI agent import no block here accepts a `tools` array. MCP `prompts`
-        and `resources` are accepted on save, but an unreachable MCP server doesn't fail the
-        run (verified on OpenAI), so put the policy the guardrail must apply in its
-        instructions. Providers come in two families with two configuration formats:
+        and `resources` are accepted on save but never used at run time, so put the policy the
+        guardrail must apply in its instructions. Providers come in two families with two
+        configuration formats:
 
         - **Built-in providers** — each has its own configuration block.
           - **openai**: OpenAI models (GPT-4.1, GPT-5, etc.). Configure via the `openai` object.
@@ -10864,7 +10886,7 @@ components:
           type: array
           description: |-
             MCP prompt entries saved with a catalog-provider guardrail (generic flat format).
-            Each entry references one MCP connection and the prompt names allowed from it.
+            Each entry references one MCP connection and prompt names; a guardrail's run never fetches them.
           items:
             type: object
             properties:
@@ -10885,7 +10907,7 @@ components:
                     description: Connection to the MCP server that exposes the prompts.
                   allowedPrompts:
                     type: array
-                    description: Prompt names the model may fetch from the server.
+                    description: Prompt names saved with the entry; a guardrail's run never fetches them.
                     items:
                       type: string
           x-celigo-ai-guidance:
@@ -11142,7 +11164,7 @@ components:
               type: array
               description: |-
                 MCP prompt entries saved with the guardrail. Each item references one
-                MCP connection and the prompt names allowed from it.
+                MCP connection and prompt names; a guardrail's run never fetches them.
               items:
                 type: object
                 properties:
@@ -11164,7 +11186,7 @@ components:
                         description: Connection to the MCP server.
                       allowedPrompts:
                         type: array
-                        description: Prompt names to allow from the MCP server.
+                        description: Prompt names saved with the entry; a guardrail's run never fetches them.
                         items:
                           type: string
             resources:
@@ -11331,7 +11353,7 @@ components:
                       type: array
                       description: |-
                         MCP prompt entries saved with a Gemini guardrail. Each item references one
-                        MCP connection and the prompt names allowed from it.
+                        MCP connection and prompt names; a guardrail's run never fetches them.
                       items:
                         type: object
                         properties:
@@ -11353,7 +11375,7 @@ components:
                                 description: Connection to the MCP server.
                               allowedPrompts:
                                 type: array
-                                description: Prompt names to allow from the MCP server.
+                                description: Prompt names saved with the entry; a guardrail's run never fetches them.
                                 items:
                                   type: string
                     resources:
@@ -11553,7 +11575,7 @@ components:
                       type: array
                       description: |-
                         MCP prompt entries saved with a Claude guardrail. Each item references one
-                        MCP connection and the prompt names allowed from it.
+                        MCP connection and prompt names; a guardrail's run never fetches them.
                       items:
                         type: object
                         properties:
@@ -11575,7 +11597,7 @@ components:
                                 description: Connection to the MCP server.
                               allowedPrompts:
                                 type: array
-                                description: Prompt names to allow from the MCP server.
+                                description: Prompt names saved with the entry; a guardrail's run never fetches them.
                                 items:
                                   type: string
                     resources:
@@ -11677,8 +11699,8 @@ components:
           `aiAgent.openai.tools`, `aiAgent.litellm._overrides.gemini.tools`, `….anthropic.tools`) —
           any non-empty array fails the save with 422 `guardrail_tools_not_allowed` ("Tools aren't
           supported on a guardrail AI agent configuration…"), on create and on update. `prompts` and
-          `resources` are accepted on save, but an unreachable MCP server doesn't fail the run
-          (verified on OpenAI), so put the policy in the instructions. The server still echoes
+          `resources` are accepted on save but never used at run time, so put the policy in the
+          instructions. The server still echoes
           `openai.tools: []` on OpenAI guardrails.
       properties:
         type:
@@ -17547,9 +17569,12 @@ components:
           type: array
           description: |-
             Errors recorded for the record. `source: application` with
-            `stage: apiCall` means the request reached the destination and its
-            answer was the failure; the destination's response body rides in
-            `message`.
+            `stage: apiCall` marks the import's call to the destination. Usually
+            the destination's answer was the failure, and its response body rides
+            in `message`; but a request the import couldn't build carries the same
+            pair and was never sent, such as a URL template that failed to render
+            (`code: handlebars_template_parse_error`, "Failed to generate request
+            url from template ...").
           items:
             type: object
             properties:

package/dist/networkpolicy.yml

@@ -24,6 +24,10 @@ tags:
     description: |-
       Network policies are named IP allow and deny lists that control where API tokens, MCP servers, and users may connect from. A policy takes effect only once it is assigned — through `_networkPolicyId` on an API token or MCP server, or in account settings for workspace-user and end-user sign-in — and each environment (production or sandbox) keeps its own library of policies. Network policies must be enabled for the account, and only the account owner and administrators can manage them.
 
+      Every policy that applies to a call must admit the caller. An API token's policy is checked when the token authenticates, before the request runs; an MCP server's policy is checked on every request to it, so a call to an MCP server passes both its token's policy and the server's. A personal access token has no policy of its own: it is checked against the workspace-user sign-in policy of the environment it belongs to. Sign-in policies are checked when a workspace user signs in or switches account or environment, and when an end user signs in to an MCP server.
+
+      A refused call gets HTTP 403 with `{"errors": [{"code": "access_denied", "message": "Access denied."}]}` and nothing that names the policy or the address. An MCP server endpoint speaks JSON-RPC, so its 403 carries the MCP server's access-denied error (`-32006`) in a JSON-RPC envelope instead — `{"jsonrpc": "2.0", "error": {"code": -32006, "message": "Access denied."}, "id": <request id>}`, with `id` echoed when the request had one — and the server's request log records the call as blocked.
+
       ## Network policy schema
 
       {% openapi-schemas spec="networkpolicy" schemas="NetworkPolicy" grouped="true" %}