@celigo/api-specs 0.2.202 → 0.2.204

package/dist/flow.yml

@@ -3018,6 +3018,10 @@ paths:
         preference is off, a flow set to `basic` captures nothing and its jobs carry no `logMode`. Jobs older
         than the flow's log retention window will return an empty `logs` array.
 
+        A ToolImport step's tool chain is returned as one entry per record and chain, carrying
+        `_toolImportId`: the steps inside the tool and any nested tools do not get entries of their own,
+        and the entry's `status` is `error` when any step in the chain errored.
+
         For per-stage data (an HTTP request and response, or a mapping's or script hook's input and
         output), pick an entry and call `POST .../logs/data/query` with the corresponding `stage`. To stitch an
         export entry to its downstream imports, use the `traceKey` with
@@ -3042,7 +3046,7 @@ paths:
         - name: status
           in: query
           required: false
-          description: Filter log entries by record outcome.
+          description: Filter log entries by record outcome. A ToolImport chain entry matches on its rolled-up `status`.
           schema:
             type: string
             enum:
@@ -3056,7 +3060,10 @@ paths:
         - name: _expOrImpId
           in: query
           required: false
-          description: Comma-separated list of export or import step ids. Only entries produced by these steps are returned.
+          description: |-
+            Comma-separated list of export or import step ids. Only entries produced by these steps are returned.
+            A ToolImport step id returns that step's chain entries, one per record; the id of a step inside
+            its tool, a nested ToolImport included, returns no entries.
           schema:
             type: string
         - name: traceKeyPrefix
@@ -3114,6 +3121,27 @@ paths:
                         timeTaken: 1744
                     nextPageUrl: null
                     prevPageUrl: null
+                tool_import_run:
+                  summary: An export feeding a ToolImport step whose tool chain failed inside the tool
+                  value:
+                    logs:
+                      - startedAt: '2026-10-28T01:04:03.639000Z'
+                        recordId: FhaPg7Nv
+                        groupId: 7gprZE6q
+                        traceKey: '1'
+                        _expOrImpId: 6ae149afa8b7937d2e5a3765
+                        status: error
+                        timeTaken: 69
+                        _toolImportId: 6ae149afa8b7937d2e5a3765
+                      - startedAt: '2026-10-28T01:03:38.565000Z'
+                        recordId: iOp3KKIq
+                        groupId: PZZZpe8u
+                        traceKey: '1'
+                        _expOrImpId: 6ae14994a8b7937d2e5a3741
+                        status: success
+                        timeTaken: 41
+                    nextPageUrl: null
+                    prevPageUrl: null
                 empty_no_debug:
                   summary: No log entries available for the run
                   value:
@@ -3144,6 +3172,15 @@ paths:
         `duplicateTraceKey` is `true`, the traceKey was seen on more than one record in the job, so
         results may mix records from retries or fan-out. Without `traceKey` in the request,
         `traceView` is `false` and only the single queried step is returned.
+
+        For a ToolImport step, send the entry's `_toolImportId` to trace its tool chain; `groupId` is then
+        not needed and is ignored, and `steps` lists every step of the chain, nested tools included, with
+        `traceView` `false`. When `traceKey` also resolves a full flow trace, the steps come from that
+        trace and the tool chain appears within them.
+
+        A missing `recordId` or `_expOrImpId`, or a missing `groupId` without `_toolImportId`, returns
+        `400` `missing_required_field`. A non-string `groupId` or `recordId`, or a `_toolImportId` that is
+        not a valid id, returns `400` `invalid_field`.
       parameters:
         - name: _id
           in: path
@@ -3181,6 +3218,12 @@ paths:
                   groupId: 1WsTiyxQ
                   recordId: CMeN0hDc
                   traceKey: '0'
+              tool_chain:
+                summary: Every step of a ToolImport step's tool chain for one record
+                value:
+                  _expOrImpId: 6ae149afa8b7937d2e5a3765
+                  recordId: cAl5nHBP
+                  _toolImportId: 6ae149afa8b7937d2e5a3765
       responses:
         '200':
           description: Step metadata (or a trace across paired steps when `traceKey` was supplied).
@@ -3223,8 +3266,68 @@ paths:
                         timeTaken: 1744
                         startedAt: '2026-04-23 02:51:45.066'
                         completedAt: '2026-04-23 02:51:46.810'
