@celigo/api-specs 0.2.203 → 0.2.205

package/dist/connection.yml

@@ -1185,7 +1185,9 @@ paths:
         - |-
           Soft-deletes the connection into the recycle bin (restorable for 30 days). Check
           `GET /v1/connections/{_id}/dependencies` first — a connection still referenced by flows,
-          exports, imports, or a borrowing connection is rejected with 422.
+          exports, imports, a borrowing connection, or MCP servers (a tool override, or a
+          `connections[]` entry that requires end-user credentials) is rejected with 422
+          `dependencies_not_deleted`.
   /v1/connections/{_id}/ping:
     get:
       x-internal: false

package/dist/mcp-server.yml

@@ -20,7 +20,7 @@ info:
       - Carries **permission sets** ("Capability Sets" in the UI) — named bundles of its tools, APIs, prompts, and resources granted to end users via `pset:<_id>` capability strings on end-user, group, and role resource grants
       - Carries optional **traffic limits** (`policies[]`) — a server-level rate limit, a per-user rate limit for OAuth end users, and a usage quota — enforced before a tool runs; a rejected call gets HTTP 429 with `Retry-After`
       - Can proxy **upstream MCP servers** (`upstreamMcpConnections[]`, attached through `mcp`-type connections) and whitelist which of their tools, prompts, and resources it exposes
-      - Lists the **connections** its tools run through (`connections[]`) and flags the ones each end user must supply their own credentials for (`requiresEndUserCredentials`)
+      - Lists the **connections** each end user must supply their own credentials for (`connections[]`); only entries with `requiresEndUserCredentials: true` are kept
       - Can be pinned to a **network policy** (`_networkPolicyId`) that restricts which IP ranges may reach it
 servers:
   - url: https://api.integrator.io
@@ -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':
@@ -2466,17 +2468,23 @@ components:
     ServerConnection:
       type: object
       description: |-
-        One connection the server's tools use, with the flag that decides whether
-        each end user must supply their own credentials for it. Connections named
-        here and in `tools[].overrides.connections[]` together form the set that
-        `GET /v1/mcpservers/{_id}/connections` lists.
+        One connection each end user must supply their own credentials for.
+        Connections named here and in `tools[].overrides.connections[]`
+        together form the set that `GET /v1/mcpservers/{_id}/connections` lists.
       x-celigo-ai-guidance:
         - |-
           Reference a live connection owned by this account: an unknown id fails
           with 422 "resource_not_found" and the same connection listed twice with
-          422 "resource_invalid".
+          422 "resource_invalid" — even on an entry sent with the flag false, which
+          is then dropped.
+        - |-
+          A stored entry makes the connection a dependency of the server:
+          DELETE /v1/connections/{_id} fails with 422 "dependencies_not_deleted"
+          ("mcpserver <id> must be deleted before you can delete connection <id>")
+          until a PUT removes the entry or clears its flag.
       required:
         - _connectionId
+        - requiresEndUserCredentials
       properties:
         _connectionId:
           type: string
@@ -2491,14 +2499,15 @@ components:
             - 6ab1ebb94db5688fd8c7189f
         requiresEndUserCredentials:
           type: boolean
-          default: false
           description: |-
             When true, each end user must supply their own values for the fields
             the connection's `endUserProvidedFields` names (through the MCP setup
             page) before calling tools that use it; those values are stored as a
-            per-user `mcpChild` connection. The platform contract is that clearing
-            the flag, or dropping the connection from every server that set it,
-            invalidates the end users' `mcpChild` connections for it.
+            per-user `mcpChild` connection. Only `true` is stored — an entry sent
+            with `false` is dropped on save, so clearing the flag removes the
+            entry. The platform contract is that clearing the flag, or dropping
+            the connection from every server that set it, invalidates the end
+            users' `mcpChild` connections for it.
           examples:
             - true
     Annotations:
@@ -3704,11 +3713,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:
@@ -3719,6 +3723,20 @@ components:
           description: |-
             Connection of type `mcp` that holds the upstream server URL and
             credentials. Each connection can be attached to a server once.
