@celigo/api-specs 0.2.20 → 0.2.21

package/dist/tool.yml

@@ -382,6 +382,86 @@ paths:
         - |-
           Updates an existing tool with the provided configuration.
           This is used for major updates to a tool's structure or behavior.
+    patch:
+      x-internal: false
+      summary: Patch a tool
+      description: |-
+        Partially updates a tool using a JSON Patch document (RFC 6902).
+        The `add`, `remove`, `replace`, and `move` operations are supported
+        (`copy` and `test` are rejected), and only on the following whitelisted
+        paths:
+
+        | Path | Description |
+        |------|-------------|
+        | `/name` | Tool display name |
+        | `/description` | Tool description |
+        | `/aiDescription` | AI-generated description object |
+        | `/input/debugUntil` | Tool Input debug capture expiry (ISO-8601, at most 1 hour in the future; 422 beyond the cap) |
+        | `/output/debugUntil` | Tool Output debug capture expiry (ISO-8601, at most 1 hour in the future; 422 beyond the cap) |
+
+        All other paths are rejected with 422 (`not a whitelisted property`).
+
+        PATCH is the intended way to update these fields without accidentally
+        resetting other tool configuration via `PUT`. In particular, it is how
+        you arm and disarm step debug capture: `replace` `/input/debugUntil` or
+        `/output/debugUntil` with a future ISO timestamp to start capturing, or
+        a past timestamp to stop. While armed, captured logs are readable at
+        `GET /v1/tools/{_id}/tool_input/requests` and
+        `GET /v1/tools/{_id}/tool_output/requests`.
+      operationId: patchTool
+      tags:
+        - Tools
+      parameters:
+        - name: _id
+          in: path
+          description: The unique identifier of the tool
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: tools
+            examples:
+              - 69d462d5b9c28ea0b7f82522
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/JsonPatchRequest'
+            examples:
+              rename:
+                summary: Rename a tool
+                value:
+                  - op: replace
+                    path: /name
+                    value: Updated Tool Name
+              update_description:
+                summary: Update tool description
+                value:
+                  - op: replace
+                    path: /description
+                    value: Updated tool description
+              arm_input_debug:
+                summary: Arm input debug capture for 30 minutes
+                value:
+                  - op: replace
+                    path: /input/debugUntil
+                    value: '2026-08-25T12:30:00.000Z'
+              disarm_output_debug:
+                summary: Disarm output debug capture
+                value:
+                  - op: replace
+                    path: /output/debugUntil
+                    value: '2020-01-01T00:00:00.000Z'
+      responses:
+        '204':
+          description: Tool patched successfully.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
     delete:
       x-internal: false
       summary: Delete a tool
@@ -1348,12 +1428,20 @@ paths:
       summary: List captured debug requests for a tool step
       description: |-
         Lists the debug request records captured for a specific step of a tool.
-        These are the raw outbound requests the step issued, retained for
-        troubleshooting. Use the `key` of an entry with
-        `GET /v1/tools/{_id}/{_stepId}/requests/{key}` to fetch the full detail
-        of a single captured request.
+        These are the raw request/response payloads the step processed, retained
+        for troubleshooting while debug capture is active for the step. Use the
+        `key` of an entry with `GET /v1/tools/{_id}/{_stepId}/requests/{key}` to
+        fetch the full detail of a single captured request.
+
+        When more records match than fit in one page, `nextPageURL` returns the
+        relative URL for the next page.
 
-        Returns `{requests: []}` when the step has captured no debug requests.
+        **Important:** Time parameters (`time_lte`, `time_gt`) must be epoch
+        milliseconds (integers), not ISO 8601 strings. When `time_lte` is
+        provided, `time_gt` is also required.
+
+        Requires the `manage:tool:logs` permission. Returns `{requests: []}` when
+        the step has captured no debug requests.
       operationId: listToolStepRequests
       tags:
         - Tools
@@ -1372,14 +1460,91 @@ paths:
           in: path
           required: true
           description: |-
