@celigo/api-specs 0.2.114 → 0.2.116

package/dist/ai-agent.yml

@@ -566,6 +566,182 @@ paths:
                   value: {}
         '401':
           $ref: '#/components/responses/401-unauthorized'
+  /v1/imports/{_id}/aiagents/chat:
+    post:
+      x-internal: false
+      operationId: chatWithAiAgent
+      tags:
+        - AI Agents
+      summary: Chat with a saved AI agent
+      description: |-
+        Sends one message to a saved AI agent and streams the answer as
+        `text/event-stream`. Events arrive in order: `init`, `thinking`
+        (started), a `progress` pair per tool call (`tool <name> started` /
+        `finished`), `thinking` (completed) — a Celigo Tool's inner-step
+        `progress` events can still arrive after it — `responsechunk` deltas
+        of the reply (raw text — join them), `usage` (tokens and AI-credit cost),
+        `complete` (`data.success`); an `error` event replaces the reply when
+        the turn fails (see `ChatStreamEvent`). The agent runs as configured:
+        its tools (web search, MCP servers, Celigo Tools) execute for real and
+        the turn is billed — AI credits on a hosted model, the key's owner on
+        a BYOK one. The same `conversationHistoryId` across requests keeps a
+        conversation; without it the message is a single turn and nothing is
+        stored. Needs the `ai_agent:chat` permission (manage and administrator
+        roles; monitor gets 403) and `Content-Type: application/json` (415 if
+        not).
+
+        None of the flow pipeline runs — no input filter, mappings, hooks or
+        response mapping — so this is the agent in conversation, not the import
+        step; `POST /v1/imports/preview` runs the step with its pre-submit
+        stages. A tile-level manager can chat only with agents inside
+        accessible integrations. Files travel as storage keys from the UI's
+        signed-upload flow; the public API has no upload route. The stream
+        carries its own failure: a turn the agent service could not finish
+        still answers 200 with an `error` event inside it. Read the events in
+        order and stop at `complete`, or at an `error` that ends the stream.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: 'The AI agent — an import with `adaptorType: AiAgentImport`.'
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: imports
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ChatRequest'
+            examples:
+              single-turn:
+                summary: One message, no conversation
+                value:
+                  data:
+                    - text: 'Classify this ticket: the invoice total is wrong on order 4411.'
+              continued-conversation:
+                summary: A follow-up in a conversation the caller keys
+                value:
+                  data:
+                    - text: What did you decide for the previous ticket?
+                      conversationHistoryId: support-triage-session-42
+      responses:
+        '200':
+          description: |-
+            The turn as a stream of server-sent events, ending with `complete`.
+            A turn the agent service could not finish still answers 200: the
+            failure arrives inside the stream as an `error` event.
+          content:
+            text/event-stream:
+              itemSchema:
+                $ref: '#/components/schemas/ChatStreamEvent'
+              examples:
+                reply-with-a-web-search:
+                  summary: A turn that called web search, as the raw stream
+                  value: |
+                    event: init
+                    data: {"requestId": "3e71c33f-1c5e-4df5-93af-b3d503b28b23"}
+
+                    event: thinking
+                    data: {"status": "started", "requestId": "3e71c33f-1c5e-4df5-93af-b3d503b28b23"}
+
+                    event: progress
+                    data: {"content": "tool web_search started", "input": "", "output": "", "requestid": "3e71c33f-1c5e-4df5-93af-b3d503b28b23"}
+
+                    event: progress
+                    data: {"content": "tool web_search finished", "input": "", "output": "", "requestid": "3e71c33f-1c5e-4df5-93af-b3d503b28b23"}
+
+                    event: thinking
+                    data: {"status": "completed", "requestId": "3e71c33f-1c5e-4df5-93af-b3d503b28b23", "durationMs": 6571, "summary": "Called web_search"}
+
+                    event: responsechunk
+                    data: Latest stable Python 3 release: 3.15.0 — source: python.org.
+
+                    event: usage
+                    data: {"content": {"model": "gpt-5-mini", "input_tokens": 9218, "output_tokens": 737, "total_tokens": 9955, "token_only_ai_credits": 0.004345275, "tool_addon_cost": 0.01, "total_cost": 0.015845275, "web_search_details": {"billed_search_actions": 1, "tool_call_ai_credits": 0.0115}, "tool_call_buckets": [{"category": "native_tool", "total_count": 1, "tools": [{"name": "web_search", "count": 1}]}]}}
+
+                    event: complete
+                    data: {"success": true}
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '415':
+          description: '`Content-Type: application/json` header is missing.'
+  /v1/aiagents/chat:
+    post:
+      x-internal: false
+      operationId: chatWithVirtualAiAgent
+      tags:
+        - AI Agents
+      summary: Chat with an unsaved AI agent document
+      description: |-
+        Sends one message to an AI agent document carried in the request — a
+        draft never saved, or a saved agent with unsaved changes — and streams
+        the answer back as `text/event-stream` with the same events as
+        `POST /v1/imports/{_id}/aiagents/chat` (see `ChatStreamEvent`). The
+        document is validated in memory the way a save validates it and is
+        never persisted: the saved agent, if there is one, is untouched, so
+        this is how a change is tried before it is saved. The agent's tools
+        execute for real and the turn is billed; none of the flow pipeline
+        runs. `conversationHistoryId` keeps a conversation keyed on the
+        document's `_id` when one is present, so a draft of a saved agent can
+        continue that agent's history. Needs the `ai_agent:virtual_chat`
+        permission (manage and administrator roles; monitor gets 403) and
+        `Content-Type: application/json` (415 otherwise).
+
+        The integrator.io agent editor uses this route for a Test or chat
+        message while the form has unsaved edits. A tile-level manager can use
+        it only when every connection, MCP connection and Celigo Tool the
+        document references is inside accessible integrations. A turn the
+        agent service could not finish still answers 200 with an `error` event
+        inside the stream.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/VirtualChatRequest'
+            examples:
+              try-changed-instructions:
+                summary: Run a saved agent's document with edited instructions, without saving
+                value:
+                  data:
+                    - text: 'Classify this ticket: the invoice total is wrong on order 4411.'
+                  import:
+                    _id: 6ad1005b1c1632e833de1227
+                    name: Ticket triage
+                    adaptorType: AiAgentImport
+                    aiAgent:
+                      provider: openai
+                      openai:
+                        model: gpt-5-mini
+                        instructions: Classify the ticket and always ask for the order number when it is missing.
+      responses:
+        '200':
+          description: |-
+            The turn as a stream of server-sent events, ending with `complete`.
+            A turn the agent service could not finish still answers 200: the
+            failure arrives inside the stream as an `error` event.
+          content:
+            text/event-stream:
+              itemSchema:
+                $ref: '#/components/schemas/ChatStreamEvent'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '415':
+          description: '`Content-Type: application/json` header is missing.'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
 components:
   securitySchemes:
     bearerAuth:
@@ -6214,6 +6390,173 @@ components:
             dependencyIds:
               export:
                 - 64ff4b21612a134bd2f45534
+    ChatMessage:
+      type: object
+      description: |-
+        One message for the agent. Give it `text`, `files`, or both; the agent
+        answers in the streamed response.
+      properties:
+        text:
+          type: string
+          description: |-
+            The message the agent answers. Whitespace-only text counts as empty,
+            so a message with no `files` must carry visible text.
+          examples:
+            - 'Classify this ticket: the invoice total is wrong on order 4411.'
+        files:
+          type: array
+          description: |-
+            Files the agent reads with the message (images, PDFs, JSON documents).
+            Each entry names an object already uploaded to the account's file
+            storage through the signed-upload flow the integrator.io UI uses; the
+            public API has no upload route of its own.
+          items:
+            type: object
+            required:
+              - name
+              - blobKey
+            properties:
+              name:
+                type: string
+                description: File name shown to the agent.
+                examples:
+                  - invoice-4411.pdf
+              blobKey:
+                type: string
+                description: Storage key of the uploaded file, as returned by the signed-upload flow.
+        conversationHistoryId:
+          type: string
+          maxLength: 200
+          description: |-
+            Caller-chosen key for a conversation with this agent. Turns sent
+            with the same key share a history: the agent sees the earlier
+            requests and replies and the history is updated after each turn.
+            The key is scoped to the calling user and the agent, so the same
+            string against a different agent is a different conversation. Omit
+            it for a single-turn message — nothing is stored.
+          examples:
+            - support-triage-session-42
+      x-celigo-ai-guidance:
+        - |-
+          A history keyed by a caller-chosen `conversationHistoryId` is runtime memory for the
+          agent; it does not appear in the agent's Conversation history in the integrator.io
+          UI, which lists only conversations started from the UI.
+    ChatRequest:
+      type: object
+      description: |-
+        Body of a chat turn with a saved AI agent: `data` holds the one message
+        — its `text`, its `files` (name and storage `blobKey` of uploaded
+        files), and an optional `conversationHistoryId` that keeps a
+        conversation across requests.
+      x-celigo-ai-guidance:
+        - |-
+          Rejections before the agent runs use the standard error envelope: 400 `invalid_request`
+          ("Request body can't be empty.") for an empty body; 400 `missing_required_field` ("data
+          (must be an array with exactly one element) is required.") when `data` is not a
+          one-element array, and ("data[0].text or data[0].files is required.") when the one
+          message has neither `files` nor a non-blank `text`; 404 `invalid_ref` ("Import not
+          found.") when no import with the `_id` is in the account.
+      required:
+        - data
+      properties:
+        data:
+          type: array
+          minItems: 1
+          maxItems: 1
+          description: |-
+            Exactly one message per request. A request with more than one entry
+            is rejected before the agent runs.
+          items:
+            $ref: '#/components/schemas/ChatMessage'
+    ChatStreamEvent:
+      type: object
+      description: |-
+        One server-sent event of a chat turn. The stream is `text/event-stream`:
+        each event is an `event:` line naming the event and one or more `data:`
+        lines carrying its payload, separated by a blank line. `data` is JSON for
+        every event except `responsechunk`, whose `data:` lines are raw text (one
+        line per line of the delta). A successful turn is `init`, `thinking`
+        (started), any number of `progress` events, `thinking` (completed), the
+        `responsechunk` deltas, `usage`, `complete`; a Celigo Tool's inner-step
+        `progress` events can still arrive after `thinking` (completed).
+      required:
+        - event
+      properties:
+        event:
+          type: string
+          enum:
+            - init
+            - thinking
+            - progress
+            - responsechunk
+            - bloboutput
+            - usage
+            - complete
+            - error
+          x-enumDescriptions:
+            init: First event; `data.requestId` identifies the turn
+            thinking: '`data.status` is `started` when the agent begins and `completed` with `durationMs` (and a `summary` such as `Called web_search`) when it is done reasoning'
+            progress: 'A tool the agent is using — `data.content` reads `tool <name> started` or `tool <name> finished` (a Celigo Tool is named `celigo_tool_<_toolId>`), with `input` and `output` when the tool reports them; a Celigo Tool''s inner steps arrive as `data.content` `<step name>: <step type>` with `data.input` `step_start`, `step_complete` or `step_failed`, `data.output` the step''s stats as text, and `data.step` `{type: tool_step, event, name, tool_id, stepType, stats, attempt}`'
+            responsechunk: A delta of the agent's reply; concatenate the deltas in order for the full text
+            bloboutput: A file the agent produced — `data.content.preSignedURL` is a time-limited download link
+            usage: Token counts and cost of the turn — `data.content` is a `ChatUsage` object; sent for every turn that reached the agent, also after an `error` the agent service reported
+            complete: Last event of a turn that reached the agent — `data.success` is `true`, or `false` when an `error` event preceded it
+            error: The turn failed — see the description of this schema for the payload shapes
+          description: Name carried on the `event:` line.
+        data:
+          description: |-
+            The event payload. For `error` the payload shape says where the
+            failure happened. The agent service reports `{code, message, source?}`
+            (for example `tool_stream_error` / `Tool execution failed` with
+            `source: tools`) and the stream goes on to `usage` and `complete`
+            with `success: false`. The chat relay reports `{content: {code,
+            message}}` and ends the stream there — no `usage`, no `complete`
+            (`validation_error` for a `conversationHistoryId` over 200
+            characters). A stream that broke before reaching the relay
+            arrives as a `data:` line with no `event:` line whose JSON carries
+            `error` or `code`.
+          oneOf:
+            - type: object
+              additionalProperties: true
+            - type: string
+    VirtualChatRequest:
+      type: object
+      description: |-
+        Body of a chat turn with an AI agent document that has not been saved
+        (or has unsaved changes): `data` holds the one message — `text`,
+        `files` and an optional `conversationHistoryId`, as on the saved-agent
+        route — and `import` carries the document to run, in the shape
+        `GET /v1/imports/{_id}` returns. The document is validated in memory
+        the same way a save validates it and is never persisted.
+      x-celigo-ai-guidance:
+        - |-
+          The document is checked in this order: 400 `invalid_request` ("Import document should be
+          a JSON object.") when `import` is missing or not an object; 422 — the validation a save
+          runs — `missing_required_field` on a field the import schema requires, or `invalid_ref`
+          with `field: _connectionId` ("<id> is not a valid _connectionId") on a connection not in
+          the account; then 400 `invalid_adaptor` ("Unsupported operation: Chat route is enabled
+          only for AI Agent imports.") when `adaptorType` is not `AiAgentImport`. The `data` rules
+          match the saved-agent route.
+      required:
+        - data
+        - import
+      properties:
+        data:
+          type: array
+          minItems: 1
+          maxItems: 1
+          description: Exactly one message per request.
+          items:
+            $ref: '#/components/schemas/ChatMessage'
+        import:
+          description: |-
+            The AI agent document to run, with `adaptorType: AiAgentImport` and
+            the `aiAgent` block for the configuration under test. An `_id` is
+            optional; when present it is kept, so a `conversationHistoryId`
+            continues the same history the saved agent uses. A `_connectionId`
+            selects the BYOK connection the turn runs through.
+          allOf:
+            - $ref: '#/components/schemas/Request'
   responses:
     400-bad-request:
       description: |
@@ -6302,5 +6645,18 @@ components:
                 errors:
                   - code: dependencies_not_deleted
                     message: export 6902d88c10b42b2eaac9b2a1 must be deleted before you can delete connection 6398ddf316be761fb16a6523
+    403-forbidden:
+      description: |
+        Forbidden. The authenticated caller does not have permission to perform this operation.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: forbidden
+                    message: You do not have permission to access this resource.
 x-enable-proxy: true
 x-internal: false

package/dist/export.yml

@@ -16061,11 +16061,25 @@ components:
             Handlebars template that overrides how each record's unique trace key is generated, used
             to track records through the flow and match retries to prior errors (e.g.
             `{{join "_" record.customerId record.orderId}}`). When omitted, the system picks a unique
-            field automatically. If a transform reshapes the data first, omit the `record.` prefix.
-            Trace keys are capped at 256 characters; a longer key is stored truncated from the middle,
-            keeping the beginning and end of the value. Downstream imports use the trace key as their
-            default concurrency lock key (a blank key means no lock); it never de-duplicates — a record
-            emitted twice with the same key is processed twice.
+            field automatically from the record's top level, by exact field name (`GET
+            /v1/flows/{_id}/traceKey` serves the pattern). The rendered value of a template is stamped
+            on each record as `io_custom_trace_key` and travels downstream with it. If a transform
+            reshapes the data first, omit the `record.` prefix. Trace keys are capped at 256 characters;
+            a longer key is stored truncated from the middle, keeping the beginning and end of the
+            value. Downstream imports use the trace key as their default concurrency lock key (a blank
+            key means no lock); it never de-duplicates — a record emitted twice with the same key is
+            processed twice.
+          x-celigo-ai-guidance:
+            - |-
+              The default derivation reads these top-level fields in order and takes the first present
+              (a record carrying `id` and `internalId` is keyed on `id` alone) — `id`, `Id`, `ID`,
+              `internalid`, `Internalid`, `internalId`, `InternalId`, `INTERNALID`, `_id`, `_Id`, `_ID`,
+              `internal_id`, `internal_Id`, `Internal_id`, `Internal_Id`, `INTERNAL_ID`, `identifier`,
+              `IDENTIFIER` — then a `*anything` rule the platform does not document.
+            - |-
+              A record in flight through the flow carries `io_custom_trace_key` when a template is set
+              — that value is the downstream imports' default lock key; without a template the record
+              carries no trace-key field (the key is derived, not stored on the record).
           examples:
             - '{{record.id}}'
             - '{{join "_" record.customerId record.orderId}}'

package/dist/import.yml

@@ -15944,7 +15944,8 @@ components:
             Handlebars template that generates a concurrency lock key for each record: records that
             render the same key are never submitted at the same time, while records with different
             keys are processed in parallel. When omitted, the record's trace key is the lock key (a
-            blank trace key means no lock); a template replaces that default rather than adding to it.
+            blank trace key means no lock; a custom `traceKeyTemplate` upstream arrives on the record
+            as `io_custom_trace_key`); a template replaces that default rather than adding to it.
             The template is rendered from the record as it arrives at the import — before the import's
             own lookups and mapping run — so a key built from one of the import's lookup results
             (`{{lookup.<name>}}`) or from a mapped field renders empty, and an empty key is no lock at

package/dist/job.yml

@@ -45,10 +45,26 @@ paths:
           pass at least one of `_integrationId`, `_flowId`, `_exportId`,
           `_importId`, `_flowJobId`, `createdAt_gte`, or `createdAt_lte` to
           scope the query. Omitting all filters returns all jobs in the account.
+          Exception: for a caller with integration-only access, `_flowId` scopes
+          a `type=flow` or `type=retry` query only together with
+          `_integrationId` (below).
         - **Child jobs** (`type=export` or `type=import`) — requires
           `_flowJobId` or a resource ID filter (`_exportId` / `_importId`).
           Returns the export/import sub-jobs within a parent flow job.
 
+        Job reads are authorized per integration. For a caller with
+        integration-only access (an account share that populates
+        `integrationAccessLevel` and omits `accessLevel`), a parent-job query
+        scoped by `_flowId` alone (`type=flow` or `type=retry`) fails with `400`
+        `query_param_required` ("Please provide the integration _id for which you
+        want to fetch the jobs"); it succeeds once `_integrationId` is sent beside
+        `_flowId`. Account-level callers may scope by `_flowId` alone, but that
+        path resolves the flow document first, so the jobs of a deleted flow come
+        back only when `_integrationId` is sent. Send the flow's `_integrationId`
+        together with `_flowId` whenever the flow document carries one — a flow
+        in the account's "Standalone flows" integration sends that integration's
+        id; only a legacy flow whose `_integrationId` is `null` has none to send.
+
         Date filters accept ISO 8601, plain date, or epoch milliseconds. When
         combining `numError_gte`/`numError_lte` with `_integrationId`, use full
         ISO 8601 with millis (plain-date format may be rejected). To page
@@ -67,7 +83,12 @@ paths:
             x-celigo-refModel: integrations
             examples:
               - 6842261335b64c0bcb308e4f
-          description: Filter by integration ID. Satisfies the required-param check.
+          description: |-
+            Filter by integration ID. Satisfies the required-param check. Callers
+            with integration-only access must send it beside `_flowId` on
+            `type=flow` and `type=retry` queries — `_flowId` alone is refused
+            there. A value that is not the flow's integration returns no jobs
+            rather than an error.
         - name: _exportId
           in: query
           schema:
@@ -91,7 +112,13 @@ paths:
             x-celigo-refModel: flows
             examples:
               - 69f54d6b7009ea11abad707a
-          description: Filter by flow ID. Satisfies the required-param check.
+          description: |-
+            Filter by flow ID. Satisfies the required-param check for
+            account-level callers; callers with integration-only access must
+            also send `_integrationId` on `type=flow` and `type=retry` queries.
+            On its own it resolves the flow document
+            first, so it returns nothing for a flow that no longer exists — pair
+            it with `_integrationId` to read a deleted flow's jobs.
         - name: _flowJobId
           in: query
           schema:
@@ -312,6 +339,12 @@ paths:
                     errors:
                       - code: invalid_query
                         message: For child jobs, query parameters must contain either "_flowJobId" or "resourceId"
+                integration_only_caller_missing_integration_id:
+                  summary: Integration-only caller queried by _flowId without _integrationId
+                  value:
+                    errors:
+                      - code: query_param_required
+                        message: Please provide the integration _id for which you want to fetch the jobs.
                 invalid_status:
                   summary: Invalid status enum value
                   value:

package/dist/tool.yml

@@ -24812,7 +24812,8 @@ components:
             Handlebars template that generates a concurrency lock key for each record: records that
             render the same key are never submitted at the same time, while records with different
             keys are processed in parallel. When omitted, the record's trace key is the lock key (a
-            blank trace key means no lock); a template replaces that default rather than adding to it.
+            blank trace key means no lock; a custom `traceKeyTemplate` upstream arrives on the record
+            as `io_custom_trace_key`); a template replaces that default rather than adding to it.
             The template is rendered from the record as it arrives at the import — before the import's
             own lookups and mapping run — so a key built from one of the import's lookup results
             (`{{lookup.<name>}}`) or from a mapped field renders empty, and an empty key is no lock at
@@ -36956,11 +36957,25 @@ components:
             Handlebars template that overrides how each record's unique trace key is generated, used
             to track records through the flow and match retries to prior errors (e.g.
             `{{join "_" record.customerId record.orderId}}`). When omitted, the system picks a unique
-            field automatically. If a transform reshapes the data first, omit the `record.` prefix.
-            Trace keys are capped at 256 characters; a longer key is stored truncated from the middle,
-            keeping the beginning and end of the value. Downstream imports use the trace key as their
-            default concurrency lock key (a blank key means no lock); it never de-duplicates — a record
-            emitted twice with the same key is processed twice.
+            field automatically from the record's top level, by exact field name (`GET
+            /v1/flows/{_id}/traceKey` serves the pattern). The rendered value of a template is stamped
+            on each record as `io_custom_trace_key` and travels downstream with it. If a transform
+            reshapes the data first, omit the `record.` prefix. Trace keys are capped at 256 characters;
+            a longer key is stored truncated from the middle, keeping the beginning and end of the
+            value. Downstream imports use the trace key as their default concurrency lock key (a blank
+            key means no lock); it never de-duplicates — a record emitted twice with the same key is
+            processed twice.
+          x-celigo-ai-guidance:
+            - |-
+              The default derivation reads these top-level fields in order and takes the first present
+              (a record carrying `id` and `internalId` is keyed on `id` alone) — `id`, `Id`, `ID`,
+              `internalid`, `Internalid`, `internalId`, `InternalId`, `INTERNALID`, `_id`, `_Id`, `_ID`,
+              `internal_id`, `internal_Id`, `Internal_id`, `Internal_Id`, `INTERNAL_ID`, `identifier`,
+              `IDENTIFIER` — then a `*anything` rule the platform does not document.
+            - |-
+              A record in flight through the flow carries `io_custom_trace_key` when a template is set
+              — that value is the downstream imports' default lock key; without a template the record
+              carries no trace-key field (the key is derived, not stored on the record).
           examples:
             - '{{record.id}}'
             - '{{join "_" record.customerId record.orderId}}'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.114",
+  "version": "0.2.116",
   "private": false,
   "description": "Public OpenAPI bundles (dist/) and the celigo-cli lint schema pack (schemas.json).",
   "keywords": [

package/schemas.json

@@ -1,7 +1,7 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "433e7903",
+		"iasCommit": "2cbeaf8b",
 		"generatedAt": "2026-10-15"
 	},
 	"roots": {