@celigo/api-specs 0.2.18 → 0.2.20

package/dist/ai-agent.yml

@@ -21,10 +21,11 @@ tags:
       generate data within integration flows. They are stored as import resources
       with `adaptorType: AiAgentImport` and managed via the `/v1/imports` endpoints.
 
-      Three providers are supported — OpenAI (via the Responses API), Google Gemini
-      (via LiteLLM), and Anthropic Claude (via LiteLLM). A `_connectionId` is optional:
-      omit it to use platform-managed credentials, or supply one for BYOK (bring your
-      own key).
+      Three built-in providers — OpenAI (via the Responses API), Google Gemini (via
+      LiteLLM), and Anthropic Claude (via LiteLLM) — run on platform-managed
+      credentials or, with a `_connectionId`, on your own key (BYOK). Catalog
+      providers — Mistral, xAI, Hugging Face, DeepSeek, Cohere, and Groq — use one generic
+      flat configuration format and always run on a BYOK connection.
 
       ## AI agent schema
 
@@ -110,10 +111,14 @@ paths:
       x-internal: false
       summary: Create an AI agent
       description: |-
-        Creates a new AI agent import. Omit `_connectionId` to use
-        platform-managed credentials; include it for BYOK. Configure the
-        provider-specific block (`aiAgent.openai` or `aiAgent.litellm`) — the
-        other block is ignored.
+        Creates a new AI agent import. The provider decides the configuration
+        format: `aiAgent.openai` for OpenAI, `aiAgent.litellm` for Gemini and
+        Anthropic Claude, or the generic flat format (`aiAgent.model`,
+        `aiAgent.modelOptions`, …) for the catalog providers Mistral, xAI,
+        Hugging Face, DeepSeek, Cohere, and Groq — a block that does not match the
+        provider is rejected. For a built-in provider, omit `_connectionId` to
+        use platform-managed credentials or include it for BYOK; a catalog
+        provider saves without one but needs a BYOK connection to run.
       operationId: createAiAgent
       tags:
         - AI Agents
@@ -150,6 +155,24 @@ paths:
                           tools:
                             - type: googleSearch
                               googleSearch: {}
+              xai-catalog-byok:
+                summary: Catalog provider (xAI) on a BYOK connection — generic flat format
+                value:
+                  name: Invoice Extractor
+                  adaptorType: AiAgentImport
+                  _connectionId: 662aaa6576bf4040548dbbe4
+                  aiAgent:
+                    provider: xai
+                    model: grok-4.6
+                    modelOptions:
+                      maxOutputTokens: 5000
+                      reasoning_effort: high
+                      temperature: 1
+                      topP: 1
+                    instructions: Extract the invoice fields from each record.
+                    output:
+                      format:
+                        type: text
       responses:
         '201':
           description: Created AI agent.
@@ -368,7 +391,9 @@ paths:
 
         Each entry in `imports` must include `adaptorType: "AiAgentImport"` and
         a valid `aiAgent` configuration. A `_connectionId` is required unless the
-        agent uses platform-managed credentials. The response array is positional
+        agent is on a built-in provider (`openai`, `gemini`, `anthropic`) using
+        platform-managed credentials — catalog providers always need one, since
+        the preview runs the model. The response array is positional
         — `response[i]` corresponds to `imports[i]`. A per-entry
         `statusCode: 422` with `errors` means that specific configuration failed,
         not that the overall request failed.
@@ -620,14 +645,22 @@ components:
         AI Agent configuration used by both AiAgentImport and GuardrailImport (ai_agent type).
 
         Configures which AI provider and model to use, along with instructions, parameter
