@celigo/api-specs 0.2.191 → 0.2.193

package/dist/flow.yml

@@ -2151,12 +2151,17 @@ paths:
         `pathToMany`, `childIndex`, `traceKey`) identify where in the pipeline the record was when it
         failed and how it's structured.
 
-        The `data` field is the record as it reached the failing step — on an HTTP import, before the
-        import's mappings, not the request the import sent. Use `PUT .../{retryDataKey}/data` to mutate
+        The `data` field is the record as the failing stage held it: for an import-stage error
+        (`page_processor_import`) on an HTTP import, the record before the import's mappings, not the
+        request the import sent; for a postResponseMap hook's error (`post_response_mapping`), the record
+        after the step's response mapping. Use `PUT .../{retryDataKey}/data` to mutate
         the snapshot before retrying. Only errors with a `retryDataKey` expose this endpoint;
         connection-class errors are rejected with `no_retrydata_found`. The `stage` field indicates
-        where the retry will resume: `page_processor_import` re-runs the import (most common),
-        `page_generator` means the error was upstream of the processor.
+        where the retry will resume: `page_processor_import` re-runs the import (most common, and where a
+        postSubmit hook's errors are stored, so their retry writes the records again),
+        `post_response_mapping` (a postResponseMap hook's error) resumes after the import from the stored
+        reply in `adaptorResponse`, sending nothing to the destination again and carrying the record on
+        to the flow's next steps, and `page_generator` means the error was upstream of the processor.
       parameters:
         - name: _id
           in: path
@@ -7625,8 +7630,8 @@ components:
         `GET /v1/flows/{_id}/{_stepId}/{retryDataKey}/data` and accepted (full-replace) by the PUT on the
         same path.
 
-        The `data` field carries the record as it reached the failing step, which a retry runs through
-        that step again — its shape is adaptor-specific. The surrounding fields identify where in the
+        The `data` field carries the record as it reached the failing stage, and a retry resumes from
+        that stage (`stage`) — its shape is adaptor-specific. The surrounding fields identify where in the
         pipeline the failure happened and how the record was structured.
       properties:
         retryDataKey:
@@ -7636,16 +7641,28 @@ components:
             - 5f8d43a1b9e5a80011a35f2d-rdk-0
         data:
           description: |-
-            The record as it reached the step. On an HTTP import it is the incoming record, before the
+            The record as the failing stage held it, which depends on `stage`. At `page_processor_import`
+            (an import's errors, a postSubmit hook's included) it is the incoming record, before the
             import's mappings — not the request body the import sent or the response it got back — and a
             retry maps it again with the import's current mappings, so a mapping fix reaches the retried
-            record. Shape varies by adaptor.
+            record. At `post_response_mapping` (a postResponseMap hook's error) it is the record after the
+            step's response mapping, with the mapped fields: a retry neither maps nor sends it again, and
+            the destination's reply is in `adaptorResponse`. Shape varies by adaptor.
           additionalProperties: true
         stage:
           type: string
-          description: Pipeline stage where the record was when the error occurred.
+          description: |-
+            Pipeline stage where the record was when the error occurred, which is where a retry resumes.
+            `page_processor_import` is the record as it entered the import, so a retry sends it to the
+            destination again; a postSubmit hook's errors are stored here, so retrying them writes records
+            the destination already accepted a second time (live, 2026-10-22). `post_response_mapping` is a
+            postResponseMap hook's error, raised after the destination answered: a retry runs the hook from
+            the stored reply and carries the record on to the flow's next steps, sending nothing to that
+            destination again (live, 2026-10-23 and 2026-10-25: the import's request count didn't change,
+            and the next import received the retried records).
           examples:
             - page_processor_import
+            - post_response_mapping
             - importMappingExtract
         pgExportId:
           type: string
@@ -7687,7 +7704,8 @@ components:
           additionalProperties: true
           description: |-
             Adaptor-level response envelope captured alongside the record payload. Present on failures
-            returned by an HTTP or import adaptor; carries fields like `data[]`, `errors[]`,
+            returned by an HTTP or import adaptor, and on a postResponseMap hook's errors, where it is the
+            destination's stored reply (`statusCode`, `id`, `_json`); carries fields like `data[]`, `errors[]`,
             `subGroupIdMapForSuccess`, `resultRecordIds`, `dataURIs`, `groupId`, `recordId`,
             and `ignoredResults`. Treat the shape as opaque — it varies by adaptor — and pass it through
             unchanged when PUT-ing the envelope back.

package/dist/mcp-server.yml

@@ -226,6 +226,118 @@ paths:
           $ref: '#/components/responses/401-unauthorized'
         '422':
           $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/mcpservers/logs/filter-options:
+    get:
+      x-internal: false
+      operationId: getMcpServerRequestLogFilterOptions
+      tags:
+        - MCP Servers
+      summary: Get MCP request log filter options
+      description: |-
+        Returns the filter values to offer for `GET /v1/mcpservers/{_id}/logs`: the JSON-RPC
+        methods to pick from and the closed set of `status` outcomes. The `method` list is not
+        an allow-list — the list operation's `method` filter also takes the underscore form
+        (`tools_call`), methods this endpoint does not list (`initialize`), and an unknown value,
+        which returns an empty page. The options are the same for every MCP server, so this
+        endpoint takes no server id.
+      parameters:
+        - name: type
+          in: query
+          required: false
+          description: Return only one option list. Omit to return both.
+          schema:
+            type: string
+            enum:
+              - method
+              - status
+            x-enumDescriptions:
+              method: Return only the `method` list.
+              status: Return only the `status` list.
+            examples:
+              - method
+      responses:
+        '200':
+          description: Filter values. A list is present when `type` is omitted or names it.
+          content:
+            application/json:
+              schema:
+                type: object
+                description: Filter values by filter name.
+                properties:
+                  method:
+                    type: array
+                    description: |-
+                      JSON-RPC methods to offer for the `method` filter; see the list operation
+                      for every value the filter takes. Present when `type` is omitted or is
+                      `method`.
+                    items:
+                      type: string
+                      enum:
+                        - tools/list
+                        - tools/call
+                        - prompts/list
+                        - prompts/get
+                        - resources/list
+                        - resources/read
+                      x-enumDescriptions:
+                        tools/list: Requests listing the server's tools.
+                        tools/call: Requests running a tool.
+                        prompts/list: Requests listing the server's prompts.
+                        prompts/get: Requests fetching a prompt.
+                        resources/list: Requests listing the server's resources.
+                        resources/read: Requests reading a resource.
+                  status:
+                    type: array
+                    description: |-
+                      Outcomes the `status` filter accepts — a closed set; any other value is
+                      rejected with 422. Present when `type` is omitted or is `status`.
+                    items:
+                      type: string
+                      enum:
+                        - success
+                        - error
+                        - blocked
+                      x-enumDescriptions:
+                        success: Requests that completed without an error.
+                        error: Requests that failed.
+                        blocked: Requests rejected before they ran by a traffic limit, an access or OAuth scope check, or the network policy.
+              examples:
+                default:
+                  value:
+                    method:
+                      - tools/list
+                      - tools/call
+                      - prompts/list
+                      - prompts/get
+                      - resources/list
+                      - resources/read
+                    status:
+                      - success
+                      - error
+                      - blocked
+                status_only:
+                  summary: type=status
+                  value:
+                    status:
+                      - success
+                      - error
+                      - blocked
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '422':
+          description: '`type` is not `method` or `status`.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_type:
+                  value:
+                    errors:
+                      - code: invalid_query_params
+                        message: type is not valid.
   /v1/mcpservers/{_id}:
     get:
       x-internal: false
@@ -1400,28 +1512,490 @@ paths:
                         capabilities:
                           - pset:6a7b8c9d0e1f2a3b4c5d6e7f
         '400':
-          description: |-
-            Validation failed. Pre-flight failures (invalid MCP server id,
-            invalid request body, more than 100 or duplicate `_groupIds`, unknown
-            group ids, capabilities that do not resolve on this server) return a
-            bare `errors` array; a mid-batch failure returns the result body with
-            partial progress plus `errors`.
+          description: |-
+            Validation failed. Pre-flight failures (invalid MCP server id,
+            invalid request body, more than 100 or duplicate `_groupIds`, unknown
+            group ids, capabilities that do not resolve on this server) return a
+            bare `errors` array; a mid-batch failure returns the result body with
+            partial progress plus `errors`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                too_many:
+                  value:
+                    errors:
+                      - code: validation_failed
+                        message: Validation failed. _groupIds cannot exceed 100 entries per request.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          description: MCP server not found in this account.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                server_not_found:
+                  value:
+                    errors:
+                      - code: not_found
+                        message: MCP server not found in this account.
+  /v1/mcpservers/{_id}/logs:
+    get:
+      x-internal: false
+      operationId: listMcpServerRequestLogs
+      tags:
+        - MCP Servers
+      summary: List MCP server request logs
+      description: |-
+        Lists the MCP JSON-RPC requests this server handled, newest first, 50 per page. Follow
+        `nextPageURL` for the next page. Entries are summaries; when `hasPayload` is true, read
+        the stored request and response with `GET /v1/mcpservers/{_id}/logs/{key}`. Requires
+        MCP operations access on the account.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: MCP server ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: mcpservers
+            examples:
+              - 69eb9fb5b4fc023618e490b8
+        - name: time_gt
+          in: query
+          required: false
+          description: Only return requests recorded after this time (exclusive), as epoch milliseconds.
+          schema:
+            type: integer
+            format: int64
+            examples:
+              - 1792700000000
+        - name: time_lte
+          in: query
+          required: false
+          description: Only return requests recorded at or before this time (inclusive), as epoch milliseconds.
+          schema:
+            type: integer
+            format: int64
+            examples:
+              - 1792786400000
+        - name: method
+          in: query
+          required: false
+          description: |-
+            Only return requests with these JSON-RPC methods. Repeat the parameter for several
+            values. Get the values from `GET /v1/mcpservers/logs/filter-options`; the
+            underscore form the listing returns (`tools_call`) is accepted too, and so is a
+            method filter-options does not list but rows carry, such as `initialize`. A value
+            no request carries is not rejected: the page is empty.
+          style: form
+          explode: true
+          schema:
+            type: array
+            items:
+              type: string
+            examples:
+              - - tools/call
+        - name: status
+          in: query
+          required: false
+          description: Only return requests with these outcomes. Repeat the parameter for several values.
+          style: form
+          explode: true
+          schema:
+            type: array
+            items:
+              type: string
+              enum:
+                - success
+                - error
+                - blocked
+              x-enumDescriptions:
+                success: Requests that completed without an error.
+                error: Requests that failed.
+                blocked: Requests rejected before they ran by a traffic limit, an access or OAuth scope check, or the network policy.
+            examples:
+              - - error
+                - blocked
+        - name: entityName
+          in: query
+          required: false
+          description: |-
+            Only return requests that targeted this tool or prompt name, or resource URI.
+            Exact match after trimming whitespace; pass it once.
+          schema:
+            type: string
+            examples:
+              - get_customer
+        - name: nextPageToken
+          in: query
+          required: false
+          description: Continuation token. Follow the `nextPageURL` of the previous page instead of constructing it.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: One page of request summaries.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MCPServerRequestLogsResponse'
+              examples:
+                populated:
+                  value:
+                    requests:
+                      - time: 1792745012345
+                        method: tools_call
+                        status: success
+                        invocationId: a1b2c3d4e5f60718293a4b5c
+                        hasPayload: true
+                        key: 5465373387655-3f2a9c0d1e4b4c6f8a7b9d0e1f2a3b4c-tools_call-S
+                        entityName: get_customer
+                        assetType: IO Tool
+                        entityId: 65a98d1ef2b40000098c3a4d
+                        opStartedAt: 1792745012100
+                        opEndedAt: 1792745012340
+                        authType: apiToken
+                        accessToken:
+                          _id: 66b0c1d2e3f4a5b6c7d8e9f0
+                          name: MCP client token
+                          deleted: false
+                    nextPageURL: /v1/mcpservers/69eb9fb5b4fc023618e490b8/logs?nextPageToken=eyJ0IjoxNzkyNzQ1MDEyMzQ1LCJoIjoiMTIzNDU2Nzg5In0
+                empty:
+                  value:
+                    requests: []
+        '400':
+          description: The MCP server ID is not a valid ObjectId.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_id:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _mcpServerId.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          description: No MCP server with this ID is visible to the caller. Checked before the query parameters.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not_found:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: McpServer not found.
+        '422':
+          description: |-
+            A query parameter is invalid — `time_gt` or `time_lte` is not epoch milliseconds,
+            `status` has an unknown value, `entityName` is repeated, or `nextPageToken` is not a
+            token from `nextPageURL`. The message names the parameter.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_status:
+                  value:
+                    errors:
+                      - code: invalid_query_params
+                        message: status is not valid.
+        '500':
+          description: The request log store could not be queried.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                query_failed:
+                  value:
+                    errors:
+                      - code: clickhouse_error
+                        message: Unable to retrieve the request logs.
+                store_unavailable:
+                  value:
+                    errors:
+                      - code: clickhouse_connection_not_established
+                        message: ClickHouse connection is not established
+  /v1/mcpservers/{_id}/logs/purge:
+    post:
+      x-internal: false
+      operationId: purgeMcpServerRequestLogs
+      tags:
+        - MCP Servers
+      summary: Purge MCP server request log payloads
+      description: |-
+        Permanently deletes the stored request/response payloads of this server's requests
+        recorded between `time_gte` and `time_lte`, both inclusive. The listing rows stay in
+        `GET /v1/mcpservers/{_id}/logs` with `hasPayload` false. Also queues deletion of the run
+        logs of each enabled Tool on the server for the same window; a Tool whose deletion
+        could not be queued is reported in `errors[]` without failing the call. Writes a
+        `purgelogs` audit entry. The window is passed as query parameters; a request body is
+        ignored. Up to 10,000 payloads per call — narrow the window when the range holds more.
+        Requires MCP operations access on the account.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: MCP server ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: mcpservers
+            examples:
+              - 69eb9fb5b4fc023618e490b8
+        - name: time_gte
+          in: query
+          required: true
+          description: Start of the window (inclusive), as an ISO 8601 date-time. Epoch milliseconds are rejected.
+          schema:
+            type: string
+            format: date-time
+            examples:
+              - '2026-10-01T00:00:00Z'
+        - name: time_lte
+          in: query
+          required: true
+          description: End of the window (inclusive), as an ISO 8601 date-time. Must not be before `time_gte` or in the future.
+          schema:
+            type: string
+            format: date-time
+            examples:
+              - '2026-10-22T23:59:59Z'
+      responses:
+        '200':
+          description: Purge outcome. `purged` is empty when the window held no stored payloads.
+          content:
+            application/json:
+              schema:
+                type: object
+                description: Purge result envelope.
+                required:
+                  - purged
+                  - errors
+                properties:
+                  purged:
+                    type: array
+                    description: Log keys whose payloads were deleted.
+                    items:
+                      type: string
+                  errors:
+                    type: array
+                    description: Tools whose run-log deletion could not be queued. Empty when every Tool was queued.
+                    items:
+                      type: object
+                      required:
+                        - code
+                        - message
+                        - _toolId
+                      properties:
+                        code:
+                          type: string
+                          description: Always `tool_log_purge_failed`.
+                          examples:
+                            - tool_log_purge_failed
+                        message:
+                          type: string
+                          description: Human-readable description of the failure.
+                          examples:
+                            - Unable to queue Tool Builder log deletion for the selected range.
+                        _toolId:
+                          type: string
+                          format: objectId
+                          x-celigo-refModel: tools
+                          description: Tool whose run logs were not queued for deletion. Retrying the purge with the same window queues it again.
+                          examples:
+                            - 65a98d1ef2b40000098c3a4d
+              examples:
+                default:
+                  value:
+                    purged:
+                      - 5465373387655-3f2a9c0d1e4b4c6f8a7b9d0e1f2a3b4c-tools_call-S
+                    errors: []
+                tool_cascade_failed:
+                  summary: Payloads purged, one Tool not queued
+                  value:
+                    purged:
+                      - 5465373387655-3f2a9c0d1e4b4c6f8a7b9d0e1f2a3b4c-tools_call-S
+                    errors:
+                      - code: tool_log_purge_failed
+                        message: Unable to queue Tool Builder log deletion for the selected range.
+                        _toolId: 65a98d1ef2b40000098c3a4d
+        '400':
+          description: |-
+            Invalid request, checked in this order — the MCP server ID is not a valid ObjectId;
+            `time_gte` or `time_lte` is missing or not a date-time (the message names the
+            parameter); the window is reversed or ends in the future;
+            or, after the server is found, the window holds more than 10,000 payloads.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_id:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _mcpServerId.
+                missing_time_gte:
+                  value:
+                    errors:
+                      - code: invalid_query_params
+                        message: time_gte is not valid.
+                invalid_range:
+                  value:
+                    errors:
+                      - code: invalid_query_params
+                        message: time_gte and time_lte must be valid ISO datetimes, a non-future window, with time_gte <= time_lte.
+                range_too_large:
+                  value:
+                    errors:
+                      - code: invalid_request
+                        message: The selected range contains too many request logs to purge in one call. Narrow the date range.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          description: No MCP server with this ID is visible to the caller. Checked after the time window.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not_found:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: McpServer not found.
+        '500':
+          description: |-
+            The request log store could not be queried, or payload deletion failed partway.
+            Payloads deleted before the failure stay deleted; retry the same window.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                purge_failed:
+                  value:
+                    errors:
+                      - code: log_purge_failed
+                        message: Unable to purge the request log.
+                query_failed:
+                  value:
+                    errors:
+                      - code: clickhouse_error
+                        message: Unable to retrieve the request logs.
+  /v1/mcpservers/{_id}/logs/{key}:
+    get:
+      x-internal: false
+      operationId: getMcpServerRequestLog
+      tags:
+        - MCP Servers
+      summary: Get an MCP server request log
+      description: |-
+        Returns the stored request and response for one MCP request, looked up by a `key` from
+        `GET /v1/mcpservers/{_id}/logs`. Only entries with `hasPayload` true have a key. A key
+        whose payload was purged, a key that names no stored payload, and a malformed key all
+        answer `422` `log_file_unavailable`. The stored `Authorization` request header is
+        masked. Requires MCP operations access on the account.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: MCP server ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: mcpservers
+            examples:
+              - 69eb9fb5b4fc023618e490b8
+        - name: key
+          in: path
+          required: true
+          description: Log key from the `GET /v1/mcpservers/{_id}/logs` listing, used exactly as returned.
+          schema:
+            type: string
+            examples:
+              - 5465373387655-3f2a9c0d1e4b4c6f8a7b9d0e1f2a3b4c-tools_call-S
+      responses:
+        '200':
+          description: The stored record with the fields decoded from `key` added.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MCPServerRequestLogDetail'
+              examples:
+                default:
+                  value:
+                    key: 5465373387655-3f2a9c0d1e4b4c6f8a7b9d0e1f2a3b4c-tools_call-S
+                    id: 3f2a9c0d1e4b4c6f8a7b9d0e1f2a3b4c
+                    time: 1792745012345
+                    method: tools_call
+                    status: success
+                    request:
+                      headers:
+                        content-type: application/json
+                        authorization: Bearer ********
+                      body: '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"get_customer","arguments":{"customerId":"C-1042"}}}'
+                      httpVersion: '1.1'
+                      url: /customer-integration
+                      clientAddress: 203.0.113.7
+                      size: 234
+                    response:
+                      body: '{"jsonrpc":"2.0","id":7,"result":{"content":[{"type":"text","text":"{\"customerId\":\"C-1042\"}"}]}}'
+                      headers:
+                        content-type: application/json
+                      size: 196
+                    entityName: get_customer
+                    assetType: IO Tool
+                    _byUserId: 624774a6a7574d3ed9f9a5cc
+                    _accessTokenId: 66b0c1d2e3f4a5b6c7d8e9f0
+                    _agentId: null
+                    clientName: null
+                    clientVersion: null
+                    sourceType: celigo
+                    upstreamHost: null
+                    _connectionId: null
+                    authMode: null
+                    upstreamMs: null
+                    errorCategory: null
+                    traceId: 7f9c2e1a4b3d4c5e
+                    purgeAt: 1795337012345
+        '400':
+          description: The MCP server ID is not a valid ObjectId.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
               examples:
-                too_many:
+                invalid_id:
                   value:
                     errors:
-                      - code: validation_failed
-                        message: Validation failed. _groupIds cannot exceed 100 entries per request.
+                      - code: invalid_ref
+                        message: Please provide a valid _mcpServerId.
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '403':
           $ref: '#/components/responses/403-forbidden'
         '404':
-          description: MCP server not found in this account.
+          description: |-
+            No MCP server with this ID is visible to the caller. A key with no stored payload is a
+            `422`, not a `404`.
           content:
             application/json:
               schema:
@@ -1430,8 +2004,40 @@ paths:
                 server_not_found:
                   value:
                     errors:
-                      - code: not_found
-                        message: MCP server not found in this account.
+                      - code: invalid_ref
+                        message: McpServer not found.
+        '422':
+          description: |-
+            The stored payload could not be read (`log_file_unavailable` — the answer for a purged
+            key, a key that names no stored payload, and a malformed key), or could not be parsed
+            (`invalid_log_file`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                unavailable:
+                  value:
+                    errors:
+                      - code: log_file_unavailable
+                        message: Unable to retrieve the log file.
+                unparseable:
+                  value:
+                    errors:
+                      - code: invalid_log_file
+                        message: Unable to parse. Masked secret keys can cause parsing errors, update the access token or private field to view the data.
+        '500':
+          description: The request log store could not be queried while locating the payload.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                query_failed:
+                  value:
+                    errors:
+                      - code: clickhouse_error
+                        message: Unable to retrieve the request logs.
 components:
   securitySchemes:
     bearerAuth:
@@ -9676,6 +10282,435 @@ components:
               message:
                 type: string
                 description: Human-readable error message.
+    MCPServerRequestLogEntry:
+      type: object
+      description: |-
+        Summary row in the `GET /v1/mcpservers/{_id}/logs` listing — one MCP JSON-RPC request
+        the server handled. The stored request/response payload is only on
+        `GET /v1/mcpservers/{_id}/logs/{key}`, and only when `hasPayload` is true.
+      required:
+        - time
+        - method
+        - status
+        - invocationId
+        - hasPayload
+        - entityName
+        - assetType
+        - entityId
+        - opStartedAt
+        - opEndedAt
+        - authType
+      properties:
+        time:
+          type: integer
+          format: int64
+          description: Epoch milliseconds when the request was recorded. The listing is sorted on this value, newest first.
+          examples:
+            - 1792745012345
+        method:
+          type:
+            - string
+            - 'null'
+          description: |-
+            JSON-RPC method of the request, with `/` replaced by `_` (`tools_call`,
+            `resources_read`). A JSON-RPC batch is recorded as one row with method `batch`.
+          examples:
+            - tools_call
+        status:
+          type: string
+          enum:
+            - success
+            - error
+            - blocked
+          x-enumDescriptions:
+            success: The request completed without an error.
+            error: The request failed.
+            blocked: The request was rejected before it ran by a traffic limit, an access or OAuth scope check, or the network policy.
+          description: Outcome of the request. Filter on it with the `status` query parameter.
+          examples:
+            - success
+        invocationId:
+          type: string
+          description: |-
+            Invocation id of the downstream tool run that served a `tools/call`. Empty string
+            when the request produced no downstream invocation.
+          examples:
+            - ''
+            - a1b2c3d4e5f60718293a4b5c
+        hasPayload:
+          type: boolean
+          description: |-
+            When true, the request/response payload is stored and `key` is set; read it with
+            `GET /v1/mcpservers/{_id}/logs/{key}`. False when the payload was never stored (the
+            server's logging mode skipped it) or has been purged.
+          examples:
+            - true
+        key:
+          type: string
+          description: |-
+            Opaque log key. Pass it to `GET /v1/mcpservers/{_id}/logs/{key}`; use it exactly as
+            returned. Present when `hasPayload` is true.
+          examples:
+            - 5465373387655-3f2a9c0d1e4b4c6f8a7b9d0e1f2a3b4c-tools_call-S
+        entityName:
+          type:
+            - string
+            - 'null'
+          description: |-
+            Capability the request targeted — the tool or prompt name for `tools/call` and
+            `prompts/get`, or the resource URI for `resources/read`. Null for list methods.
+          examples:
+            - get_customer
+        assetType:
+          type:
+            - string
+            - 'null'
+          enum:
+            - IO Tool
+            - API
+            - Prompt
+            - Resource
+            - null
+          x-enumDescriptions:
+            IO Tool: A `tools/call` served by a Celigo Tool.
+            API: A `tools/call` served by a builder-mode API.
+            Prompt: A `prompts/get` request.
+            Resource: A `resources/read` request.
+          description: |-
+            Kind of capability the request reached. Null for list methods and for tools
+            proxied from an upstream MCP server.
+          examples:
+            - IO Tool
+        entityId:
+          type:
+            - string
+            - 'null'
+          description: |-
+            Identifies the Tool (`assetType` `IO Tool`) or builder-mode API (`assetType` `API`)
+            that served a `tools/call`. Null otherwise.
+          examples:
+            - 65a98d1ef2b40000098c3a4d
+        opStartedAt:
+          type:
+            - integer
+            - 'null'
+          format: int64
+          description: Epoch milliseconds when the operation started. Null when not recorded.
+          examples:
+            - 1792745012100
+        opEndedAt:
+          type:
+            - integer
+            - 'null'
+          format: int64
+          description: Epoch milliseconds when the operation ended. Null when not recorded.
+          examples:
+            - 1792745012340
+        authType:
+          type:
+            - string
+            - 'null'
+          enum:
+            - oauth
+            - apiToken
+            - null
+          x-enumDescriptions:
+            oauth: The caller authenticated with an MCP OAuth token.
+            apiToken: The caller authenticated with an API token.
+          description: How the MCP client authenticated. Null when neither applies.
+          examples:
+            - apiToken
+        byUser:
+          type: object
+          description: User who made the request. Present when set.
+          required:
+            - _id
+            - name
+            - email
+            - deleted
+          properties:
+            _id:
+              type: string
+              format: objectId
+              x-celigo-refModel: users
+              description: User who made the request.
+              examples:
+                - 624774a6a7574d3ed9f9a5cc
+            name:
+              type:
+                - string
+                - 'null'
+              description: Display name of the user. Null when the user record is gone or has no name.
+              examples:
+                - Jane Doe
+            email:
+              type:
+                - string
+                - 'null'
+              description: Email of the user. Null when the user record is gone.
+              examples:
+                - jane.doe@example.com
+            deleted:
+              type: boolean
+              description: When true, the user has been deleted or could not be found.
+              examples:
+                - false
+        accessToken:
+          type: object
+          description: API token the request authenticated with. Present when set.
+          required:
+            - _id
+            - name
+            - deleted
+          properties:
+            _id:
+              type: string
+              format: objectId
+              x-celigo-refModel: accesstokens
+              description: API token the request authenticated with.
+              examples:
+                - 66b0c1d2e3f4a5b6c7d8e9f0
+            name:
+              type:
+                - string
+                - 'null'
+              description: Name of the token. Null when the token record is gone or has no name.
+              examples:
+                - MCP client token
+            deleted:
+              type: boolean
+              description: When true, the token has been deleted or could not be found.
+              examples:
+                - false
+    MCPServerRequestLogsResponse:
+      type: object
+      description: |-
+        Envelope returned by `GET /v1/mcpservers/{_id}/logs`. Each page holds at most 50
+        entries; `requests[]` is empty when no request matches.
+      required:
+        - requests
+      properties:
+        requests:
+          type: array
+          description: Request summaries, newest first.
+          items:
+            $ref: '#/components/schemas/MCPServerRequestLogEntry'
+        nextPageURL:
+          type: string
+          description: |-
+            Relative URL of the next page, repeating the current filters with a continuation
+            token. Present when more entries remain. Follow it as returned; do not construct it.
+          examples:
+            - /v1/mcpservers/69eb9fb5b4fc023618e490b8/logs?status=error&nextPageToken=eyJ0IjoxNzkyNzQ1MDEyMzQ1LCJoIjoiMTIzNDU2Nzg5In0
+    MCPServerRequestLogDetail:
+      type: object
+      description: |-
+        Stored request/response payload for one MCP request, returned by
+        `GET /v1/mcpservers/{_id}/logs/{key}`. The stored record is returned as-is with `key`,
+        `id`, `time`, `method`, and `status` decoded from the log key. Records written by older
+        releases may lack some of the other fields.
+      required:
+        - key
+        - id
+        - time
+        - method
+        - status
+      properties:
+        key:
+          type: string
+          description: Echoes the `key` path parameter.
+          examples:
+            - 5465373387655-3f2a9c0d1e4b4c6f8a7b9d0e1f2a3b4c-tools_call-S
+        id:
+          type: string
+          description: Storage id of this record — the second segment of `key`.
+          examples:
+            - 3f2a9c0d1e4b4c6f8a7b9d0e1f2a3b4c
+        time:
+          type: integer
+          format: int64
+          description: Epoch milliseconds when the request was recorded, decoded from `key`.
+          examples:
+            - 1792745012345
+        method:
+          type: string
+          description: JSON-RPC method with `/` replaced by `_`, decoded from `key`.
+          examples:
+            - tools_call
+        status:
+          type: string
+          enum:
+            - success
+            - error
+            - blocked
+          x-enumDescriptions:
+            success: The request completed without an error.
+            error: The request failed.
+            blocked: The request was rejected before it ran by a traffic limit, an access or OAuth scope check, or the network policy.
+          description: Outcome of the request, decoded from `key`. Same values as the listing's `status`.
+          examples:
+            - success
+        request:
+          type: object
+          description: |-
+            Inbound HTTP request as stored — `headers` (the `Authorization` value masked), `body`
+            (the JSON-RPC body as a string), `httpVersion`, `url`, `clientAddress`, and `size`.
+          additionalProperties: true
+        response:
+          type: object
+          description: Response the MCP server sent as stored — `body` (a string), `headers`, and `size`.
+          additionalProperties: true
+        entityName:
+          type:
+            - string
+            - 'null'
+          description: Tool or prompt name, or resource URI, the request targeted. Null for list methods.
+          examples:
+            - get_customer
+        assetType:
+          type:
+            - string
+            - 'null'
+          enum:
+            - IO Tool
+            - API
+            - Prompt
+            - Resource
+            - null
+          x-enumDescriptions:
+            IO Tool: A `tools/call` served by a Celigo Tool.
+            API: A `tools/call` served by a builder-mode API.
+            Prompt: A `prompts/get` request.
+            Resource: A `resources/read` request.
+          description: Kind of capability the request reached. Same values as the listing's `assetType`.
+          examples:
+            - IO Tool
+        _byUserId:
+          type:
+            - string
+            - 'null'
+          format: objectId
+          x-celigo-refModel: users
+          description: |-
+            User who made the request. Unlike the listing, the detail returns the raw id
+            without name or email.
+          examples:
+            - 624774a6a7574d3ed9f9a5cc
+        _accessTokenId:
+          type:
+            - string
+            - 'null'
+          format: objectId
+          x-celigo-refModel: accesstokens
+          description: API token the request authenticated with. Null for other authentication types.
+          examples:
+            - 66b0c1d2e3f4a5b6c7d8e9f0
+        _agentId:
+          type:
+            - string
+            - 'null'
+          description: |-
+            Celigo agent the MCP client identified itself as with the `x-celigo-agent-id` request
+            header. Null when the request carried none.
+          examples:
+            - null
+        clientName:
+          type:
+            - string
+            - 'null'
+          description: Name the MCP client reported in an `initialize` request. Null for other methods.
+          examples:
+            - claude-desktop
+        clientVersion:
+          type:
+            - string
+            - 'null'
+          description: Version the MCP client reported in an `initialize` request. Null for other methods.
+          examples:
+            - 1.4.2
+        sourceType:
+          type:
+            - string
+            - 'null'
+          enum:
+            - celigo
+            - upstream
+            - null
+          x-enumDescriptions:
+            celigo: The capability is served by Celigo.
+            upstream: The capability is proxied from an upstream MCP server.
+          description: Where the targeted capability is served from. Null when it could not be determined.
+          examples:
+            - celigo
+        upstreamHost:
+          type:
+            - string
+            - 'null'
+          description: Host of the upstream MCP server the request was proxied to. Null when the request was not proxied.
+          examples:
+            - null
+        _connectionId:
+          type:
+            - string
+            - 'null'
+          format: objectId
+          x-celigo-refModel: connections
+          description: |-
+            `mcp`-type connection the request was proxied through. Null when the request was not
+            proxied.
+          examples:
+            - null
+        authMode:
+          type:
+            - string
+            - 'null'
+          enum:
+            - parent
+            - null
+          x-enumDescriptions:
+            parent: The request was proxied to the upstream MCP server with the server's own connection credentials.
+          description: How a proxied request authenticated upstream. Null when the request was not proxied.
+          examples:
+            - null
+        upstreamMs:
+          type:
+            - integer
+            - 'null'
+          description: Latency of the hop to the upstream MCP server, in milliseconds. Null when the request was not proxied.
+          examples:
+            - null
+        errorCategory:
+          type:
+            - string
+            - 'null'
+          description: Category of the failure. Null when the request succeeded or was blocked.
+          examples:
+            - null
+        traceId:
+          type:
+            - string
+            - 'null'
+          description: Trace id of the request for cross-service correlation.
+          examples:
+            - 7f9c2e1a4b3d4c5e
+        purgeAt:
+          type:
+            - integer
+            - 'null'
+          format: int64
+          description: Epoch milliseconds when this record expires under the account's data retention period.
+          examples:
+            - 1795337012345
+        limitType:
+          type:
+            - string
+            - 'null'
+          description: Traffic limit that rejected the request. Present when a traffic limit blocked it.
+        denial:
+          type: object
+          description: Details of the access check that rejected the request. Present when an access check blocked it.
+          additionalProperties: true
+      additionalProperties: true
   responses:
     401-unauthorized:
       description: |-
@@ -9737,9 +10772,9 @@ components:
                 errors:
                   - code: unprocessable_entity
                     message: The request could not be processed due to a semantic error.
-    404-not-found:
+    403-forbidden:
       description: |
-        Not found. The requested resource does not exist or is not visible to the caller.
+        Forbidden. The authenticated caller does not have permission to perform this operation.
       content:
         application/json:
           schema:
@@ -9748,11 +10783,11 @@ components:
             default:
               value:
                 errors:
-                  - code: not_found
-                    message: The requested resource was not found.
-    403-forbidden:
+                  - code: forbidden
+                    message: You do not have permission to access this resource.
+    404-not-found:
       description: |
-        Forbidden. The authenticated caller does not have permission to perform this operation.
+        Not found. The requested resource does not exist or is not visible to the caller.
       content:
         application/json:
           schema:
@@ -9761,7 +10796,7 @@ components:
             default:
               value:
                 errors:
-                  - code: forbidden
-                    message: You do not have permission to access this resource.
+                  - code: not_found
+                    message: The requested resource was not found.
 x-enable-proxy: true
 x-internal: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.191",
+  "version": "0.2.193",
   "private": false,
   "description": "Public OpenAPI bundles (dist/) and the celigo-cli lint schema pack (schemas.json).",
   "keywords": [

package/schemas.json

@@ -1,8 +1,8 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "1cd90c84",
-		"generatedAt": "2026-10-25"
+		"iasCommit": "9ea51d4f",
+		"generatedAt": "2026-10-26"
 	},
 	"roots": {
 		"aiagent": 128,