@celigo/api-specs 0.2.202 → 0.2.204

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/mcp-server.yml

@@ -220,6 +220,7 @@ paths:
                     policies: []
                     createdAt: '2026-04-24T16:52:05.607Z'
                     lastModified: '2026-04-24T16:52:05.607Z'
+                    enabledItemCount: 0
         '400':
           $ref: '#/components/responses/400-bad-request'
         '401':
@@ -347,8 +348,8 @@ paths:
         prompts, resources, connections, upstream MCP connections, and OAuth
         settings. Each upstream connection row is enriched with the connection's
         current `name` and each upstream capability with its effective `title`,
-        `annotations`, and (when overridden) `name`; `enabledItemCount` is
-        computed on this response and the list response only.
+        `annotations`, and (when overridden) `name`, and `enabledItemCount` is
+        computed. The list, POST, and PUT responses carry the same enrichment.
       operationId: getMcpServerById
       tags:
         - MCP Servers
@@ -596,6 +597,7 @@ paths:
                       useCeligoOauth: true
                     createdAt: '2026-04-24T16:52:05.607Z'
                     lastModified: '2026-05-07T15:22:16.985Z'
+                    enabledItemCount: 3
         '400':
           $ref: '#/components/responses/400-bad-request'
         '401':
@@ -3704,11 +3706,6 @@ components:
           resources combined: the 501st row fails the whole PUT with 422
           "mcp_upstream_max_capabilities" on upstreamMcpConnections[{index}].
           The cap is per attachment, so a second connection gets its own 500.
-        - |-
-          Set alias explicitly when the connection name is longer than 32
-          characters: the alias derived from the name on first attach fails the
-          PUT with 422 "size_limit_exceeded" on upstreamMcpConnections.{index}.alias,
-          the same response an explicit alias of 33 or more characters gets.
       required:
         - _connectionId
       properties:
@@ -3728,11 +3725,14 @@ components:
           description: |-
             Short handle that namespaces the upstream's capabilities on this
             server. Lowercased on save and unique per server (case-insensitive) —
-            a duplicate is rejected with 422 `mcp_upstream_duplicate_alias`, an
-            invalid character with 422 `mcp_upstream_invalid_alias_charset`, and
-            an over-long value with 422 `size_limit_exceeded`.
-            Derived from the connection name when omitted on the first attach, so
-            a name longer than the alias cap needs an explicit alias.
+            a duplicate is rejected with 422 `mcp_upstream_duplicate_alias` and an
+            invalid character with 422 `mcp_upstream_invalid_alias_charset`.
+            Derived from the connection name when omitted on the first attach,
+            with every character other than a letter, digit, `-`, or `_` turned
+            into `_`. POST, PUT, and PATCH shorten a sent or derived value over 32
+            characters to 32 instead of rejecting it: the cut drops trailing `_`
+            (and, for a sent value, trailing `-`), and a `_2`, `_3`, … suffix
+            within the 32 settles a collision with another alias on the server.
           examples:
             - deepwiki
             - crm_tools
@@ -3741,7 +3741,7 @@ components:
           readOnly: true
           description: |-
             Current display name of the attached connection, joined from the
-            connection record on GET and list responses.
+            connection record on GET, list, POST, and PUT responses.
           examples:
             - DeepWiki MCP
         discoveryStatus:
@@ -4419,9 +4419,9 @@ components:
               description: |-
                 Number of capabilities currently served — enabled `tools`, `apis`,
                 `prompts`, and `resources` plus every enabled and available upstream
-                tool, prompt, and resource row. Computed on GET and list responses
-                only (it is absent from create and update responses) and reported
-                even when `include` omits the arrays it counts.
+                tool, prompt, and resource row. Computed on GET, list, POST, and
+                PUT responses, and reported even when `include` omits the arrays
+                it counts.
               examples:
                 - 5
             draft:

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/storagequery.yml

@@ -74,6 +74,9 @@ paths:
         total bytes a statement may read are each capped; the 422 that reports an exceeded
         cap names the current limit. Requires the account's license to include the Storage
         Query entitlement (`filesql`).