-        tuning, output format, and available tools. Three providers are supported:
-
-        - **openai**: OpenAI models (GPT-4, GPT-4o, GPT-4o-mini, GPT-5, etc.). Configure via the `openai` object.
-        - **gemini**: Google Gemini models via the LiteLLM proxy. Configure via `litellm` with overrides in `litellm._overrides.gemini`.
-        - **anthropic**: Anthropic Claude models via the LiteLLM proxy. Configure via `litellm` with overrides in `litellm._overrides.anthropic`.
-
-        A `_connectionId` is optional (BYOK). If not provided on the parent import,
-        platform-managed credentials are used.
+        tuning, output format, and available tools. 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.
+          - **gemini**: Google Gemini models via the LiteLLM proxy. Configure via `litellm` with overrides in `litellm._overrides.gemini`.
+          - **anthropic**: Anthropic Claude models via the LiteLLM proxy. Configure via `litellm` with overrides in `litellm._overrides.anthropic`.
+        - **Catalog providers** — `mistral`, `xai`, `huggingface`, `deepseek`, `cohere`, `groq`. Added
+          as catalog data rather than platform code, they share one generic flat format:
+          `model`, `modelOptions`, `instructions`, `output`, and the `tools` / `prompts` /
+          `resources` arrays directly on this object.
+
+        A `_connectionId` on the parent import selects bring-your-own-key (BYOK)
+        credentials. Without one, built-in providers run on platform-managed
+        credentials; catalog providers have no platform-managed credentials, so they
+        save without a connection but cannot run until one is attached.
       required:
         - provider
       properties:
@@ -637,18 +670,224 @@ components:
             - openai
             - gemini
             - anthropic
+            - mistral
+            - xai
+            - huggingface
+            - deepseek
+            - cohere
+            - groq
           x-enumDescriptions:
-            openai: Use OpenAI models via the OpenAI Responses API.
-            gemini: Use Google Gemini models via the LiteLLM proxy.
-            anthropic: Use Anthropic Claude models via the LiteLLM proxy.
+            openai: Use OpenAI models via the OpenAI Responses API (built-in; `openai` block).
+            gemini: Use Google Gemini models via the LiteLLM proxy (built-in; `litellm` block).
+            anthropic: Use Anthropic Claude models via the LiteLLM proxy (built-in; `litellm` block).
+            mistral: Use Mistral models (catalog provider; generic flat format, BYOK).
+            xai: Use xAI Grok models (catalog provider; generic flat format, BYOK).
+            huggingface: Use Hugging Face inference endpoint models (catalog provider; generic flat format, BYOK).
+            deepseek: Use DeepSeek models (catalog provider; generic flat format, BYOK).
+            cohere: Use Cohere models (catalog provider; generic flat format, BYOK).
+            groq: Use Groq-hosted models (catalog provider; generic flat format, BYOK).
           description: AI provider to use.
           x-celigo-ai-guidance:
             - |-