-            Export or import step id whose captured debug requests you want. Must be a
-            step ObjectId — reserved path segments such as `invocations`, `invoke`, and
-            `test` are not valid step ids.
+            The step whose captured logs to list. Either the ObjectId of an
+            export or import step defined directly in this tool's routers, or one
+            of the virtual step ids `tool_input` / `tool_output` (logs captured
+            via `input.debugUntil` / `output.debugUntil`). Steps nested inside a
+            child tool are addressed on that child tool's id. Reserved path
+            segments such as `invocations`, `invoke`, and `test` are not valid
+            step ids.
           schema:
             type: string
-            format: objectId
             examples:
               - 67ee026136f4d1eeb529ad63
+              - tool_input
+              - tool_output
+        - name: time_gt
+          in: query
+          required: false
+          description: |-
+            Lower bound of the time window (exclusive), as epoch milliseconds.
+            Required when `time_lte` is provided.
+          schema:
+            type: integer
+            format: int64
+            examples:
+              - 1776917000000
+        - name: time_lte
+          in: query
+          required: false
+          description: |-
+            Upper bound of the time window (inclusive), as epoch milliseconds.
+            Defaults to now if omitted. When provided, `time_gt` is also required.
+          schema:
+            type: integer
+            format: int64
+            examples:
+              - 1776917346304
+        - name: method
+          in: query
+          required: false
+          description: |-
+            Only return records with these HTTP methods. Repeat the parameter to
+            filter on multiple values.
+          style: form
+          explode: true
+          schema:
+            type: array
+            items:
+              type: string
+            examples:
+              - - POST
+                - GET
+        - name: statusCode
+          in: query
+          required: false
+          description: |-
+            Only return records with these response status codes. Repeat the
+            parameter to filter on multiple values.
+          style: form
+          explode: true
+          schema:
+            type: array
+            items:
+              type: string
+            examples:
+              - - '200'
+                - '422'
+        - name: stage
+          in: query
+          required: false
+          description: |-
+            Only return records for these processing stages. Repeat the parameter
+            to filter on multiple values.
+          style: form
+          explode: true
+          schema:
+            type: array
+            items:
+              type: string
+        - name: nextPageToken
+          in: query
+          required: false
+          description: |-
+            Continuation token for pagination. Do not construct this manually —
+            follow the `nextPageURL` returned by the previous page instead.
+          schema:
+            type: string
       responses:
         '200':
           description: |-
@@ -1396,7 +1561,31 @@ paths:
                     description: Captured debug request records.
                     items:
                       type: object
+                      description: Summary of one captured debug request.
+                      properties:
+                        key:
+                          type: string
+                          description: |-
+                            Identifier of the captured record; pass it to
+                            `GET /v1/tools/{_id}/{_stepId}/requests/{key}`.
+                        time:
+                          type: integer
+                          description: Capture time as epoch milliseconds.
+                        method:
+                          type: string
+                          description: HTTP method of the captured request.
+                        statusCode:
+                          type: string
+                          description: Response status code of the captured request.
+                        stage:
+                          type: string
+                          description: Processing stage the record was captured in.
                       additionalProperties: true
+                  nextPageURL:
+                    type: string
+                    description: |-
+                      Relative URL of the next page. Present only when more
+                      records match than were returned.
                 required:
                   - requests
               examples:
@@ -1404,8 +1593,148 @@ paths:
                   summary: No debug requests captured
                   value:
                     requests: []
+                populated:
+                  summary: Captured debug requests for a tool step
+                  value:
+                    requests:
+                      - key: 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST
+                        time: 1776917346304
+                        method: POST
+                        statusCode: '200'
         '401':
           $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          description: 'Invalid time filter parameters. Error code: `invalid_or_missing_field`.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_time:
+                  value:
+                    errors:
+                      - code: invalid_or_missing_field
+                        message: time_lte must be an epoch millisecond value, not an ISO string.
+                missing_time_gt:
+                  value:
+                    errors:
+                      - code: invalid_or_missing_field
+                        message: 'Invalid or Missing Field: time_gt'
+    delete:
+      x-internal: false
+      summary: Delete captured debug requests for a tool step
+      description: |-
+        Deletes captured debug request records for a specific step of a tool, by
+        their `key` values from `GET /v1/tools/{_id}/{_stepId}/requests`. Between
+        1 and 1000 keys can be deleted per call.
+
+        The response lists the keys that were deleted and, separately, any keys
+        that failed to delete along with the failure reason.
+
+        Requires the `manage:tool:logs:deletion` permission.
+      operationId: deleteToolStepRequests
+      tags:
+        - Tools
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: The unique identifier of the tool.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: tools
+            examples:
+              - 69d462d5b9c28ea0b7f82522
+        - name: _stepId
+          in: path
+          required: true
+          description: |-
+            The step whose captured logs to delete. Either the ObjectId of an
+            export or import step defined directly in this tool's routers, or one
+            of the virtual step ids `tool_input` / `tool_output` (logs captured
+            via `input.debugUntil` / `output.debugUntil`).
+          schema:
+            type: string
+            examples:
+              - 67ee026136f4d1eeb529ad63
+              - tool_input
+              - tool_output
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              description: Keys of the captured debug requests to delete.
+              properties:
+                keys:
+                  type: array
+                  description: |-
+                    Keys of the records to delete, from the
+                    `GET /v1/tools/{_id}/{_stepId}/requests` listing.
+                  minItems: 1
+                  maxItems: 1000
+                  items:
+                    type: string
+              required:
+                - keys
+            examples:
+              default:
+                summary: Delete two captured debug requests
+                value:
+                  keys:
+                    - 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST
+                    - 5481201048878-b21bf2bef9ff588b958882d2f4827f47-422-POST
+      responses:
+        '200':
+          description: |-
+            Deletion outcome. `deleted` lists the removed keys; `errors` lists
+            keys that could not be removed with the failure reason.
+          content:
+            application/json:
+              schema:
+                type: object
+                description: Deletion result envelope.
+                properties:
+                  deleted:
+                    type: array
+                    description: Keys of the records that were deleted.
+                    items:
+                      type: string
+                  errors:
+                    type: array
+                    description: Records that failed to delete.
+                    items:
+                      type: object
+                      properties:
+                        key:
+                          type: string
+                          description: Key of the record that failed to delete.
+                        error:
+                          type: string
+                          description: Failure reason.
+                required:
+                  - deleted
+                  - errors
+              examples:
+                default:
+                  summary: All requested records deleted
+                  value:
+                    deleted:
+                      - 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST
+                      - 5481201048878-b21bf2bef9ff588b958882d2f4827f47-422-POST
+                    errors: []
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
         '404':
           $ref: '#/components/responses/404-not-found'
   /v1/tools/{_id}/{_stepId}/requests/{key}:
@@ -1416,6 +1745,14 @@ paths:
         Returns the full detail of a single captured debug request for a tool
         step, identified by its `key`. Obtain the `key` from
         `GET /v1/tools/{_id}/{_stepId}/requests`.
+
+        The record carries the captured request/response payloads for the step,
+        plus the `key`, record `id`, and capture `time`. For `tool_input`,
+        `tool_output`, and ToolImport steps the stored body is the in-memory JSON
+        record (not adaptor-masked). Router Import/Export bubbles keep existing
+        adaptor masking.
+
+        Requires the `manage:tool:logs` permission.
       operationId: getToolStepRequest
       tags:
         - Tools
@@ -1434,14 +1771,19 @@ paths:
           in: path
           required: true
           description: |-
-            Export or import step id the captured request belongs to. Must be a step
-            ObjectId — reserved path segments such as `invocations`, `invoke`, and
-            `test` are not valid step ids.
+            The step the captured request belongs to. Either the ObjectId of an
+            export or import step defined directly in this tool's routers, or one
+            of the virtual step ids `tool_input` / `tool_output` (logs captured
+            via `input.debugUntil` / `output.debugUntil`). Steps nested inside a
+            child tool are addressed on that child tool's id. Reserved path
+            segments such as `invocations`, `invoke`, and `test` are not valid
+            step ids.
           schema:
             type: string
-            format: objectId
             examples:
               - 67ee026136f4d1eeb529ad63
+              - tool_input
+              - tool_output
         - name: key
           in: path
           required: true
@@ -1457,18 +1799,131 @@ paths:
             application/json:
               schema:
                 type: object