+      parameters:
+        - $ref: '#/components/parameters/AShareIdHeader'
+        - $ref: '#/components/parameters/EnvIdHeader'
       requestBody:
         required: true
         content:
@@ -150,8 +153,13 @@ paths:
         '403':
           description: |-
             The account's license does not include the Storage Query entitlement
-            (`STORAGE_QUERY_NOT_ENTITLED`). Also returned when the caller's role,
-            environment, or account-share context does not permit the query.
+            (`STORAGE_QUERY_NOT_ENTITLED`), or the account context is refused: the caller
+            has accepted an account share but sent no `integrator-ashareid`
+            (`STORAGE_QUERY_ASHARE_HEADER_REQUIRED`), `integrator-ashareid` and
+            `integrator-envid` were both sent (`STORAGE_QUERY_CONFLICTING_ACCOUNT_HEADERS`),
+            `integrator-envid` is not an environment of the caller's account
+            (`STORAGE_QUERY_INVALID_ENVIRONMENT`), or `integrator-ashareid` is not a share
+            accepted by the caller (`STORAGE_QUERY_ACCESS_REFUSED`).
           content:
             application/json:
               schema:
@@ -162,6 +170,30 @@ paths:
                     errors:
                       - code: STORAGE_QUERY_NOT_ENTITLED
                         message: Storage query is not enabled for this account
+                ashareHeaderRequired:
+                  summary: Caller has an accepted share but sent no integrator-ashareid
+                  value:
+                    errors:
+                      - code: STORAGE_QUERY_ASHARE_HEADER_REQUIRED
+                        message: This account is shared with you; resend the query with the integrator-ashareid header
+                conflictingAccountHeaders:
+                  summary: integrator-ashareid and integrator-envid sent together
+                  value:
+                    errors:
+                      - code: STORAGE_QUERY_CONFLICTING_ACCOUNT_HEADERS
+                        message: integrator-ashareid and integrator-envid cannot be combined; send only the one that names the account for this query
+                invalidEnvironment:
+                  summary: integrator-envid is not an environment of this account
+                  value:
+                    errors:
+                      - code: STORAGE_QUERY_INVALID_ENVIRONMENT
+                        message: The requested environment is not available for this account
+                accessRefused:
+                  summary: integrator-ashareid is not a share accepted by the caller
+                  value:
+                    errors:
+                      - code: STORAGE_QUERY_ACCESS_REFUSED
+                        message: Your role, environment or account sharing does not permit this query
         '404':
           description: |-
             A referenced storage path did not resolve to a file the caller can read
@@ -189,16 +221,18 @@ paths:
             whose first argument is not a literal path or list of paths
             (`STORAGE_QUERY_READER_PATH_NOT_LITERAL`); a reader that does not match the
             file's format (`STORAGE_QUERY_READER_FORMAT_MISMATCH`); a row generator with no
-            file reference (`STORAGE_QUERY_NO_STORAGE_REFERENCE`) or one that would generate
-            more rows than allowed (`STORAGE_QUERY_GENERATOR_TOO_LARGE`); a schema- or
+            file reference (`STORAGE_QUERY_NO_STORAGE_REFERENCE`), one whose arguments are
+            not all whole-number literals (`STORAGE_QUERY_GENERATOR_ARGUMENT_NOT_LITERAL`),
+            or one that would generate more rows than allowed
+            (`STORAGE_QUERY_GENERATOR_TOO_LARGE`); a schema- or
             catalog-qualified table name, or a path carrying a wildcard
             (`STORAGE_QUERY_INVALID_SOURCE`); a folder path without its trailing slash
             (`STORAGE_NOT_A_FILE`) or a file path with one (`STORAGE_ITEM_NOT_FOLDER`); an
             unsupported file type (`STORAGE_QUERY_UNSUPPORTED_FILE_TYPE`) — a compressed
             file is refused too, with "Querying `<name>` is not supported; supported formats
