@celigo/api-specs 0.2.115 → 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.115",
+  "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": "d2a71cdf",
+		"iasCommit": "2cbeaf8b",
 		"generatedAt": "2026-10-15"
 	},
 	"roots": {