-                description: A single captured debug request record.
+                description: |-
+                  A single captured debug request record, including the captured
+                  request/response payloads.
+                properties:
+                  key:
+                    type: string
+                    description: Echoes the `key` path parameter.
+                  id:
+                    type: string
+                    description: Internal storage id parsed from the log filename.
+                  time:
+                    type: integer
+                    format: int64
+                    description: Epoch milliseconds when this pair was stored.
+                  request:
+                    type: object
+                    description: |-
+                      The captured request envelope. Synthetic `tool_input` /
+                      `tool_output` / ToolImport logs store the in-memory JSON
+                      record; router Import/Export bubbles store the adaptor HTTP
+                      request.
+                    properties:
+                      method:
+                        type: string
+                        description: HTTP method (`GET`, `POST`, …). Synthetic captures use `POST`.
+                        examples:
+                          - POST
+                      url:
+                        type: string
+                        description: |-
+                          Fully-resolved URL sent. Present on adaptor HTTP
+                          captures; omitted on synthetic `tool_input` /
+                          `tool_output` / ToolImport logs.
+                      headers:
+                        type: object
+                        description: |-
+                          Headers sent with the request. Adaptor HTTP captures
+                          mask credentials; synthetic captures have no adaptor
+                          masking.
+                        additionalProperties: true
+                      body:
+                        description: |-
+                          Captured request payload. Object for synthetic
+                          `tool_input` / `tool_output` / ToolImport logs (the
+                          in-memory JSON record). String for adaptor HTTP
+                          router-bubble captures.
+                  response:
+                    type: object
+                    description: The captured response envelope.
+                    properties:
+                      statusCode:
+                        type: integer
+                        description: HTTP status code (`200` on success, `422` on schema/transform failure for synthetic captures).
+                        examples:
+                          - 200
+                      headers:
+                        type: object
+                        description: Response headers. Empty object on synthetic captures that did not issue HTTP.
+                        additionalProperties: true
+                      body:
+                        description: |-
+                          Captured response payload. Object for synthetic
+                          `tool_input` / `tool_output` / ToolImport logs. String
+                          for adaptor HTTP router-bubble captures.
+                      receivedAt:
+                        type: integer
+                        format: int64
+                        description: Epoch milliseconds when this pair was captured. Present on synthetic logs.
+                  context:
+                    type: object
+                    description: |-
+                      Run correlation for synthetic logs keyed by tool id. Present
+                      on `tool_input` / `tool_output` / ToolImport captures so the
+                      originating flow or job can be recovered; omitted on adaptor
+                      HTTP router-bubble logs.
+                    properties:
+                      _rootContainerId:
+                        type: string
+                        description: Owning flow, API, or tool id of the run that produced this capture.
+                      _jobId:
+                        type: string
+                        description: Job id of the run that produced this capture.
                 additionalProperties: true
               examples:
-                default:
-                  summary: One captured debug request
+                adaptor_http:
+                  summary: Router-bubble HTTP capture
                   value:
-                    key: 6a2e23bbcf5b64ca6b93b774
-                    method: POST
-                    url: https://httpbin.org/post
-                    statusCode: 200
+                    key: 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST
+                    id: a10af1ade8fe477a847771c1e3716e36
+                    time: 1776917346304
+                    request:
+                      method: POST
+                      url: https://httpbin.org/post
+                      headers:
+                        content-type: application/json
+                      body: '{"orderId":"SO-1042"}'
+                    response:
+                      statusCode: 200
+                      headers:
+                        content-type: application/json
+                      body: '{"ok":true}'
+                tool_input:
+                  summary: Synthetic Tool Input capture
+                  value:
+                    key: 5481201053696-b20bf2bde8fe477a847771c1e3716e36-200-POST
+                    id: b20bf2bde8fe477a847771c1e3716e36
+                    time: 1776917346304
+                    request:
+                      method: POST
+                      headers: {}
+                      body:
+                        customerId: CUST-1001
+                    response:
+                      statusCode: 200
+                      headers: {}
+                      receivedAt: 1776917346304
+                      body:
+                        customerId: CUST-1001
+                        validated: true
+                    context:
+                      _jobId: 69d462d5b9c28ea0b7f82533
         '401':
           $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
         '404':
           $ref: '#/components/responses/404-not-found'
 components:
@@ -3894,6 +4349,18 @@ components:
                   format: email
         transform:
           $ref: '#/components/schemas/Transform'