+                tool_chain:
+                  summary: A ToolImport chain with a nested tool; both levels completed, so each is one step
+                  value:
+                    duplicateTraceKey: false
+                    traceView: false
+                    steps:
+                      - _expOrImpId: 6ae149afa8b7937d2e5a3765
+                        recordId: cAl5nHBP
+                        groupId: tiGa65Ii
+                        status: success
+                        timeTaken: 1087
+                        startedAt: '2026-10-28 01:06:32.434'
+                        completedAt: '2026-10-28 01:07:23.501'
+                        _toolImportId: 6ae149afa8b7937d2e5a3765
+                        outputGroupId: l6c2lG3p
+                      - _expOrImpId: 6ae14996cde0d88a5bbfad2c
+                        recordId: cAl5nHBP
+                        groupId: 3hQzg1Ih
+                        status: success
+                        timeTaken: 96
+                        startedAt: '2026-10-28 01:06:41.108'
+                        completedAt: '2026-10-28 01:06:41.204'
+                        _toolImportId: 6ae149afa8b7937d2e5a3765
+                      - _expOrImpId: 6ae149a3be555e5e52cb1994
+                        recordId: cAl5nHBP
+                        groupId: HaFyH4Nf
+                        status: success
+                        timeTaken: 67
+                        startedAt: '2026-10-28 01:06:52.861'
+                        completedAt: '2026-10-28 01:07:13.604'
+                        _toolImportId: 6ae149afa8b7937d2e5a3765
+                        outputGroupId: JcfPMY4T
+                      - _expOrImpId: 6ae14995a8b7937d2e5a374f
+                        recordId: cAl5nHBP
+                        groupId: DLnI66c3
+                        status: success
+                        timeTaken: 136
+                        startedAt: '2026-10-28 01:07:01.160'
+                        completedAt: '2026-10-28 01:07:01.296'
+                        _toolImportId: 6ae149afa8b7937d2e5a3765
         '400':
-          $ref: '#/components/responses/400-bad-request'
+          description: A required selector is missing, or a selector has the wrong type.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                missing_selector:
+                  value:
+                    errors:
+                      - code: missing_required_field
+                        message: groupId, recordId, _expOrImpId is required.
+                invalid_type:
+                  value:
+                    errors:
+                      - code: invalid_field
+                        message: groupId must be a string.
+                invalid_tool_import_id:
+                  value:
+                    errors:
+                      - code: invalid_field
+                        message: _toolImportId must be a valid id.
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '404':
@@ -3245,6 +3348,11 @@ paths:
         that its name is valid: the server answers an unknown stage name the same way as a stage that
         captured nothing, so check the stage name and the job's `logMode` (`GET /v1/jobs/{_id}`)
         before concluding the step recorded nothing.
+
+        For a ToolImport step, set `stage` to `tool` to get the record's input to and output from the
+        whole tool, without `groupId`. With `stage` `tool`, a missing `recordId` or `_expOrImpId` returns
+        `400` `missing_required_field`, and a `_toolImportId` that differs from `_expOrImpId` returns
+        `400` `invalid_exp_or_imp_id`.
       parameters:
         - name: _id
           in: path
@@ -3283,6 +3391,13 @@ paths:
                   groupId: 4tQqtS
                   recordId: f0xVak
                   stage: preMapHook
+              tool_stage:
+                summary: Fetch a ToolImport step's composed input and output
+                value:
+                  _expOrImpId: 6ae149afa8b7937d2e5a3765
+                  _toolImportId: 6ae149afa8b7937d2e5a3765
+                  recordId: cAl5nHBP
+                  stage: tool
       responses:
         '200':
           description: Log entries for the requested `(step, stage)`.
@@ -3329,13 +3444,71 @@ paths:
                                 phoneExtension: '12'
                           errors: []
                     errors: []
+                tool_stage:
+                  summary: stage tool on a ToolImport step whose chain completed
+                  value:
+                    logs:
+                      - log:
+                          stage: tool
+                          recordId: cAl5nHBP
+                          groupId: tiGa65Ii
+                          outputGroupId: l6c2lG3p
+                          input:
+                            record:
+                              id: 1
+                              name: Leanne Graham
+                          output:
+                            record:
+                              id: 1
+                              postTitle: sunt aut facere repellat provident
+                    errors: []
+                tool_stage_chain_error:
+                  summary: stage tool on a ToolImport step whose chain failed inside the tool
+                  value:
+                    logs:
+                      - log:
+                          stage: tool
+                          recordId: FhaPg7Nv
+                          groupId: 7gprZE6q
+                          input:
+                            record:
+                              id: 1
+                              name: Leanne Graham
+                    errors:
+                      - errorId: '6461095244'
+                        errorMessage: 'id: String contains alpha characters'
+                        errorCode: non_parsable_string
+                        errorSource: resource
                 empty_result:
                   summary: Nothing captured for the stage, or an unknown stage name
                   value:
                     logs: []
                     errors: []
         '400':
