@celigo/api-specs 0.2.202 → 0.2.203

package/dist/job.yml

@@ -48,9 +48,10 @@ paths:
           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.
+        - **Child jobs** (`type=export`, `type=import`, or `type=tool`) — requires
+          `_flowJobId` or a resource ID filter (`_exportId` / `_importId`; for
+          `tool` jobs, `_importId` is the `ToolImport`'s id). Returns the step
+          jobs within a parent flow job.
 
         Job reads are authorized per integration. For a caller with
         integration-only access (an account share that populates
@@ -71,6 +72,11 @@ paths:
         forward, take the `createdAt` of the last record, subtract 1 ms, and
         pass it as `createdAt_lte`.
 
+        The query is validated strictly: a parameter the endpoint does not support
+        fails with `422 invalid_query_params` naming it, and a malformed value — an
+        unrecognized `type` or `status`, a non-numeric count filter, an unparseable
+        date, or a plain string where an array is expected — fails with `400`.
+
         A `queued` or `running` job created outside `createdAt_gte` /
         `createdAt_lte` is left out of a date-filtered list.
       parameters:
@@ -126,27 +132,27 @@ paths:
               - 69f54d6f47185f8c7a500597
           description: |-
             Filter by parent flow-job ID. Satisfies the required-param check.
-            Required when querying child jobs (`type=export` or `type=import`).
-        - name: _flowId_in
+            Required when querying child jobs (`type=export`, `type=import`, or
+            `type=tool`).
+        - name: _flowId_in[]
           in: query
+          style: form
+          explode: true
           schema:
-            type: string
-            examples:
-              - 69f54d6b7009ea11abad707a,69e83e7a75f7f8c14a12916e
-          description: |-
-            Comma-separated list of flow IDs to match. Works as an additional
-            filter but does **not** satisfy the required-param check alone.
-            `flowId_in` (without underscore) is accepted as an alias.
-        - name: status_in
-          in: query
-          schema:
-            type: string
+            type: array
+            items:
+              type: string
+              format: objectId
+              x-celigo-refModel: flows
             examples:
-              - completed,failed
+              - - 69f54d6b7009ea11abad707a
+                - 69e83e7a75f7f8c14a12916e
           description: |-
-            Comma-separated list of status values to match (e.g.
-            `completed,failed`). Works as an additional filter but does
-            **not** satisfy the required-param check alone.
+            Flow IDs to match, sent as one `_flowId_in[]=<id>` pair per ID (indexed
+            `_flowId_in[0]=<id>` also works). A plain `_flowId_in=<id>` value —
+            including a comma-separated list — fails with `400 invalid_query_param`.
+            Works as an additional filter but does **not** satisfy the
+            required-param check alone.
         - name: createdAt_lte
           in: query
           schema:
@@ -245,17 +251,19 @@ paths:
               - import
               - retry
               - bulk_retry
+              - tool
             x-enumDescriptions:
               flow: A parent flow-run job that orchestrates the full pipeline.
               export: A child job for an export step within a flow run.
               import: A child job for an import step within a flow run.
               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.
           description: |-
             Filter by job type. `flow`, `retry`, and `bulk_retry` are
-            parent-level jobs; `export` and `import` are child jobs (require
-            `_flowJobId` or a resource-ID filter). Unrecognized values silently
-            return an empty response.
+            parent-level jobs; `export`, `import`, and `tool` are child jobs
+            (require `_flowJobId` or a resource-ID filter). An unrecognized value
+            fails with `400 invalid_url` ("type is not valid.").
       responses:
         '200':
           description: Array of job records matching the filters.
@@ -319,7 +327,13 @@ paths:
         '204':
           description: No jobs match the given filters.
         '400':
-          description: Required query parameters are missing or invalid.
+          description: |-
+            Required query parameters are missing (`invalid_query`), or a value is
+            malformed: an unrecognized `status` or a non-numeric `numSuccess_*` /
+            `numIgnore_*` filter (`invalid_query_param`), an array parameter sent as
+            a plain string (`invalid_query_param`), an unrecognized `type` or a
+            non-numeric `numError_*` filter (`invalid_url`), or an unparseable date
+            (`invalid_field`).
           content:
             application/json:
               schema:
@@ -349,6 +363,24 @@ paths:
                     errors:
                       - code: invalid_query_param
                         message: The query parameter "status" has invalid value.
+                array_as_string:
+                  summary: Array parameter sent as a plain value
+                  value:
+                    errors:
+                      - code: invalid_query_param
+                        message: The query parameter _flowId_in must be an array. Repeat the parameter for each value, e.g. _flowId_in[0]=value1&_flowId_in[1]=value2.
+                invalid_type:
+                  summary: Unrecognized type value
+                  value:
+                    errors:
+                      - code: invalid_url
+                        message: type is not valid.
+                invalid_date:
+                  summary: Unparseable date filter
+                  value:
+                    errors:
+                      - code: invalid_field
+                        message: 'The value provided for the field: ''createdAt_gte'' is invalid.'
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '422':
@@ -1323,9 +1355,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
@@ -1340,6 +1372,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
@@ -1349,10 +1382,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
@@ -1414,8 +1451,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:
@@ -1507,8 +1545,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:
@@ -1565,7 +1603,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:

package/dist/processor.yml

@@ -1174,8 +1174,10 @@ paths:
 
         `data` is the template's root context: `{{name}}` reads `data.name`. A template written for a
         step reads the record as `{{record.<field>}}`, so send the record under `record`
-        (`"data": {"record": {...}}`). Double braces HTML-escape the value (`&` renders as `&amp;`);
-        triple braces insert it unchanged. A `timestamp` with no time zone renders in UTC.
+        (`"data": {"record": {...}}`). Double braces HTML-escape the value (`&` renders as `&amp;`),
+        or URI-encode it when `options` carries an `http` connection and `fieldPath`
+        `http.relativeURI`; triple braces insert it unchanged. A `timestamp` with no time zone
+        renders in UTC.
 
         A null value, or a field under an object that is null, renders empty here. An HTTP import
         escapes values its own way, at run time and in the import preview: in its JSON body a
@@ -1189,6 +1191,11 @@ paths:
         entry's `helperFunctions`, but that list is not complete: `eq` and `truncateWords`, for
         example, render although it omits them, so render a doubtful helper once here before relying
         on it.
+
+        By default `lookup` doesn't resolve here: each call renders a placeholder such as
+        `{$ASYNCID$0$0$}`, Handlebars' own `{{lookup object key}}` form included, and the placeholder
+        is truthy, so `{{#if (lookup …)}}` always takes its first branch. `options` resolves an HTTP
+        import's static lookups instead (see `options`).
       requestBody:
         required: true
         content:
@@ -1214,6 +1221,63 @@ paths:
                       description: Form of the result; `text` returns the rendered string.
                       examples:
                         - text
+                options:
+                  type: object
+                  description: |-
+                    Step context for a template that calls `{{lookup '<name>' <key>}}`. Send the saved
+                    `import`, its `connection` with `type` `http`, and `fieldPath` to resolve the
+                    import's static lookups (those with a `map`) instead of rendering placeholders. A
+                    template that also calls a dynamic lookup still renders every lookup as a
+                    placeholder, as does an `import` sent without `connection` or a connection of type
+                    `rdbms`, `rest`, `ftp`, `netsuite` or `salesforce`.
+                  properties:
+                    fieldPath:
+                      type: string
+                      description: |-
+                        Field the template belongs to, such as `http.body` or `http.relativeURI`. Required
+                        whenever `connection.type` is `http`, and with that connection `http.relativeURI`
+                        URI-encodes double-brace values instead of HTML-escaping them.
+                      examples:
+                        - http.body
+                      x-celigo-ai-guidance:
+                        - |-
+                          A 422 with an empty `{}` body from this route means `options.connection.type` is
+                          `http` and `options.fieldPath` is missing: every template fails that way until
+                          `fieldPath` names the step field the template belongs to, such as `http.body`.
+                    connection:
+                      type: object
+                      additionalProperties: true
+                      description: The import's connection; `type` `http` turns static lookup resolution on.
+                      properties:
+                        type:
+                          type: string
+                          description: Connection type of the import; static lookups resolve with `http`.
+                          examples:
+                            - http
+                    import:
+                      type: object
+                      additionalProperties: true
+                      description: |-
+                        The saved import whose `http.lookups` the template calls by name. A key found in
+                        a lookup's `map` renders the mapped value, and any other key renders the lookup's
+                        `default`, or empty when it has none. Failures answer 422 with an `errors` array:
+                        `cannot_evaluate_static_lookup` for a key not in the map when the lookup sets
+                        `allowFailures: false`, `lookup_not_found` for a name the import doesn't define
+                        (Handlebars' own `{{lookup object key}}` form included), and
+                        `lookup_data_not_defined` for a key that is missing, empty or the number `0`.
+                  if:
+                    properties:
+                      connection:
+                        properties:
+                          type:
+                            const: http
+                        required:
+                          - type
+                    required:
+                      - connection
+                  then:
+                    required:
+                      - fieldPath
                 data:
                   type: object
                   additionalProperties: true
@@ -1228,6 +1292,27 @@ paths:
                   data:
                     record:
                       name: Smith & Sons
+              static_lookup:
+                summary: Resolve an HTTP import's static lookup
+                value:
+                  rules:
+                    template: '{{lookup ''statusMap'' record.status}}'
+                    resultMode: text
+                  data:
+                    record:
+                      status: '1'
+                  options:
+                    fieldPath: http.body
+                    connection:
+                      type: http
+                    import:
+                      http:
+                        lookups:
+                          - name: statusMap
+                            map:
+                              '1': active
+                              '2': inactive
+                            default: unknown
       responses:
         '200':
           description: The rendered template.
@@ -1256,6 +1341,12 @@ paths:
                     mediaType: text
                     data: Smith &amp; Sons | Smith & Sons
                     duration: 0
+                static_lookup:
+                  summary: Result of the static lookup request example
+                  value:
+                    mediaType: text
+                    data: active
+                    duration: 1
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '422':

package/dist/tool.yml

@@ -1241,8 +1241,8 @@ paths:
         '422':
           description: |-
             A step failed, or the Tool was refused before any step ran: a connection binding is
-            missing (`connection_not_overridden`) or has no `_id`, its branches don't all merge
-            back (`tool_dangling_branch`), or the input fails `input.schema` (a missing `required`
+            missing (`connection_not_overridden`), its branches don't all merge back
+            (`tool_dangling_branch`), or the input fails `input.schema` (a missing `required`
             property answers `tool_input_schema_validation_failed`). The output stage answers 422 too when the stored
             `output.schema` holds `additionalProperties: false` and the output mappings write a field
             it doesn't list ("Tool output validation failed: must NOT have additional properties").
@@ -1250,6 +1250,14 @@ paths:
             `proceedOnFailure: true`: the later steps still run, but the response carries the error,
             not the output. Either way the response includes `invocationId` when logging is active,
             so the run can be opened in the run history.
+
+            Once the Tool is found and has steps, a malformed `overrides` block is refused with
+            `invalid_override` ("Invalid override at <path>. <reason>") before any step runs:
+            `overrides` is not an object, a `connections`/`exports`/`imports`/`routers` value is not
+            an array or holds a non-object entry, a connection binding has no `_abstractId`, names
+            none of `_id`, `_borrowConcurrencyFromConnectionId`, or `requiresEndUserCredentials`, or
+            sets both `_id` and `_borrowConcurrencyFromConnectionId`. These refusals carry only `code`
+            and `message`, and no `invocationId` even with `x-log-mode: debug`.
           content:
             application/json:
               schema:
@@ -1259,7 +1267,7 @@ paths:
                 properties:
                   errors:
                     type: array
-                    description: Execution errors, each with a `code`, `message`, `source`, and epoch-millisecond `time`.
+                    description: Execution errors, each with a `code`, `message`, `source`, and epoch-millisecond `time`. An `invalid_override` refusal has only `code` and `message`.
                     items:
                       type: object
                       additionalProperties: true
@@ -1280,10 +1288,23 @@ paths:
                         message: 'Missing connection overrides. The following connection IDs must be overridden: 6ab1f5657b3d01a9084253a5.'
                     invocationId: 6ab1f5877cd5cdd66da1cc8b
                 binding_without_id:
-                  summary: A connection binding without `_id`
+                  summary: A connection binding with only `_abstractId`
+                  value:
+                    errors:
+                      - code: invalid_override
+                        message: 'Invalid override at overrides.connections[0]. Connection override must include at least one of: _id, _borrowConcurrencyFromConnectionId, requiresEndUserCredentials.'
+                binding_without_abstract_id:
+                  summary: A connection binding without `_abstractId`
+                  value:
+                    errors:
+                      - code: invalid_override
+                        message: Invalid override at overrides.connections[0]._abstractId. Missing required _abstractId.
+                overrides_not_object:
+                  summary: '`overrides` sent as an array'
                   value:
                     errors:
-                      - message: 'Invalid override at overrides.connections[0]. Connection override must include at least one of: _id, _borrowConcurrencyFromConnectionId, requiresEndUserCredentials.'
+                      - code: invalid_override
+                        message: Invalid override at overrides. Expected overrides to be an object.
   /v1/tools/{_id}/invocations:
     get:
       x-internal: false
@@ -1895,12 +1916,14 @@ paths:
         not landed yet; re-query before concluding nothing was stored.
 
         For nested Tools, set `stage` to `tool` with the nested ToolImport id to fetch the
-        composed input/output payload.
+        composed input/output payload; `groupId` is not needed for that stage and is ignored.
+        Until the nested Tool's payloads land, that entry carries only `_expOrImpId` and `stage`.
 
         When the invocation is missing or not visible under the caller's integration ACL,
         the endpoint returns `204 No Content`. `404` applies only to an unknown or inaccessible
-        Tool `_id`. A malformed `executionId` returns `422`, and a body missing any of the four
-        selector keys returns `400`. Sandbox Tools return `403`.
+        Tool `_id`. A malformed `executionId` returns `422`, and a body missing a required
+        selector key (`groupId` is required for every stage except `tool`) returns `400`.
+        Sandbox Tools return `403`.
       parameters:
         - name: _id
           in: path
@@ -1947,7 +1970,6 @@ paths:
                 value:
                   _expOrImpId: 67ee026136f4d1eeb529ad63
                   stage: tool
-                  groupId: g-12345
                   recordId: r-67890
       responses:
         '200':
@@ -2012,6 +2034,21 @@ paths:
                               content-type: application/json; charset=utf-8
                             body: '[{"_id":"6a50f177a8d85436a4a890db","name":"SO-1043"}]'
                     errors: []
+                nestedToolStage:
+                  summary: Nested Tool composed payload — the record it received and the record it returned
+                  value:
+                    logs:
+                      - log:
+                          _expOrImpId: 67ee026136f4d1eeb529ad63
+                          stage: tool
+                          input:
+                            record:
+                              orderId: SO-1043
+                          output:
+                            record:
+                              orderId: SO-1043
+                              title: Sample Slide Show
+                    errors: []
                 noMatch:
                   summary: Selector matched no stored payload
                   value:
@@ -31247,7 +31284,8 @@ components:
               description: |-
                 Provider-native ID of the storage root (e.g. a Google Drive shared-drive ID) the relative
                 path resolves against; set when pathMode is relativePath. The provider's own ID, not a Celigo ID.
-                For Google Cloud Storage it is the bucket name.
+                For Google Cloud Storage it is the bucket name, and a bucket that doesn't exist fails the
+                export preview with 422 `gcs_bucket_not_found`.
               examples:
                 - 1qU1hvFarBFMb4-twqKm1rR5o_6j9vs9g
                 - erp-exports
@@ -39498,8 +39536,15 @@ components:
       required:
         - _expOrImpId
         - stage
-        - groupId
         - recordId
+      if:
+        properties:
+          stage:
+            not:
+              const: tool
+      then:
+        required:
+          - groupId
       properties:
         _expOrImpId:
           type: string
@@ -39526,7 +39571,7 @@ components:
             - tool
         groupId:
           type: string
-          description: Group identifier of the step record.
+          description: Group identifier of the step record. Ignored when `stage` is `tool`.
           examples:
             - YYFuqOqC
         recordId:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.202",
+  "version": "0.2.203",
   "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": "4a026a0b",
+		"iasCommit": "d2f3a96e",
 		"generatedAt": "2026-10-28"
 	},
 	"roots": {