-              - **openai**: Uses OpenAI Responses API. Configure via the `openai` object.
-              - **gemini**: Uses Google Gemini via LiteLLM. Configure via `litellm` with
-                Gemini-specific overrides in `litellm._overrides.gemini`.
-              - **anthropic**: Uses Anthropic Claude via LiteLLM. Configure via `litellm` with
-                Claude-specific overrides in `litellm._overrides.anthropic`.
+              The provider decides the configuration format, and the server rejects a
+              mismatch with 422 `invalid_provider_config_format`: `openai` needs the
+              `openai` block, `gemini` and `anthropic` need the `litellm` block (Gemini- or
+              Claude-specific settings under `litellm._overrides`), and the catalog
+              providers (`mistral`, `xai`, `huggingface`, `deepseek`, `cohere`, `groq`) need the
+              generic flat format — `model` and `modelOptions` directly on this object,
+              never an `openai` or `litellm` block.
+            - |-
+              Catalog providers are BYOK-only at run time: the agent saves without a
+              `_connectionId`, but its first run fails with 422 `invalid_request` ("No API
+              key configured for provider …"). Always attach an HTTP connection to the
+              vendor's API (token auth) when the provider is a catalog provider.
+        model:
+          type: string
+          description: |-
+            Model identifier for a catalog provider (generic flat format) — for example
+            `grok-4.6`. Built-in providers set the model inside their own block
+            (`openai.model`, `litellm.model`) instead.
+          x-celigo-ai-guidance:
+            - |-
+              Required for every catalog provider — omitting it or sending an empty string
+              fails the save with 422 `missing_required_field`.
+            - |-
+              Without a `_connectionId` on the parent import the model must be one the
+              catalog lists for the provider: an unknown id fails the save with 422
+              `model_not_found`, a listed-but-disabled id with 422 `model_disabled`. With a
+              `_connectionId` (BYOK) any model string saves — the server does not check it
+              against the catalog or the vendor.
+        modelOptions:
+          type: object
+          description: |-
+            Model tuning for a catalog provider (generic flat format). Which keys, values, and
+            ranges are accepted is defined per catalog model and validated on save when the
+            model is a catalog entry.
+          properties:
+            maxOutputTokens:
+              type: number
+              description: Maximum number of tokens the model may generate.
+            temperature:
+              type: number
+              description: Sampling temperature.
+            topP:
+              type: number
+              description: Nucleus sampling threshold.
+            reasoning_effort:
+              type: string
+              enum:
+                - low
+                - medium
+                - high
+                - xhigh
+              x-enumDescriptions:
+                low: Minimal reasoning before answering.
+                medium: Moderate reasoning.
+                high: Extensive reasoning.
+                xhigh: Maximum reasoning.
+              description: Reasoning depth for models that expose it.
+          x-celigo-ai-guidance:
+            - |-
+              When the model is a catalog entry, the server validates this object against
+              that model's schema and fails the save with 422 `invalid_model_options`
+              naming the key: unknown keys are rejected, `reasoning_effort` must be one of
+              the enum values where the model accepts it at all (xAI's `grok-4.6` does;
+              DeepSeek's `deepseek-chat` rejects the key), and numeric bounds apply —
+              on `grok-4.6`, `temperature` ≤ 2, `topP` ≤ 1, `maxOutputTokens` ≥ 100.
+            - |-
+              With a `_connectionId` and a model the catalog does not list, the object is
+              passed through unvalidated — send only options the vendor's API accepts.
+        instructions:
+          type: string
+          description: |-
+            System prompt for a catalog provider (generic flat format). Built-in providers
+            set it inside their own block (`openai.instructions`,
+            `litellm._overrides.anthropic.systemInstruction`).
+        output:
+          type: object
+          description: |-
+            Output format for a catalog provider (generic flat format). Built-in providers
+            configure it inside their own block (`openai.output`, `litellm.responseFormat`).
+          properties:
+            format:
+              type: object
+              description: Controls the structure of the model's output.
+              properties:
+                type:
+                  type: string
+                  enum:
+                    - text
+                    - json_schema
+                  x-enumDescriptions:
+                    text: Free-form text.
+                    json_schema: Structured JSON conforming to `jsonSchema`.
+                  description: Output type.
+                  x-celigo-ai-guidance:
+                    - |-
+                      `blob` is not accepted here — the save fails with 422
+                      `unsupported_output_format` naming the model (verified on `grok-4.6`).
+                name:
+                  type: string
+                  description: Name of the JSON schema, for `json_schema` output.
+                strict:
+                  type: boolean
+                  description: When true, the model must conform exactly to `jsonSchema`.
+                jsonSchema:
+                  type: object
+                  additionalProperties: true
+                  description: JSON Schema the structured output must conform to, for `json_schema` output.
+            verbose:
+              type: string
+              description: Level of detail in the model's response, for models that expose it.
+        tools:
+          type: array
+          description: |-
+            Tools available to a catalog-provider agent (generic flat format). Entries mirror
+            the built-in providers' tool entries: a Celigo Tool by `_toolId`, an MCP server by
+            `_mcpConnectionId`, or a vendor web-search tool.
+          items:
+            type: object
+            properties:
+              type:
+                type: string
+                enum:
+                  - tool
+                  - mcp
+                  - web_search
+                x-enumDescriptions:
+                  tool: Reference a reusable Celigo Tool resource.
+                  mcp: Connect to an MCP server for additional external tools.
+                  web_search: Search the web for real-time information, where the vendor's model supports it.
+                description: Type of tool entry.
+              tool:
+                type: object
+                description: Reference to a Celigo Tool resource, used when type is "tool".
+                properties:
+                  _toolId:
+                    type: string
+                    format: objectId
+                    x-celigo-refModel: tools
+                    description: The Celigo Tool to call.
+              mcp:
+                type: object
+                description: MCP server connection, used when type is "mcp".
+                properties:
+                  _mcpConnectionId:
+                    type: string
+                    format: objectId
+                    x-celigo-refModel: connections
+                    description: Connection to the MCP server.
+                  allowedTools:
+                    type: array
+                    description: |-
+                      Specific tools to allow from the MCP server (all if omitted). Each entry
+                      is either a plain tool name or an object carrying display metadata.
+                    items:
+                      type:
+                        - string
+                        - object
+              config:
+                type: object
+                additionalProperties: true
+                description: Tool-specific options for vendor-native tools (for example web-search settings).
+          x-celigo-ai-guidance:
+            - |-
+              References are checked on save: an unknown `_toolId` or `_mcpConnectionId`
+              fails with 422 `invalid_ref` naming the array index.
+        prompts:
+          type: array
+          description: |-
+            MCP prompt entries available to a catalog-provider agent (generic flat format).
+            Each entry references one MCP connection and the prompt names allowed from it.
+          items:
+            type: object
+            properties:
+              type:
+                type: string
+                enum:
+                  - mcp
+                x-enumDescriptions:
+                  mcp: Reference prompts exposed by an MCP server.
+                description: Type of prompt entry. Always "mcp".
+              mcp:
+                type: object
+                properties:
+                  _mcpConnectionId:
+                    type: string
+                    format: objectId
+                    x-celigo-refModel: connections
+                    description: Connection to the MCP server that exposes the prompts.
+                  allowedPrompts:
+                    type: array
+                    description: Prompt names the agent may fetch from the server.
+                    items:
+                      type: string
+          x-celigo-ai-guidance:
+            - |-
+              An unknown `_mcpConnectionId` fails the save with 422 `invalid_ref` naming
+              the array index.
+        resources:
+          $ref: '#/components/schemas/McpResources'
         openai:
           type: object
           description: |
@@ -679,10 +918,11 @@ components:
               x-celigo-ai-guidance:
                 - |-
                   With platform-managed credentials (no `_connectionId` on the parent
-                  import), the model must be on the platform's allowlist — an
-                  unlisted model fails the save with 422. A BYOK connection bypasses
-                  the allowlist and the model string is passed through to the
-                  provider as-is.
+                  import), the model must be one the platform hosts. The save does not
+                  check this — an unlisted model saves, and the agent's first run fails
+                  with 422 `invalid_model`, whose message lists the hosted models. A
+                  BYOK connection bypasses the hosted list and the model string is
+                  passed through to the provider as-is.
             reasoning:
               type: object
               description: Controls depth of reasoning for complex tasks.
@@ -1085,6 +1325,13 @@ components:
                 - claude-sonnet-4-6
                 - claude-opus-4-7
               x-celigo-ui-override: Required by the AI agent configuration form. Encoded here to mirror the form so builders produce connectable configurations.
+              x-celigo-ai-guidance:
+                - |-
+                  With platform-managed credentials (no `_connectionId` on the parent
+                  import), the model must be one the platform hosts for the provider —
+                  Gemini and Anthropic Claude both have a hosted list. The save does not
+                  check this — an unlisted model saves, and the agent's first run fails
+                  with 422 `invalid_model`, whose message lists the hosted models.
             temperature:
               type: number
               minimum: 0
@@ -1739,6 +1986,22 @@ components:
             litellm:
               required:
                 - model
+        else:
+          if:
+            properties:
+              provider:
+                enum:
+                  - mistral
+                  - xai
+                  - huggingface
+                  - deepseek
+                  - cohere
+                  - groq
+            required:
+              - provider
+          then:
+            required:
+              - model
     items:
       type: object
       properties:
@@ -4749,9 +5012,11 @@ components:
       type: object
       description: |-
         Writable AI agent import fields shared by the request and response schemas. Set
-        `aiAgent.provider` to choose the LLM backend, then configure the matching block:
-        `aiAgent.openai` for OpenAI, or `aiAgent.litellm` for Gemini and Anthropic Claude
-        (with provider-specific settings under `aiAgent.litellm._overrides`).
+        `aiAgent.provider` to choose the LLM backend, then configure the matching format:
+        `aiAgent.openai` for OpenAI, `aiAgent.litellm` for Gemini and Anthropic Claude
+        (with provider-specific settings under `aiAgent.litellm._overrides`), or the
+        generic flat format (`aiAgent.model`, `aiAgent.modelOptions`, …) for the catalog
+        providers Mistral, xAI, Hugging Face, DeepSeek, Cohere, and Groq.
       properties:
         name:
           type: string
@@ -4770,7 +5035,12 @@ components:
           type: string
           format: objectId
           x-celigo-refModel: connections
-          description: Connection for BYOK (bring your own key). Optional — platform-managed credentials are used when omitted.
+          description: |-
+            Connection for BYOK (bring your own key) — an HTTP connection to the vendor's API.
+            Optional for the built-in providers (`openai`, `gemini`, `anthropic`), which run on
+            platform-managed credentials when it is omitted. Catalog providers (`mistral`, `xai`,
+            `huggingface`, `deepseek`, `cohere`, `groq`) have no platform-managed credentials: the agent
+            saves without one but cannot run until it is set.
           examples:
             - 662aaa6576bf4040548dbbe4
         _integrationId:
@@ -5125,9 +5395,11 @@ components:
       type: object
       description: |-
         Configuration for an AI agent import. Set `aiAgent.provider` to choose
-        the LLM backend, then configure the matching block: `aiAgent.openai` for
-        OpenAI, or `aiAgent.litellm` for Gemini and Anthropic Claude. Omit
-        `_connectionId` to use platform-managed credentials.
+        the LLM backend, then configure the matching format: `aiAgent.openai` for
+        OpenAI, `aiAgent.litellm` for Gemini and Anthropic Claude, or the generic
+        flat format (`aiAgent.model`, `aiAgent.modelOptions`, …) for the catalog
+        providers. Omit `_connectionId` to use platform-managed credentials on a
+        built-in provider; catalog providers need a BYOK connection to run.
       required:
         - name
         - adaptorType

package/dist/connection.yml

@@ -801,17 +801,33 @@ paths:
       x-internal: false
       summary: Patch a connection
       description: |-
-        Partially updates a connection using a JSON Patch document (RFC 6902).
-        Only the `replace` operation is supported, and only on the following
-        whitelisted paths:
+        Partially updates a connection using a JSON Patch document (RFC 6902)
+        without re-sending its credentials — stored credentials are never read,
+        required, or changed by this operation. Use it for the settings below;
+        everything else goes through `PUT`, which replaces the whole document.
+        Only these paths are accepted (`<adaptor>` is the connection's `type`,
+        e.g. `/http/concurrencyLevel`, `/netsuite/targetConcurrencyLevel`):
 
         | Path | Description |
         |------|-------------|
         | `/name` | Connection display name |
         | `/debugDate` | Debug logging expiry (ISO-8601, max 1 hour from now) |
         | `/debugUntil` | Alias for `/debugDate` |
+        | `/<adaptor>/concurrencyLevel` | Concurrent requests allowed. Platform-managed while `autoRecoverRateLimitErrors` is true — the recovery machinery moves it toward the target, so set `targetConcurrencyLevel` instead |
+        | `/<adaptor>/targetConcurrencyLevel` | Ceiling auto-recovery climbs back to. Persists only while `autoRecoverRateLimitErrors` is true; while false the save unsets it |
+        | `/_borrowConcurrencyFromConnectionId` | Share another connection's concurrency budget. `remove` clears it |
+        | `/autoRecoverRateLimitErrors` | Rate-limit auto-recovery toggle. Turning it on copies the current level into the target; turning it off unsets the target and leaves the level at its current value |
 
-        All other paths are rejected with `422`.
+        `replace` and `add` both set the value (a currently unset field is fine);
+        `remove` unsets it. A `null` value is rejected. Any other path — including
+        `/netsuite/concurrencyLevelRESTlet`, `/netsuite/concurrencyLevelWebServices`
+        and `rateLimit` fields — fails with `<path> is not a whitelisted property`.
+        Concurrency values must be whole numbers; out-of-range integers are clamped
+        into the account's licensed range rather than rejected. A whitelisted path
+        under an adaptor block the connection does not use is accepted but never
+        read. The borrowed-from connection must exist in the account, may not itself
+        borrow, and a connection that others borrow from cannot start borrowing.
+        Settings-only changes are recorded in the connection's audit log.
       operationId: patchConnection
       tags:
         - Connections
@@ -841,6 +857,32 @@ paths:
                   - op: replace
                     path: /name
                     value: Shopify US Production
+              set_target_concurrency:
+                summary: Raise the target concurrency of an HTTP connection (auto-recovery on)
+                value:
+                  - op: replace
+                    path: /http/targetConcurrencyLevel
+                    value: 10
+              disable_auto_recovery_and_set_level:
+                summary: Turn off rate-limit auto-recovery and fix the concurrency level
+                value:
+                  - op: replace
+                    path: /autoRecoverRateLimitErrors
+                    value: false
+                  - op: replace
+                    path: /http/concurrencyLevel
+                    value: 4
+              borrow_concurrency:
+                summary: Share another connection's concurrency budget
+                value:
+                  - op: replace
+                    path: /_borrowConcurrencyFromConnectionId
+                    value: 615dfa0742763671275b70ab
+              stop_borrowing:
+                summary: Stop borrowing concurrency
+                value:
+                  - op: remove
+                    path: /_borrowConcurrencyFromConnectionId
       responses:
         '204':
           description: Connection patched successfully
@@ -2645,11 +2687,13 @@ components:
                 When true, rate-limit errors from the target system trigger automatic recovery: concurrency
                 drops to 1, the rate-limited requests are retried with doubling waits (1 to 1024 minutes,
                 after which the flag switches itself off), and concurrency climbs back toward
-                `targetConcurrencyLevel`. While true, `concurrencyLevel` is platform-managed and writes to
-                it are ignored — `targetConcurrencyLevel` is the lever.
+                `targetConcurrencyLevel`. While true, `targetConcurrencyLevel` is the throughput lever: a
+                `concurrencyLevel` sent in a PUT is ignored, and one sent in a PATCH is stored but the
+                recovery machinery moves it back toward the target.
               x-celigo-ai-guidance:
-                - To change throughput while this is true, write `targetConcurrencyLevel`; a `concurrencyLevel` write returns 200 and changes nothing.
-                - Turning it on copies `concurrencyLevel` into `targetConcurrencyLevel`; turning it off copies the target back into `concurrencyLevel` and unsets the target.
+                - To change throughput while this is true, write `targetConcurrencyLevel`; a `concurrencyLevel` sent in a PUT returns 200 and changes nothing.
+                - Turning it on copies `concurrencyLevel` into `targetConcurrencyLevel`; turning it off unsets the target and leaves `concurrencyLevel` at its current value, which may be below the old target if a recovery was in progress. A `targetConcurrencyLevel` written while this is false is unset by the save.
+                - These four settings (`concurrencyLevel`, `targetConcurrencyLevel`, `_borrowConcurrencyFromConnectionId`, this flag) accept a credential-free `PATCH /v1/connections/{_id}`. A PUT must re-send the credentials — omitting them or echoing their masked `******` values clears them.
             enableMicroBatchForOneToMany:
               type: boolean
               default: true
@@ -3926,7 +3970,7 @@ components:
             Higher values increase throughput but may trigger API rate limits.
             Set this based on the target API's rate limit documentation.
             Values above the account's licensed maximum (25 standard, 50 with an Environments license) are silently clamped down.
-            Platform-managed while `autoRecoverRateLimitErrors` is true — writes are ignored; set `targetConcurrencyLevel` instead.
+            Platform-managed while `autoRecoverRateLimitErrors` is true — a PUT ignores the value and the recovery machinery moves it toward the target; set `targetConcurrencyLevel` instead.
           minimum: 1
           maximum: 50
           default: 25
@@ -7516,9 +7560,20 @@ components:
           x-celigo-refModel: connections
           description: |-
             Reference to another connection to share concurrency limits with. When set, this
-            connection's traffic counts against the referenced connection's limit instead of its own.
+            connection's traffic counts against the referenced connection's limit instead of its own,
+            and its own concurrency and auto-recovery settings have no effect. One level only: the
+            referenced connection may not itself borrow, and a connection that others borrow from
+            cannot start borrowing.
           examples:
             - 615dfa0742763671275b70ab
+        autoRecoverRateLimitErrors:
+          type: boolean
+          default: true
+          description: |-
+            When true, rate-limit errors from the target system trigger automatic recovery — concurrency
+            drops to 1 and climbs back toward the adaptor block's `targetConcurrencyLevel`, which is the
+            throughput lever while this is on. Turning it on copies the current `concurrencyLevel` into
+            the target; turning it off unsets the target and leaves `concurrencyLevel` at its current value.
         __integrationIds:
           type: array
           maxItems: 100

package/dist/flow.yml

@@ -6716,15 +6716,29 @@ components:
             triggeredBy:
               type: string
               readOnly: true
-              description: Who/what triggered the job (free-form string).
+              description: |-
+                What started the run. On a `flow` job: `system` for a scheduled run, the `_id` of
+                the user who ran the flow, or the `_id` of the upstream flow whose `_runNextFlowIds`
+                chained into this one; absent on event-driven runs (webhook, real-time listener, and
+                stream page generators), which the inbound event starts. On a `retry` job: `auto`
+                for the platform's automatic intermittent-error retry, otherwise the `_id` of the
+                user who submitted the retry. Absent on `export` and `import` child jobs — the
+                parent flow job carries it.
               examples:
-                - scheduler
+                - system
             canceledBy:
               type: string
               readOnly: true
-              description: Who/what requested cancellation (free-form string).
+              description: |-
+                Who canceled the run: the `_id` of the user who requested the cancel, or `system` for
+                every platform-initiated cancel — stuck-run recovery after a worker exit or crash or
+                when a run stops making progress, stale-run cleanup, a scheduler that could not
+                re-queue the run, and the cancels that follow deleting the flow or replacing one of
+                its connections. The record does not say which of these it was.
+              x-celigo-ai-guidance:
+                - A `system` cancel is not something the user did and not a verdict on the flow's configuration, and by itself it does not prove the run was stuck — deleting the flow or replacing one of its connections cancels in-flight runs the same way; read the run's age and progress counters for that.
               examples:
-                - user
+                - system
             flowExecutionGroupId:
               type: string
               readOnly: true