-          $ref: '#/components/responses/400-bad-request'
+          description: A required selector is missing, or a ToolImport selector is invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                missing_selector:
+                  summary: stage tool without recordId
+                  value:
+                    errors:
+                      - code: missing_required_field
+                        message: recordId is required.
+                missing_group_id:
+                  summary: A stage other than tool without groupId
+                  value:
+                    errors:
+                      - code: missing_required_field
+                        message: groupId is required.
+                tool_import_mismatch:
+                  summary: _toolImportId differs from _expOrImpId
+                  value:
+                    errors:
+                      - code: invalid_exp_or_imp_id
+                        message: Please provide a valid _expOrImpId.
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '404':
@@ -7242,9 +7415,9 @@ components:
         A job represents one execution of a flow/export/import (or a retry) in integrator.io.
         Jobs are read-only records created by the platform when executions occur.
 
-        Parent jobs (`type: flow`) carry aggregate counters; child jobs (`type: export` or `import`)
-        carry per-step counters -- do not sum both to avoid double-counting. `_exportId` on a parent
-        flow job references the page-generator export, not all exports in the flow.
+        Parent jobs (`type: flow`) carry aggregate counters; child jobs (`type: export`, `import`, or
+        `tool`) carry per-step counters -- do not sum both to avoid double-counting. `_exportId` on a
+        parent flow job references the page-generator export, not all exports in the flow.
       allOf:
         - $ref: '#/components/schemas/ResourceResponse'
         - type: object
@@ -7259,6 +7432,7 @@ components:
                 - flow
                 - retry
                 - bulk_retry
+                - tool
               x-enumDescriptions:
                 export: |-
                   A child job for an export step within a flow run: the flow's source export, or a
@@ -7268,10 +7442,14 @@ components:
                 flow: A parent flow-run job that orchestrates the full pipeline.
                 retry: A retry of a single failed record from a previous job.
                 bulk_retry: A bulk retry of multiple failed records from a previous job.
+                tool: |-
+                  A child job for a Tool step (a `ToolImport`) within a flow run. A lookup step inside
+                  the Tool gets its own `export` child job under the same flow job.
               x-celigo-ai-guidance:
                 - |-
                   - `flow`: a flow run (parent job)
                   - `export` / `import`: child jobs for an export/import step
+                  - `tool`: child job for a Tool step (`ToolImport`); a lookup step inside the Tool is listed as its own `export` child job of the same flow job
                   - `retry` / `bulk_retry`: error management retries
             status:
               type: string
@@ -7333,8 +7511,9 @@ components:
               readOnly: true
               description: |-
                 The export or import resource ID for this child job. Present on child
-                jobs (`type: export` or `type: import`) — check `type` to determine
-                whether this references an export or import resource.
+                jobs (`type: export`, `import`, or `tool`) — check `type`: an `export` job
+                references an export, an `import` job an import, and a `tool` job the
+                `ToolImport` that ran the Tool.
               examples:
                 - 69f54d6c1e7f3a22cc7848b2
             _retryOfJobId:
@@ -7426,8 +7605,8 @@ components:
                 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.
+                user who submitted the retry. Absent on `export`, `import`, and `tool` child jobs —
+                the parent flow job carries it.
               examples:
                 - system
             canceledBy:
@@ -7484,7 +7663,8 @@ components:
               description: |-
                 Number of records processed successfully. On a parent flow job (`type: flow`) this is the
                 sum across every step in the run, so one record that passes through an export and an import
-                counts twice. On a child job (`type: export` or `import`) it is that step's count alone.
+                counts twice. On a child job (`type: export`, `import`, or `tool`) it is that step's count
+                alone.
                 For per-step counts, read the run with `GET /v1/jobs/{_id}/family` or list its children with
                 `GET /v1/jobs?_flowJobId={_id}&type=import`.
               examples:
@@ -8059,9 +8239,21 @@ components:
           description: Id of the export or import step that produced this entry.
           examples:
             - 60a2c4e6f321d800129a1a3c
+        _toolImportId:
+          type: string
+          format: objectId
+          x-celigo-refModel: imports
+          description: |-
+            ToolImport step that owns the tool chain this entry rolls up, the same id as `_expOrImpId`.
+            Present only on ToolImport chain entries; pass it as `_toolImportId` to `metadata/query` to
+            trace the chain, and to `data/query` with `stage` `tool` to read the chain's errors.
+          examples:
+            - 60a2c4e6f321d800129a1a3c
         status:
           type: string