+            When the upstream server rejects a proxied `tools/call`, `prompts/get`,
+            or `resources/read`, the MCP client gets a JSON-RPC error with HTTP
+            status 200: -32008 `Upstream server denied access` for an upstream 403,
+            -32004 `Upstream rate limit exceeded` for a 429, and for a 401 either
+            -32007 `Upstream connection requires re-authorization` or -32603. A
+            `token` or `custom` connection answers -32007. An `oauth` connection
+            first refreshes its token and retries once: -32007 when the connection
+            can't be refreshed (for example, it holds no refresh token), when the
+            token endpoint rejects the grant (for example, with 400), or when the
+            retry is still 401; -32603 when the refresh fails any other way, such
+            as the token endpoint answering 5xx. -32007, -32008, and -32004 carry
+            this id in
+            `error.data._connectionId`; -32603, which an upstream 5xx also answers,
+            carries no `error.data`.
           examples:
             - 6a6655fce52f3c30d0a53926
         alias:
@@ -3728,11 +3746,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 +3762,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:
@@ -4140,13 +4161,17 @@ components:
             - Order Processing Server
         relativeURI:
           type: string
-          maxLength: 131072
+          maxLength: 128
           pattern: ^\/[a-zA-Z0-9_\-]+$
           description: |-
             URI path segment for the MCP server endpoint. Must be unique per account —
             duplicates are rejected with 422 `mcp_server_duplicate_relative_uri`. Only letters,
             numbers, dashes, and underscores after the leading slash (the server's error message
-            also claims colons and dots are allowed, but they are rejected in practice). Creation
+            also claims colons and dots are allowed, but they are rejected in practice). The
+            length limit counts the leading slash; a longer value is rejected with 422
+            `mcp_server_relative_uri_too_long`. `/registry`, `/oidc`, and `/portal`, in any letter
+            case, are reserved for platform endpoints under the account alias and are rejected
+            with 422 `mcp_server_reserved_relative_uri`. PUT applies both checks too. Creation
             also requires the account to have an account alias set (422
             `mcp_server_account_alias_required` otherwise).
           x-celigo-ai-guidance:
@@ -4188,11 +4213,19 @@ components:
         connections:
           type: array
           description: |-
-            Connections the server's tools run through, each flagged for whether
-            end users must supply their own credentials. Always returned — an
-            empty array when none is listed — and cleared when omitted on PUT.
-            Together with `tools[].overrides.connections[]` this is the set
+            Connections each end user must supply their own credentials for. Only
+            entries with `requiresEndUserCredentials: true` are kept — any other
+            entry is validated, then dropped on save. Always returned (an empty
+            array when none is listed) and cleared when omitted on PUT; together
+            with `tools[].overrides.connections[]` it forms the set
             `GET /v1/mcpservers/{_id}/connections` reports.
+          x-celigo-ai-guidance:
+            - |-
+              List a connection here only to make each end user supply their own credentials
+              for it, with requiresEndUserCredentials set to true. A connection the tools run on
+              the account's own credentials needs no entry: an entry sent with the flag false
+              still gets 201/200, but it is absent from the response and from every later
+              GET — do not resend it.
           items:
             $ref: '#/components/schemas/ServerConnection'
         tools:
@@ -4419,9 +4452,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:
@@ -11196,7 +11229,13 @@ components:
           type:
             - string
             - 'null'
-          description: Category of the failure. Null when the request succeeded or was blocked.
+          description: |-
+            Category of the failure. Null when the request succeeded or was blocked.
+            For a proxied request, `authentication` when the upstream connection needs
+            re-authorization (JSON-RPC -32007) or the upstream server denied access
+            (-32008), `rateLimit` when it answered HTTP 429 (-32004), `upstreamError`
+            for another upstream failure such as a 5xx (-32603), and `internal` when an
+            `oauth` connection's token refresh failed (-32603).
           examples:
             - null
         traceId:

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.203",
+  "version": "0.2.205",
   "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": "d2f3a96e",
+		"iasCommit": "c89a0221",
 		"generatedAt": "2026-10-28"
 	},
 	"roots": {
@@ -8332,7 +8332,8 @@
 				"requiresEndUserCredentials": 8
 			},
 			"r": [
-				"_connectionId"
+				"_connectionId",
+				"requiresEndUserCredentials"
 			]
 		},
 		{