-            are CSV, JSON, NDJSON, and Parquet"; a file still uploading ("Upload for `<path>`
-            is not yet complete"); a folder that is
-            empty, mixes formats, or holds too many files (`STORAGE_QUERY_FOLDER_EMPTY`,
+            are CSV, JSON, NDJSON, and Parquet"; a file still uploading
+            (`STORAGE_ITEM_NOT_ACTIVE`, "Upload for `<path>` is not yet complete"); a folder
+            that is empty, mixes formats, or holds too many files (`STORAGE_QUERY_FOLDER_EMPTY`,
             `STORAGE_QUERY_MIXED_FORMAT_FOLDER`, `STORAGE_QUERY_FOLDER_TOO_MANY_FILES`); too
             many distinct files (`STORAGE_QUERY_TOO_MANY_SOURCES`); or more input bytes than
             the cap (`STORAGE_QUERY_INPUT_TOO_LARGE`).
@@ -243,6 +277,18 @@ paths:
                     errors:
                       - code: STORAGE_QUERY_NO_STORAGE_REFERENCE
                         message: A query that generates rows must read at least one Celigo Storage file; only constant expressions may omit a file reference
+                generatorArgumentNotLiteral:
+                  summary: Row generator argument that is an expression
+                  value:
+                    errors:
+                      - code: STORAGE_QUERY_GENERATOR_ARGUMENT_NOT_LITERAL
+                        message: Every argument of generate_series must be a whole-number literal so the row count can be checked before the query runs
+                fileStillUploading:
+                  summary: File whose upload has not finished
+                  value:
+                    errors:
+                      - code: STORAGE_ITEM_NOT_ACTIVE
+                        message: Upload for "/orders/2026/batch-07.csv" is not yet complete
                 wildcardPath:
                   summary: Wildcard in a storage path
                   value:
@@ -311,6 +357,8 @@ paths:
             format: objectId
             examples:
               - 6ab5a7d0c772d334c44701be
+        - $ref: '#/components/parameters/AShareIdHeader'
+        - $ref: '#/components/parameters/EnvIdHeader'
       responses:
         '200':
           description: Current state of the job.
@@ -376,7 +424,15 @@ paths:
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '403':
-          description: The account's license does not include the Storage Query entitlement (`STORAGE_QUERY_NOT_ENTITLED`).
+          description: |-
+            The account's license does not include the Storage Query entitlement
+            (`STORAGE_QUERY_NOT_ENTITLED`), or the account context is refused: the caller
+            has accepted an account share but sent no `integrator-ashareid`
+            (`STORAGE_QUERY_ASHARE_HEADER_REQUIRED`), `integrator-ashareid` and
+            `integrator-envid` were both sent (`STORAGE_QUERY_CONFLICTING_ACCOUNT_HEADERS`),
+            `integrator-envid` is not an environment of the caller's account
+            (`STORAGE_QUERY_INVALID_ENVIRONMENT`), or `integrator-ashareid` is not a share
+            accepted by the caller (`STORAGE_QUERY_ACCESS_REFUSED`).
           content:
             application/json:
               schema:
@@ -387,6 +443,30 @@ paths:
                     errors:
                       - code: STORAGE_QUERY_NOT_ENTITLED
                         message: Storage query is not enabled for this account
+                ashareHeaderRequired:
+                  summary: Caller has an accepted share but sent no integrator-ashareid
+                  value:
+                    errors:
+                      - code: STORAGE_QUERY_ASHARE_HEADER_REQUIRED
+                        message: This account is shared with you; resend the query with the integrator-ashareid header
+                conflictingAccountHeaders:
+                  summary: integrator-ashareid and integrator-envid sent together
+                  value:
+                    errors:
+                      - code: STORAGE_QUERY_CONFLICTING_ACCOUNT_HEADERS
+                        message: integrator-ashareid and integrator-envid cannot be combined; send only the one that names the account for this query
+                invalidEnvironment:
+                  summary: integrator-envid is not an environment of this account
+                  value:
+                    errors:
+                      - code: STORAGE_QUERY_INVALID_ENVIRONMENT
+                        message: The requested environment is not available for this account
+                accessRefused:
+                  summary: integrator-ashareid is not a share accepted by the caller
+                  value:
+                    errors:
+                      - code: STORAGE_QUERY_ACCESS_REFUSED
+                        message: Your role, environment or account sharing does not permit this query
         '404':
           description: No job with this id is visible to the caller (`STORAGE_QUERY_JOB_NOT_FOUND`) — unknown, expired, or submitted by another account.
           content:
@@ -446,6 +526,8 @@ paths:
             format: objectId
             examples:
               - 6ab5a7d0c772d334c44701be
+        - $ref: '#/components/parameters/AShareIdHeader'
+        - $ref: '#/components/parameters/EnvIdHeader'
         - name: page
           in: query
           required: false
@@ -510,7 +592,15 @@ paths:
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '403':
-          description: The account's license does not include the Storage Query entitlement (`STORAGE_QUERY_NOT_ENTITLED`).
+          description: |-
+            The account's license does not include the Storage Query entitlement
+            (`STORAGE_QUERY_NOT_ENTITLED`), or the account context is refused: the caller
+            has accepted an account share but sent no `integrator-ashareid`
+            (`STORAGE_QUERY_ASHARE_HEADER_REQUIRED`), `integrator-ashareid` and
+            `integrator-envid` were both sent (`STORAGE_QUERY_CONFLICTING_ACCOUNT_HEADERS`),
+            `integrator-envid` is not an environment of the caller's account
+            (`STORAGE_QUERY_INVALID_ENVIRONMENT`), or `integrator-ashareid` is not a share
+            accepted by the caller (`STORAGE_QUERY_ACCESS_REFUSED`).
           content:
             application/json:
               schema:
@@ -521,6 +611,30 @@ paths:
                     errors:
                       - code: STORAGE_QUERY_NOT_ENTITLED
                         message: Storage query is not enabled for this account
+                ashareHeaderRequired:
+                  summary: Caller has an accepted share but sent no integrator-ashareid
+                  value:
+                    errors:
+                      - code: STORAGE_QUERY_ASHARE_HEADER_REQUIRED
+                        message: This account is shared with you; resend the query with the integrator-ashareid header
+                conflictingAccountHeaders:
+                  summary: integrator-ashareid and integrator-envid sent together
+                  value:
+                    errors:
+                      - code: STORAGE_QUERY_CONFLICTING_ACCOUNT_HEADERS
+                        message: integrator-ashareid and integrator-envid cannot be combined; send only the one that names the account for this query
+                invalidEnvironment:
+                  summary: integrator-envid is not an environment of this account
+                  value:
+                    errors:
+                      - code: STORAGE_QUERY_INVALID_ENVIRONMENT
+                        message: The requested environment is not available for this account
+                accessRefused:
+                  summary: integrator-ashareid is not a share accepted by the caller
+                  value:
+                    errors:
+                      - code: STORAGE_QUERY_ACCESS_REFUSED
+                        message: Your role, environment or account sharing does not permit this query
         '404':
           description: No job with this id is visible to the caller (`STORAGE_QUERY_JOB_NOT_FOUND`) — unknown, expired, or submitted by another account.
           content:
@@ -575,6 +689,38 @@ components:
     bearerAuth:
       type: http
       scheme: bearer
+  parameters:
+    AShareIdHeader:
+      name: integrator-ashareid
+      in: header
+      required: false
+      description: |-
+        Account share to run the call as. Required when the caller has accepted a share
+        of any account: without it every Storage Query route answers
+        `403 STORAGE_QUERY_ASHARE_HEADER_REQUIRED`. A value that is not a share the caller
+        has accepted answers `403 STORAGE_QUERY_ACCESS_REFUSED`. Cannot be sent together
+        with `integrator-envid`.
+      schema:
+        type: string
+        format: objectId
+        x-celigo-refModel: ashares
+        examples:
+          - 6ab5a7d0c772d334c44701aa
+    EnvIdHeader:
+      name: integrator-envid
+      in: header
+      required: false
+      description: |-
+        Environment of the caller's own account to run the call in. Omit it to use the
+        environment the token belongs to. An id that is malformed or not an environment
+        of the caller's account answers `403 STORAGE_QUERY_INVALID_ENVIRONMENT`. Cannot be
+        sent together with `integrator-ashareid`.
+      schema:
+        type: string
+        format: objectId
+        x-celigo-refModel: environments
+        examples:
+          - 6ab5a7d0c772d334c44701bb
   schemas:
     StorageQueryRequest:
       type: object