-          description: Outcome of this step for this record.
+          description: |-
+            Outcome of this step for this record. A ToolImport chain entry is `error` when any step in
+            the chain errored, even if the ToolImport's own pass succeeded.
           enum:
             - success
             - error
@@ -8103,6 +8295,7 @@ components:
         Request body for `POST /v1/flows/{_id}/jobs/{_jobId}/logs/metadata/query`.
         Identifies a single record-at-step within the job's execution log. Include `traceKey` to widen
         the result to every step that shared that trace (export paired with its downstream imports).
+        Send `groupId` unless the request traces a ToolImport chain with `_toolImportId`.
       properties:
         _expOrImpId:
           type: string
@@ -8112,7 +8305,7 @@ components:
             - 60a2c4e6f321d800129a1a3c
         groupId:
           type: string
-          description: The `groupId` from the matching `execution-log` entry.
+          description: The `groupId` from the matching `execution-log` entry. Ignored when `_toolImportId` is sent.
           examples:
             - g_5f8d43a1b9e5a80011a35f2d
         recordId:
@@ -8120,6 +8313,16 @@ components:
           description: The `recordId` from the matching `execution-log` entry.
           examples:
             - r_0001
+        _toolImportId:
+          type: string
+          format: objectId
+          x-celigo-refModel: imports
+          description: |-
+            ToolImport step whose tool chain to trace, from the `_toolImportId` of an `execution-log`
+            entry. Scopes the returned steps to that chain and makes `groupId` unnecessary. A value that
+            is not a valid id returns `400` `invalid_field`.
+          examples:
+            - 60a2c4e6f321d800129a1a3c
         traceKey:
           type: string
           description: |-
@@ -8129,8 +8332,14 @@ components:
             - ORD-100245
       required:
         - _expOrImpId
-        - groupId
         - recordId
+      if:
+        not:
+          required:
+            - _toolImportId
+      then:
+        required:
+          - groupId
     ExecutionLogStep:
       type: object
       description: Per-step timing and outcome for a single record as it passed through one export or import.
@@ -8148,12 +8357,33 @@ components:
             - r_0001
         groupId:
           type: string
-          description: Opaque batch id.
+          description: Opaque batch id. For a ToolImport level that recorded both its input and its output, the input-side group.
           examples:
             - g_5f8d43a1b9e5a80011a35f2d
+        outputGroupId:
+          type: string
+          description: |-
+            Output-side batch id of a ToolImport level, nested levels included. Present when the request
+            traced the chain (`_toolImportId` or `traceKey`) and that level recorded both its input and its
+            output, which are then returned as this one step; a level whose output pass never ran stays a
+            step without this field.
+          examples:
+            - g_7ab12c
+        _toolImportId:
+          type: string
+          format: objectId
+          x-celigo-refModel: imports
+          description: |-
+            Outermost ToolImport step that owns the tool chain. Present on every step of a ToolImport
+            chain, including steps of nested tools; omitted for other steps.
+          examples:
+            - 60a2c4e6f321d800129a1a3c
         status:
           type: string
-          description: Outcome at this step.
+          description: |-
+            Outcome at this step. The outermost ToolImport step is `error` when any step in its chain
+            errored, even if its own pass succeeded; its `stage` then stays empty, and the step that
+            failed names the stage.
           enum:
             - success
             - error
@@ -8207,14 +8437,18 @@ components:
           description: |-
             `true` when the same traceKey was seen on more than one record in this job — useful for spotting
             records that got retried or fanned out and may need disambiguation when rendering the trace view.
+            Counts distinct `recordId` values, so the several steps of one record's ToolImport chain do not set it.
         traceView:
           type: boolean
           description: |-
             `true` when the response contains a multi-step trace (i.e. the request supplied `traceKey` and paired
-            steps were found). `false` when the response is scoped to the single queried step.
+            steps were found). `false` when the response is scoped to the single queried step, or to the tool
+            chain named by `_toolImportId`.
         steps:
           type: array
-          description: Per-step metadata. A single entry when `traceView` is false; one per paired step otherwise.
+          description: |-
+            Per-step metadata. When `traceView` is false, the single queried step, or every step of the tool
+            chain (in no fixed order) when the request sent `_toolImportId`; one per paired step otherwise.
           items:
             $ref: '#/components/schemas/ExecutionLogStep'
     ExecutionLogDataRequest:
@@ -8241,7 +8475,8 @@ components:
             return value under its hook type plus `Hook` (`preSavePageHook`, `preMapHook`,
             `postMapHook`, `postSubmitHook`, `postResponseMapHook`), whatever the function is called;
             neither the bare hook name (`preMap`) nor `<functionName>Hook` returns them (live-verified
-            2026-10-20; `inputFilter` 2026-10-22).
+            2026-10-20; `inputFilter` 2026-10-22). `tool` returns a ToolImport step's composed input and
+            output for the record; it needs no `groupId`.
           examples:
             - apiCall
             - transformation
@@ -8254,9 +8489,10 @@ components:
             - postMapHook
             - postSubmitHook
             - postResponseMapHook
+            - tool
         groupId:
           type: string
-          description: Batch id from the `execution-log` entry.
+          description: Batch id from the `execution-log` entry. Ignored when `stage` is `tool`.
           examples:
             - g_5f8d43a1b9e5a80011a35f2d
         recordId:
@@ -8264,11 +8500,29 @@ components:
           description: Record id from the `execution-log` entry.
           examples:
             - r_0001
+        _toolImportId:
+          type: string
+          format: objectId
+          x-celigo-refModel: imports
+          description: |-
+            Outermost ToolImport of the chain. Set it to the same value as `_expOrImpId` when `stage` is
+            `tool` and `_expOrImpId` is the outermost ToolImport, so the response carries the chain's
+            errors; without it `errors` comes back empty. Omit it for a tool nested inside another. A
+            different value or a malformed id returns `400` `invalid_exp_or_imp_id`.
+          examples:
+            - 60a2c4e6f321d800129a1a3c
       required:
         - _expOrImpId
         - stage
-        - groupId
         - recordId
+      if:
+        properties:
+          stage:
+            not:
+              const: tool
+      then:
+        required:
+          - groupId
     ExecutionLogDataResponse:
       type: object
       description: |-
@@ -8288,6 +8542,12 @@ components:
           group, with no `recordId`. `input` is a one-element array holding the `options` the hook received,
           and `output` holds what the hook returned.
         - `postResponseMapHook`: `recordId` is null, and `input` is the `options` object itself.
+        - `tool`: one entry with `stage`, `recordId`, `groupId` (the input-side batch), `outputGroupId`,
+          and the record entering the ToolImport (`input`) and the record it returned (`output`), each as
+          `{record}`. `outputGroupId` appears once the tool's output pass has run and `output` once that
+          pass stored a record, so a chain that failed inside the tool has `input` only. Payloads are
+          written after the job's step records, so right after a run a side can be missing because it has
+          not landed yet; re-query before treating it as absent.
       properties:
         logs:
           type: array
@@ -8303,7 +8563,10 @@ components:
           type: array
           description: |-
             Query-scoped errors. Some adaptors (e.g. NetSuiteDistributedImport) attach the actual failure here rather
-            than inside `logs[].log.errors`. Empty on success.
+            than inside `logs[].log.errors`. Empty on success. For `stage` `tool` with `_toolImportId`, holds
+            the errors the whole tool chain recorded for the record, each with `errorId`, `errorMessage`,
+            `errorCode` and `errorSource`; a nested tool, or a request without `_toolImportId`, gets an empty
+            array.
           items:
             type: object
             additionalProperties: true
@@ -8507,6 +8770,28 @@ components:
                 _connectionId: 5f7c579b6411271af4e7cefb
               options:
                 preview: true
+        _toolId:
+          type: string
+          format: objectId
+          x-celigo-refModel: tools
+          description: |-
+            Makes this a Tool preview: the steps see a fixed sample caller context, read as
+            `{{context.*}}` in HTTP request templates, `options.context` in hooks and script
+            transforms, and `["context", "<path>"]` in filter rules (`context.byUser.email` is
+            `sample.user@example.com`). Send the Tool's flow shape with its `routers` and its steps in
+            the maps; the tool itself isn't read, and in a shape without `routers` the page generator's
+            own filter, transform and hooks don't see the sample. Without `_toolId` steps have no
+            `context`: `{{context.*}}` fails an HTTP relative URI or header with 422
+            `handlebars_template_parse_error` and renders empty in a body.
+          x-celigo-ai-guidance:
+            - |-
+              The caller context in a Tool preview is a fixed sample, never the real caller: token
+              type oauth; byUser Sample User (sample.user@example.com) with one group, Sample Group,
+              and one role, Sample Role; client sample-client 0.0.0; source Sample MCP Server (type
+              mcpServer). Filters and branches written against real caller values don't match it
+              during preview.
+          examples:
+            - 64a1234567890abcdef54321
         includeStages:
           type: boolean
           description: |-