+        debugUntil:
+          type: string
+          format: date-time
+          description: |
+            Enables debug capture for the tool input stage until this timestamp.
+            While it is in the future, invocations write input-stage
+            request/response logs, listed at
+            `GET /v1/tools/{_id}/tool_input/requests`. At most 1 hour in the
+            future. A past timestamp (or omitting the field) stops capture.
+            Arm/disarm with `PATCH /v1/tools/{_id}` path `/input/debugUntil`.
+          examples:
+            - '2026-08-25T12:30:00.000Z'
         mockInput:
           type: object
           description: |
@@ -4039,6 +4506,18 @@ components:
                   examples:
                     - postProcessOutput
                     - validateOutput
+        debugUntil:
+          type: string
+          format: date-time
+          description: |
+            Enables debug capture for the tool output stage until this timestamp.
+            While it is in the future, invocations write output-stage
+            request/response logs, listed at
+            `GET /v1/tools/{_id}/tool_output/requests`. At most 1 hour in the
+            future. A past timestamp (or omitting the field) stops capture.
+            Arm/disarm with `PATCH /v1/tools/{_id}` path `/output/debugUntil`.
+          examples:
+            - '2026-08-25T12:30:00.000Z'
         mockInput:
           type: object
           description: |
@@ -4597,6 +5076,41 @@ components:
               - message
       required:
         - errors
+    JsonPatchOperation:
+      type: object
+      description: A single JSON Patch operation (RFC 6902).
+      required:
+        - op
+        - path
+      properties:
+        op:
+          type: string
+          enum:
+            - replace
+            - add
+            - remove
+          x-enumDescriptions:
+            replace: Replaces the value at the specified path.
+            add: Sets the value at the specified path.
+            remove: Removes the value at the specified path.
+          description: The operation to perform.
+        path:
+          type: string
+          description: |-
+            JSON Pointer (RFC 6901) to the field to patch. Only
+            whitelisted paths are accepted — unlisted paths return
+            `422` with `"<path> is not a whitelisted property"`.
+        value:
+          description: The new value to set. Required for `replace` and `add`, omit for `remove`.
+    JsonPatchRequest:
+      type: array
+      description: |-
+        A JSON Patch document (RFC 6902). Send an array of patch
+        operations on whitelisted fields — all other paths are rejected
+        with 422.
+      minItems: 1
+      items:
+        $ref: '#/components/schemas/JsonPatchOperation'
     IAResourceResponse:
       type: object
       description: Integration app response fields for resources that are part of integration apps
@@ -33428,9 +33942,9 @@ components:
                 errors:
                   - code: dependencies_not_deleted
                     message: export 6902d88c10b42b2eaac9b2a1 must be deleted before you can delete connection 6398ddf316be761fb16a6523
-    403-forbidden:
+    422-unprocessable-entity:
       description: |
-        Forbidden. The authenticated caller does not have permission to perform this operation.
+        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
       content:
         application/json:
           schema:
@@ -33439,11 +33953,11 @@ components:
             default:
               value:
                 errors:
-                  - code: forbidden
-                    message: You do not have permission to access this resource.
-    422-unprocessable-entity:
+                  - code: unprocessable_entity
+                    message: The request could not be processed due to a semantic error.
+    403-forbidden:
       description: |
-        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
+        Forbidden. The authenticated caller does not have permission to perform this operation.
       content:
         application/json:
           schema:
@@ -33452,7 +33966,7 @@ components:
             default:
               value:
                 errors:
-                  - code: unprocessable_entity
-                    message: The request could not be processed due to a semantic error.
+                  - code: forbidden
+                    message: You do not have permission to access this resource.
 x-enable-proxy: true
 x-internal: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.20",
+  "version": "0.2.21",
   "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": "7ad7e60",
+		"iasCommit": "dc9205a",
 		"generatedAt": "2026-09-18"
 	},
 	"roots": {
@@ -8414,6 +8414,7 @@
 				"object"
 			],
 			"p": {
+				"debugUntil": 1,
 				"description": 1,
 				"mockInput": 10,
 				"name": 1,
@@ -8503,6 +8504,7 @@
 				"object"
 			],
 			"p": {
+				"debugUntil": 1,
 				"description": 1,
 				"hooks": 196,
 				"lookups": 709,