@celigo/api-specs 0.2.1

package/dist/api.yml

@@ -0,0 +1,4140 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: APIs
+  description: API for managing Celigo custom APIs — HTTP endpoints that expose integration logic to external systems.
+  x-celigo-ai-guidance:
+    - |-
+      API for managing APIs in Celigo. APIs allow you to expose integration logic as RESTful 
+      endpoints that can be invoked by external systems or applications.
+
+      APIs can be configured in two modes:
+      - **Builder Mode**: Visual configuration with request/response mapping, transformations, and routing logic
+      - **Script Mode**: Custom JavaScript functions for complete control over API behavior
+
+      Builder mode APIs support:
+      - Custom HTTP methods (GET, POST, PUT, PATCH, DELETE)
+      - Path parameters, query parameters, headers, and request bodies
+      - Request transformations before processing
+      - Conditional response routing based on processing results
+      - Response mapping with lookups and transformations
+      - Multiple response configurations for different scenarios
+      - Mock requests and responses for testing
+
+      Script mode APIs provide:
+      - Direct access to request/response objects
+      - Full JavaScript flexibility for complex logic
+      - Integration with existing script libraries
+servers:
+  - url: https://api.integrator.io
+    description: Production (US / default region)
+  - url: https://api.eu.integrator.io
+    description: Production (EU region)
+  - url: https://api.au.integrator.io
+    description: Production (AU region)
+  - url: https://api.ca.integrator.io
+    description: Production (CA region)
+security:
+  - bearerAuth: []
+tags:
+  - name: APIs
+    description: |-
+      APIs expose integration logic as HTTP endpoints that external systems can invoke.
+
+      Two modes:
+      - **Builder** — visual configuration with request/response mapping, routing, and transformations
+      - **Script** — custom JavaScript handler function for full control
+
+      Each API gets a public URL: `https://api.integrator.io/apis/{version}/{relativeURI}`
+
+      ## API schema
+
+      {% openapi-schemas spec="api" schemas="API" grouped="true" %}
+paths:
+  /v1/apis:
+    get:
+      x-internal: false
+      summary: List APIs
+      description: |-
+        Returns all APIs configured in the account. No pagination -- every API is returned in a single
+        response. Legacy script-mode APIs (created before the builder/script distinction) may omit
+        `type`, `version`, and `disabled`. A 204 response means the account has zero APIs.
+      operationId: listApis
+      tags:
+        - APIs
+      parameters:
+        - name: limit
+          in: query
+          description: Maximum number of records to return per page.
+          schema:
+            type: integer
+            minimum: 1
+            examples:
+              - 100
+        - name: name
+          in: query
+          description: |-
+            Filter by name — a substring match, not an exact match. An empty
+            value is ignored.
+          schema:
+            type: string
+            examples:
+              - Order
+        - name: disabled
+          in: query
+          description: Filter by the `disabled` flag.
+          schema:
+            type: boolean
+        - $ref: '#/components/parameters/After'
+        - $ref: '#/components/parameters/Include'
+        - $ref: '#/components/parameters/Exclude'
+      responses:
+        '200':
+          description: Successfully retrieved list of APIs.
+          headers:
+            Link:
+              description: |-
+                RFC-5988 pagination links. When more pages remain, includes a `<...>; rel="next"` entry;
+                absent on the final page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/API'
+              examples:
+                mixed:
+                  summary: Builder and script APIs
+                  value:
+                    - _id: 68ae4264b5f755d2dd3796b4
+                      name: Order Webhook
+                      type: builder
+                      version: v1
+                      disabled: false
+                      createdAt: '2025-08-26T23:25:24.107Z'
+                      lastModified: '2026-04-07T03:48:20.795Z'
+                    - _id: 689212abe5118c1cabfb43b3
+                      name: Custom Handler
+                      type: script
+                      version: v1
+                      disabled: false
+                      _scriptId: 689212a2c42d988978e27a11
+                      function: handleRequest
+                      createdAt: '2025-08-05T14:18:19.583Z'
+                      lastModified: '2025-08-05T14:18:42.626Z'
+        '204':
+          description: No APIs exist in the account.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+      x-celigo-ai-guidance:
+        - |-
+          Returns a list of all APIs configured in the account.
+          If no APIs exist in the account, a 204 response with no body will be returned.
+    post:
+      x-internal: false
+      summary: Create an API
+      description: |-
+        Creates a new API. For `script` mode, include `script._scriptId` and `script.function` (the
+        server also copies these to the top level in the response). For `builder` mode,
+        `builder.request` is required (at minimum `relativeURI` and `method`).
+
+        Builder-mode APIs are created with `logging: {"mode": "basic"}` when the account license
+        has logging enabled -- the request body cannot override this (`logging` is ignored on POST
+        and PUT; change it afterwards with `PATCH /v1/apis/{_id}`).
+      operationId: createApi
+      tags:
+        - APIs
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              script:
+                summary: Script-mode API
+                value:
+                  name: Custom Handler
+                  type: script
+                  script:
+                    _scriptId: 689212a2c42d988978e27a11
+                    function: handleRequest
+              builder:
+                summary: Builder-mode API
+                value:
+                  name: Order Webhook
+                  type: builder
+                  builder:
+                    request:
+                      name: Receive Order
+                      method: POST
+                      relativeURI: /orders
+                    responses:
+                      - id: success
+                        name: Success
+                        type: success
+                        statusCode: 200
+                      - id: fail
+                        name: Error
+                        type: fail
+                        statusCode: 500
+                    responseRouter:
+                      id: apiRouter
+                      routeRecordsUsing: input_filters
+      responses:
+        '201':
+          description: API created successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/API'
+              examples:
+                script:
+                  summary: Created script-mode API (server copies script config to top level)
+                  value:
+                    _id: 689212abe5118c1cabfb43b3
+                    name: Custom Handler
+                    type: script
+                    version: v1
+                    disabled: false
+                    script:
+                      _scriptId: 689212a2c42d988978e27a11
+                      function: handleRequest
+                    _scriptId: 689212a2c42d988978e27a11
+                    function: handleRequest
+                    createdAt: '2025-08-05T14:18:19.583Z'
+                    lastModified: '2025-08-05T14:18:19.583Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/apis/usage:
+    get:
+      x-internal: false
+      operationId: listApisUsage
+      tags:
+        - APIs
+      summary: List month-to-date API invocation counts
+      description: |-
+        Returns one invocation-counter record per resource + method + relativeURI in the current month.
+        Counts API-style invocations across every resource type that exposes an HTTP-callable endpoint:
+        custom APIs (builder and script), individual exports/imports called via `/invoke`, virtual
+        imports, and APIM-fronted invocations.
+
+        The endpoint aggregates -- it does not return one record per individual call. Each entry rolls
+        up every invocation of that (resource, method, URI) triple in the current month. Counters reset
+        on the 1st of each month; there is no pagination and no historical-months filter on this path.
+
+        `ioInvocationCount` bills against the Celigo subscription; `apimInvocationCount` is billed
+        separately for external APIM passthrough. To find the resource behind a row, read
+        `metadata._resourceId` (present for exports/imports) or parse the resource id out of
+        `relativeURI`.
+      parameters:
+        - $ref: '#/components/parameters/Include'
+        - $ref: '#/components/parameters/Exclude'
+      responses:
+        '200':
+          description: Usage breakdown for the current month. `usages[]` is empty when no endpoints have been invoked yet.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApisUsageResponse'
+              examples:
+                default:
+                  value:
+                    usages:
+                      - _id: 69d054b9be4ce14fb4112827
+                        method: POST
+                        relativeURI: /v1/exports/6878f4a43bc01652c09cdccc/invoke
+                        metadata:
+                          _resourceId: 6878f4a43bc01652c09cdccc
+                          name: Get Contacts
+                          type: export
+                        month: 4
+                        year: 2026
+                        ioInvocationCount: 29
+                        apimInvocationCount: 0
+                        createdAt: '2026-04-04T00:00:57.285Z'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/apis/{_id}:
+    get:
+      x-internal: false
+      summary: Get an API
+      description: Returns the complete configuration of a specific API.
+      operationId: getApiById
+      tags:
+        - APIs
+      parameters:
+        - name: _id
+          in: path
+          description: The unique identifier of the API
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: apis
+            examples:
+              - 5f8d43a1b9e5a80011a35f2c
+      responses:
+        '200':
+          description: API retrieved successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/API'
+              examples:
+                script:
+                  summary: Script-mode API
+                  value:
+                    _id: 689212abe5118c1cabfb43b3
+                    name: Custom Handler
+                    type: script
+                    version: v1
+                    disabled: false
+                    script:
+                      _scriptId: 689212a2c42d988978e27a11
+                      function: handleRequest
+                    _scriptId: 689212a2c42d988978e27a11
+                    function: handleRequest
+                    createdAt: '2025-08-05T14:18:19.583Z'
+                    lastModified: '2025-08-05T14:18:42.626Z'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    put:
+      x-internal: false
+      summary: Update an API
+      description: |-
+        Replaces the full API configuration. Send the complete object -- omitted fields revert to
+        defaults, not their prior values. Read-only fields (`_id`, `createdAt`, `lastModified`) in
+        the request body are ignored.
+
+        `logging` is also ignored -- silently: a PUT that includes `logging` succeeds with the
+        stored value unchanged, and no error reveals that the change was dropped. Use
+        `PATCH /v1/apis/{_id}` (paths `/logging/mode`, `/logging/debugUntil`) to change logging
+        settings.
+      operationId: updateApi
+      tags:
+        - APIs
+      parameters:
+        - name: _id
+          in: path
+          description: The unique identifier of the API
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: apis
+            examples:
+              - 5f8d43a1b9e5a80011a35f2c
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              rename-script:
+                summary: Rename a script-mode API
+                value:
+                  name: Custom Handler v2
+                  type: script
+                  script:
+                    _scriptId: 689212a2c42d988978e27a11
+                    function: handleRequest
+      responses:
+        '200':
+          description: API updated successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/API'
+              examples:
+                renamed:
+                  summary: Script-mode API with updated name
+                  value:
+                    _id: 689212abe5118c1cabfb43b3
+                    name: Custom Handler v2
+                    type: script
+                    version: v1
+                    disabled: false
+                    script:
+                      _scriptId: 689212a2c42d988978e27a11
+                      function: handleRequest
+                    _scriptId: 689212a2c42d988978e27a11
+                    function: handleRequest
+                    createdAt: '2025-08-05T14:18:19.583Z'
+                    lastModified: '2025-08-05T14:18:42.626Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+      x-celigo-ai-guidance:
+        - |-
+          Updates an existing API with the provided configuration.
+          This is used for major updates to an API's structure or behavior.
+    patch:
+      x-internal: false
+      summary: Patch an API
+      description: |-
+        Partially updates an API using a JSON Patch document (RFC 6902).
+        The `replace` operation is supported on the following whitelisted
+        paths (`/logging/debugUntil` also accepts `remove`, which clears an
+        active debug window early):
+
+        | Path | Description |
+        |------|-------------|
+        | `/name` | API display name |
+        | `/description` | API description |
+        | `/disabled` | Enable or disable the API (boolean) |
+        | `/timeoutPeriod` | Request-timeout override in seconds |
+        | `/pagination/enabled` | Enable or disable the cursor-pagination envelope (boolean) |
+        | `/logging/mode` | Logging level for requests handled by this API |
+        | `/logging/debugUntil` | End of a temporary full-debug capture window |
+        | `/traceKeyTemplate` | Handlebars template that computes each request's trace key |
+
+        All other paths are rejected with `422`. This is the only way to change
+        `logging` -- PUT silently ignores that field.
+
+        Logging changes are validated against account entitlements: setting
+        `/logging/mode` to a payload-capturing mode (`standard`, `detailed`)
+        fails with `422` (code `payload_storage_required`) when the account
+        does not have payload storage enabled, and `/logging/debugUntil` has
+        the same payload-storage requirement. Accounts whose license does not
+        include logging, or whose license caps the maximum logging mode below
+        the requested one, are also rejected with `422`.
+      operationId: patchApi
+      tags:
+        - APIs
+      parameters:
+        - name: _id
+          in: path
+          description: The unique identifier of the API
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: apis
+            examples:
+              - 5f8d43a1b9e5a80011a35f2c
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/JsonPatchRequest'
+            examples:
+              disable_api:
+                summary: Disable an API
+                value:
+                  - op: replace
+                    path: /disabled
+                    value: true
+              rename:
+                summary: Rename an API
+                value:
+                  - op: replace
+                    path: /name
+                    value: Order Webhook v2
+      responses:
+        '204':
+          description: API 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 an API
+      description: |-
+        Deletes an API. Soft-deleted and retained in the recycle bin for 30 days. The public endpoint
+        stops responding immediately. The delete succeeds even with dependents, but those resources
+        will break -- check `GET /v1/apis/{_id}/dependencies` first.
+      operationId: deleteApi
+      tags:
+        - APIs
+      parameters:
+        - name: _id
+          in: path
+          description: The unique identifier of the API
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: apis
+            examples:
+              - 5f8d43a1b9e5a80011a35f2c
+      responses:
+        '204':
+          description: API deleted successfully
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+      x-celigo-ai-guidance:
+        - |-
+          Deletes an API configuration. This will remove the endpoint from the system and 
+          it will no longer be accessible for invocation.
+  /v1/apis/schema:
+    put:
+      x-internal: false
+      operationId: convertJsonToSchema
+      tags:
+        - APIs
+      summary: Convert a JSON object to JSON Schema
+      description: |-
+        Accepts a sample JSON object and returns its inferred JSON Schema definition.
+        Useful for bootstrapping `bodySchema` in builder-mode APIs from real payload samples.
+        Input must be a non-empty JSON object -- arrays and primitives are rejected.
+        The generated schema is shallow (one level of `properties`); nested objects become
+        `type: "object"` without further property inference.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: true
+              description: Any sample JSON object to convert into JSON Schema.
+            example:
+              name: Acme Corp
+              active: true
+              count: 42
+      responses:
+        '200':
+          description: JSON Schema generated successfully.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  type:
+                    type: string
+                    example: object
+                  properties:
+                    type: object
+                    additionalProperties: true
+                additionalProperties: true
+              example:
+                type: object
+                properties:
+                  name:
+                    type: string
+                  active:
+                    type: boolean
+                  count:
+                    type: number
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/apis/updateApiGrouping:
+    put:
+      x-internal: false
+      operationId: updateApiGrouping
+      tags:
+        - APIs
+      summary: Update the grouping for one or more APIs
+      description: |-
+        Assigns or removes an API grouping for the specified API resources. Pass
+        `_apiGroupingId: null` to ungroup. Nonexistent API IDs are silently accepted.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - _apiIds
+              properties:
+                _apiIds:
+                  type: array
+                  items:
+                    type: string
+                    format: objectId
+                    x-celigo-refModel: apis
+                    examples:
+                      - 5f8d43a1b9e5a80011a35f2c
+                  description: List of API resource IDs to update.
+                _apiGroupingId:
+                  type:
+                    - string
+                    - 'null'
+                  format: objectId
+                  description: |-
+                    The grouping ID to assign. Pass `null` or omit to remove the
+                    current grouping from the specified APIs.
+                  examples:
+                    - 60a1b2c3d4e5f60012345678
+            example:
+              _apiIds:
+                - 5f8d43a1b9e5a80011a35f2c
+                - 5f8d43a1b9e5a80011a35f2d
+              _apiGroupingId: 60a1b2c3d4e5f60012345678
+      responses:
+        '204':
+          description: API grouping updated successfully (no body returned).
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/apis/{_id}/logs:
+    get:
+      x-internal: false
+      operationId: listApiLogs
+      tags:
+        - APIs
+      summary: List recent request/response logs for an API
+      description: |-
+        Returns the recent invocation traces captured for the named API. Each entry is a decoded
+        request/response pair — masked for credentials — that the runtime stored when the API was
+        called via its public endpoint. Use this to audit what the API has handled and to triage
+        errors without re-invoking the API.
+
+        Traces are **file-backed** with server-controlled retention and capture scope; an empty
+        `requests[]` simply means nothing is currently stored for this API. Two invocation sources do
+        **not** populate this log:
+        - Test-runs via `POST /v1/apis/{_id}/test/run` never surface here.
+        - Script-mode API invocations via `POST /v1/apis/{_id}/request` also do not surface here
+          despite counting toward `/v1/apis/usage`. Only **builder-mode** invocations against the
+          public endpoint (`https://api.integrator.io/apis/{version}{relativeURI}`) populate logs.
+
+        List entries are **summaries** (`key`, `time`, `method`, `statusCode`) — to see the decoded
+        request/response payload, follow up with `GET /v1/apis/{_id}/logs/{key}`.
+
+        `statusCode` is returned as a string in list entries but as an integer on the detail endpoint.
+        Credential values are masked as `********` before storage and are not recoverable.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: The API id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: apis
+            examples:
+              - 68ae4264b5f755d2dd3796b4
+      responses:
+        '200':
+          description: Trace envelope. `requests[]` is empty when no invocations are currently stored.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiLogsResponse'
+              examples:
+                empty:
+                  value:
+                    requests: []
+                populated:
+                  value:
+                    requests:
+                      - key: 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST
+                        time: 1776917346304
+                        method: POST
+                        statusCode: '200'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/apis/{_id}/logs/{key}:
+    get:
+      x-internal: false
+      operationId: getApiLogByKey
+      tags:
+        - APIs
+      summary: Get one request/response log entry by key
+      description: |-
+        Returns the full decoded request/response envelope for one API invocation, looked up by the
+        opaque `key` values surfaced in `GET /v1/apis/{_id}/logs`. Matches the exact entry whose key is
+        provided — there is no partial-match or range query on this endpoint.
+
+        Unlike the parent list (which only carries `{key, time, method, statusCode}`), this endpoint
+        returns the complete payload: request method/url/headers/body/queryParams/clientAddress,
+        response status/headers/body/responseTime, and (for builder-mode APIs) the
+        `inputToResponseBubble` snapshot of what the response-mapper saw. Sensitive header values
+        (`authorization`, OAuth bearer tokens) are masked as `********` before storage.
+
+        For builder APIs where the response mapper didn't produce the expected output, inspect
+        `inputToResponseBubble.sourceRecord` to see what the response stage actually received.
+        `response.statusCode` is an integer here but the sibling list endpoint returns it as a
+        string. A 404 `file_not_found` means the key has expired from retention or was never
+        captured.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: The API id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: apis
+            examples:
+              - 68ae4264b5f755d2dd3796b4
+        - name: key
+          in: path
+          required: true
+          description: |-
+            Opaque log key from the parent `GET /v1/apis/{_id}/logs` listing. Encodes status + method
+            (e.g. `…-200-POST`) — use the `key` exactly as returned; do not construct one manually.
+          schema:
+            type: string
+            examples:
+              - 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST
+      responses:
+        '200':
+          description: The decoded request/response envelope.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiLogDetail'
+              examples:
+                builder-success:
+                  summary: Successful builder-mode invocation (credentials masked)
+                  value:
+                    time: 1776917346304
+                    request:
+                      method: POST
+                      url: /apis/v1/orders
+                      httpVersion: '1.1'
+                      headers:
+                        content-type: application/json
+                        authorization: '********'
+                        accept: application/json
+                        host: api.integrator.io
+                      queryParams: {}
+                      body: '{"orderId":"SO-1042","total":129.99}'
+                      clientAddress: ::ffff:127.0.0.6
+                      size: 0
+                    response:
+                      statusCode: 200
+                      statusMessage: OK
+                      headers:
+                        content-type: application/json
+                        x-request-id: abc123def456
+                      body: '{"orderId":"SO-1042"}'
+                      size: 21
+                      responseTime: 312
+                    inputToResponseBubble:
+                      sourceRecord:
+                        - orderId: SO-1042
+                          total: 129.99
+                      executionErrors: []
+                      configurationErrors: []
+                    key: 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST
+                    id: a10af1ade8fe477a847771c1e3716e36
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/apis/{_id}/requests:
+    get:
+      x-internal: false
+      operationId: listApiRequests
+      tags:
+        - APIs
+      summary: List API request run history (defaults to last 5 minutes)
+      description: |-
+        Returns the logged request executions for an API — one entry per inbound
+        request captured while the API's `logging.mode` was anything other than
+        `noLogging`. Distinct from `GET /v1/apis/{_id}/logs`, which returns the
+        legacy file-backed request/response envelopes: use `/requests` for run
+        history and trace drill-down, `/logs` for the raw decoded request and
+        response of a single call.
+
+        Whether requests are captured into run history depends on server-side
+        enablement of the capture pipeline, which is separate from this read
+        API. On accounts where capture is not active, this endpoint responds
+        normally (including filter validation) but `requests` is empty
+        regardless of the API's `logging.mode` — even for requests that the
+        legacy `GET /v1/apis/{_id}/logs` (an independent capture path) does
+        record.
+
+        Results are cursor-paginated (`next`/`prev`). When `time_gte` / `time_lte`
+        are omitted, only the last 5 minutes are returned — pass an explicit window
+        for a broader history. Use the `executionId` from a list entry with
+        `GET /v1/apis/{_id}/requests/{executionId}` to open the trace view for
+        requests logged in `detailed` or `debug` mode.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: The API id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: apis
+            examples:
+              - 685021eda02a61042cee80ab
+        - name: statusCode
+          in: query
+          description: |-
+            Filter by HTTP response status code — a single value or a
+            comma-separated list. Every value must be an integer.
+          schema:
+            type: string
+            pattern: ^\d+(,\d+)*$
+            examples:
+              - 200,404
+        - name: method
+          in: query
+          description: Filter by HTTP method (case-insensitive; normalized to uppercase).
+          schema:
+            type: string
+            enum:
+              - GET
+              - POST
+              - PUT
+              - PATCH
+              - DELETE
+              - HEAD
+              - OPTIONS
+            examples:
+              - GET
+        - name: traceKey
+          in: query
+          description: Prefix filter on the request trace key.
+          schema:
+            type: string
+            examples:
+              - trace-abc
+        - name: remoteIP
+          in: query
+          description: Prefix filter on the client IP address.
+          schema:
+            type: string
+            examples:
+              - 192.168.1.
+        - name: relativeURI
+          in: query
+          description: Prefix filter on the request relative URI.
+          schema:
+            type: string
+            examples:
+              - /orders
+        - name: searchKey
+          in: query
+          description: |-
+            Free-text search, OR-matched across `traceKey` (prefix), `remoteIP`
+            (prefix), and `relativeURI` (substring). When provided, the individual
+            `traceKey`/`remoteIP`/`relativeURI` filters are ignored. Values shorter
+            than 3 characters are rejected with 400.
+          schema:
+            type: string
+            minLength: 3
+            maxLength: 500
+            examples:
+              - order-123
+        - name: pageSize
+          in: query
+          description: |-
+            Number of entries per page. Values above the documented maximum are
+            not rejected — the server accepts them silently, so treat the
+            maximum as the supported contract rather than an enforced limit.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 50
+            examples:
+              - 50
+        - name: sortOrder
+          in: query
+          description: Sort direction by request time.
+          schema:
+            type: string
+            enum:
+              - asc
+              - desc
+            x-enumDescriptions:
+              asc: Oldest requests first
+              desc: Newest requests first
+            default: desc
+        - name: next
+          in: query
+          description: |-
+            ISO 8601 timestamp cursor for the next page (from `nextPageUrl`).
+            Mutually exclusive with `prev`; requires `cursorExecutionId`.
+          schema:
+            type: string
+            format: date-time
+        - name: prev
+          in: query
+          description: |-
+            ISO 8601 timestamp cursor for the previous page (from `prevPageUrl`).
+            Mutually exclusive with `next`; requires `cursorExecutionId`.
+          schema:
+            type: string
+            format: date-time
+        - name: cursorExecutionId
+          in: query
+          description: Tie-breaker execution id, required when paging with `next`/`prev`.
+          schema:
+            type: string
+        - name: time_gte
+          in: query
+          description: Include requests at or after this ISO timestamp.
+          schema:
+            type: string
+            format: date-time
+        - name: time_lte
+          in: query
+          description: Include requests at or before this ISO timestamp.
+          schema:
+            type: string
+            format: date-time
+      responses:
+        '200':
+          description: Paginated run history. `requests[]` is empty when nothing matches.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiRunHistoryResponse'
+              examples:
+                default:
+                  value:
+                    requests:
+                      - executionId: a1b2c3d4e5f678901234
+                        time: '2026-05-15T13:42:11.234Z'
+                        method: POST
+                        relativeURI: /orders
+                        statusCode: 200
+                        traceKey: trace-abc-123
+                        remoteIP: 192.168.1.5
+                        timeTaken: 142.7
+                        logMode: detailed
+                    nextPageUrl: null
+                    prevPageUrl: null
+        '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'
+    delete:
+      x-internal: false
+      operationId: deleteApiRequestLogs
+      tags:
+        - APIs
+      summary: Delete API request logs in a date range
+      description: |-
+        Queues asynchronous deletion of stored request log payloads for the API
+        within `[startedAt, endAt]`. Returns `202 Accepted`; cleanup runs in the
+        background. Requires manage access for log deletion — monitor-level users
+        receive `403`.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: The API id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: apis
+            examples:
+              - 685021eda02a61042cee80ab
+        - name: startedAt
+          in: query
+          required: true
+          description: Start of the deletion range, inclusive (ISO 8601). Must be before `endAt`.
+          schema:
+            type: string
+            format: date-time
+            examples:
+              - '2026-01-01T00:00:00.000Z'
+        - name: endAt
+          in: query
+          required: true
+          description: End of the deletion range, inclusive (ISO 8601). Must not be in the future.
+          schema:
+            type: string
+            format: date-time
+            examples:
+              - '2026-01-31T23:59:59.999Z'
+      responses:
+        '202':
+          description: Deletion request accepted for asynchronous processing.
+        '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/apis/{_id}/requests/{executionId}:
+    get:
+      x-internal: false
+      operationId: getApiRequestTrace
+      tags:
+        - APIs
+      summary: Get trace metadata for an API request execution
+      description: |-
+        Returns the top-level execution steps for the trace view of one API
+        request. Trace data is only available for requests that were logged in
+        `detailed` or `debug` mode (see `logMode` on the run-history entry), and
+        only when the run-history capture pipeline is active for the account
+        (see `GET /v1/apis/{_id}/requests`) — otherwise `steps` is empty for
+        every execution id.
+
+        A malformed `executionId` returns `422`; an unknown API `_id` returns `404`.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: The API id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: apis
+            examples:
+              - 685021eda02a61042cee80ab
+        - name: executionId
+          in: path
+          required: true
+          description: The execution id (20-character lowercase hex).
+          schema:
+            type: string
+            pattern: ^[0-9a-f]{20}$
+            examples:
+              - a1b2c3d4e5f678901234
+      responses:
+        '200':
+          description: Top-level trace steps for the request execution.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiTraceMetadataResponse'
+              examples:
+                default:
+                  value:
+                    steps:
+                      - _expOrImpId: 67ee026136f4d1eeb529ad63
+                        status: success
+                        timeTaken: 142
+                        groupId: 6449f2
+                        recordId: 4a8e5c
+                        time: '2026-05-15T13:42:11.234Z'
+        '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'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/apis/{_id}/requests/{executionId}/{_expOrImpId}/logs/{parentRecordId}/children:
+    get:
+      x-internal: false
+      operationId: listApiRequestChildren
+      tags:
+        - APIs
+      summary: List child records under an API trace step
+      description: |-
+        Returns the child records under a parent record within an API request
+        trace (lookup / one-to-many expansions). Results are cursor-paginated
+        (`next`/`prev`).
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: The API id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: apis
+            examples:
+              - 685021eda02a61042cee80ab
+        - name: executionId
+          in: path
+          required: true
+          description: The execution id (20-character lowercase hex).
+          schema:
+            type: string
+            pattern: ^[0-9a-f]{20}$
+            examples:
+              - a1b2c3d4e5f678901234
+        - name: _expOrImpId
+          in: path
+          required: true
+          description: Export, import, or builder resource-step identifier for the step.
+          schema:
+            type: string
+            examples:
+              - 67ee026136f4d1eeb529ad63
+        - name: parentRecordId
+          in: path
+          required: true
+          description: The parent record id whose children are returned.
+          schema:
+            type: string
+            examples:
+              - a1b2c3
+        - name: status
+          in: query
+          description: |-
+            Filter children by processing outcome — a single value or a
+            comma-separated list of `success`, `error`, `ignore`.
+          schema:
+            type: string
+            pattern: ^(success|error|ignore)(,(success|error|ignore))*$
+            examples:
+              - success,error
+        - name: pageSize
+          in: query
+          description: Number of entries per page.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 50
+            examples:
+              - 50
+        - name: sortOrder
+          in: query
+          description: Sort direction by step time.
+          schema:
+            type: string
+            enum:
+              - asc
+              - desc
+            x-enumDescriptions:
+              asc: Oldest child records first
+              desc: Newest child records first
+            default: desc
+        - name: next
+          in: query
+          description: |-
+            ISO 8601 timestamp cursor for the next page (from `nextPageUrl`).
+            Mutually exclusive with `prev`; requires `cursorRecordId`.
+          schema:
+            type: string
+            format: date-time
+        - name: prev
+          in: query
+          description: |-
+            ISO 8601 timestamp cursor for the previous page (from `prevPageUrl`).
+            Mutually exclusive with `next`; requires `cursorRecordId`.
+          schema:
+            type: string
+            format: date-time
+        - name: cursorRecordId
+          in: query
+          description: Tie-breaker record id, required when paging with `next`/`prev`.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Paginated child step records.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiRequestChildrenResponse'
+              examples:
+                default:
+                  value:
+                    children:
+                      - _expOrImpId: 67ee026136f4d1eeb529ad63
+                        status: success
+                        timeTaken: 12
+                        groupId: 6449f2
+                        recordId: child-1
+                        parentRecordId: a1b2c3
+                        time: '2026-05-15T13:42:11.234Z'
+                    nextPageUrl: null
+                    prevPageUrl: null
+        '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'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/apis/{_id}/requests/{executionId}/logs/data/query:
+    post:
+      x-internal: false
+      operationId: queryApiRequestLogData
+      tags:
+        - APIs
+      summary: Query decoded log data for an API trace step
+      description: |-
+        Returns the decoded request/response payload and error metadata for a
+        record/stage within an API request execution, identified by
+        `_expOrImpId`, `stage`, `groupId`, and `recordId`. If the log content
+        exceeds inline limits or is stored externally, an `externalReference`
+        with an S3 key (and optional byte range) is returned — download it via
+        the signed-URL endpoint. The response may be gzip-compressed.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: The API id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: apis
+            examples:
+              - 685021eda02a61042cee80ab
+        - name: executionId
+          in: path
+          required: true
+          description: The execution id (20-character lowercase hex).
+          schema:
+            type: string
+            pattern: ^[0-9a-f]{20}$
+            examples:
+              - a1b2c3d4e5f678901234
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ApiLogDataRequest'
+            examples:
+              minimal:
+                value:
+                  _expOrImpId: 67ee026136f4d1eeb529ad63
+                  stage: mapping
+                  groupId: grp-001
+                  recordId: rec-123
+      responses:
+        '200':
+          description: Log data (and/or external references) plus error metadata.
+          headers:
+            Content-Encoding:
+              description: May be `gzip` to reduce transfer time for large responses.
+              schema:
+                type: string
+                enum:
+                  - gzip
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiLogDataResponse'
+              examples:
+                default:
+                  value:
+                    logs: []
+                    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'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/apis/{_id}/requests/{executionId}/logs/signedURL:
+    get:
+      x-internal: false
+      operationId: getApiRequestLogSignedUrl
+      tags:
+        - APIs
+      summary: Get a signed URL for a stored API request log payload
+      description: |-
+        Returns a short-lived signed S3 URL (about 120 seconds expiry) for the
+        provided `s3Key` suffix, taken from an `externalReference` returned by the
+        log-data query endpoint. The full S3 key is resolved under the execution's
+        own log prefix, so callers can only access logs for this API and execution.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: The API id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: apis
+            examples:
+              - 685021eda02a61042cee80ab
+        - name: executionId
+          in: path
+          required: true
+          description: The execution id (20-character lowercase hex).
+          schema:
+            type: string
+            pattern: ^[0-9a-f]{20}$
+            examples:
+              - a1b2c3d4e5f678901234
+        - name: s3Key
+          in: query
+          required: true
+          description: |-
+            S3 object key suffix relative to the execution's log prefix, typically
+            returned in a prior log-data query `externalReference`.
+          schema:
+            type: string
+            examples:
+              - 67ee026136f4d1eeb529ad63/grp-001/part.log
+      responses:
+        '200':
+          description: Signed URL for the requested object.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiSignedUrlResponse'
+              examples:
+                default:
+                  value:
+                    signedURL: https://integrator-userdata-delete-30.s3.amazonaws.com/api-execution-logs/user/api/exec/group/file.log?Expires=1754046196&Signature=...
+        '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'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/apis/{_id}/dependencies:
+    get:
+      x-internal: false
+      operationId: listApiDependencies
+      tags:
+        - APIs
+      summary: List dependencies of an API
+      description: |-
+        Returns the set of resources that depend on the specified resource.
+        The response is an object whose keys are dependent-resource types
+        (e.g. `flows`, `imports`) and whose values are arrays of dependency
+        entries. An empty object `{}` means no other resources depend on the
+        target -- this is also returned for a well-formatted but nonexistent id.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Resource ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: apis
+            examples:
+              - 5f8d43a1b9e5a80011a35f2c
+      responses:
+        '200':
+          description: |
+            Dependency map. Keys are resource-type strings; values are arrays
+            of dependency entries. Returns `{}` when no dependents exist.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DependencyResponse'
+              examples:
+                none:
+                  summary: No dependents (also returned for a nonexistent ID)
+                  value: {}
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/apis/{_id}/test/run:
+    post:
+      x-internal: false
+      operationId: testRunApi
+      tags:
+        - APIs
+      summary: Test-run an API
+      description: |-
+        Executes the API once in a sandboxed test harness without invoking its public endpoint, and
+        returns the job tree produced by the run. Use this to validate a builder-mode API's request
+        parsing, routing, and response mapping before exposing it externally.
+
+        The response carries a `metadata` map keyed by step id (each value is the ordered list of
+        stage names that ran for that step), the parent `flowJob`, and the per-step `childJobs[]`.
+        Inspect a specific step's stages with `GET /v1/apis/{_id}/test/run/{runId}/{_stepId}`, where
+        `runId` is the parent `flowJob._id`.
+
+        Test-run invocations do **not** surface in `GET /v1/apis/{_id}/logs`.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: The API id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: apis
+            examples:
+              - 68ae4264b5f755d2dd3796b4
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              description: |-
+                Optional test request for the run. When the body is empty or
+                omitted, the run replays the API's saved
+                `builder.request.mockRequest`.
+              properties:
+                mockRequest:
+                  type: object
+                  description: |-
+                    The simulated request to run instead of the saved
+                    `builder.request.mockRequest`.
+                  properties:
+                    body:
+                      type: object
+                      description: Request body for the simulated call.
+                    pathParams:
+                      type: object
+                      description: Path parameter values for the simulated call.
+                    queryParams:
+                      type: object
+                      description: Query parameter values for the simulated call.
+                    headers:
+                      type: object
+                      description: Request headers for the simulated call.
+              additionalProperties: true
+              x-celigo-ai-guidance:
+                - Send explicit test input under the mockRequest key ({body, pathParams, queryParams, headers}); with no body the run replays the saved builder.request.mockRequest.
+            examples:
+              default:
+                summary: Run with no overrides
+                value: {}
+              withMockRequest:
+                summary: Run with an explicit test request
+                value:
+                  mockRequest:
+                    queryParams:
+                      sku: SKU-001
+      responses:
+        '200':
+          description: The job tree produced by the test run.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  metadata:
+                    type: object
+                    description: |-
+                      Map keyed by step id; each value is the ordered list of stage names that ran for
+                      that step.
+                    additionalProperties:
+                      type: array
+                      items:
+                        type: string
+                  flowJob:
+                    type: object
+                    description: The parent job for the test run. Its `_id` is the `runId`.
+                  childJobs:
+                    type: array
+                    description: Per-step child jobs produced during the run.
+                    items:
+                      type: object
+              examples:
+                default:
+                  value:
+                    metadata:
+                      68ae4264b5f755d2dd3796b4:
+                        - request
+                        - parse
+                      main:
+                        - router
+                    flowJob:
+                      _id: 6a2e23bbcf5b64ca6b93b757
+                      type: flow
+                      _integrationId: 68ed772471086fb1a76686de
+                      status: completed
+                      numError: 1
+                      numSuccess: 1
+                      startedAt: '2026-06-14T03:44:59.577Z'
+                      endedAt: '2026-06-14T03:44:59.947Z'
+                    childJobs:
+                      - _id: 6a2e23bbcf5b64ca6b93b774
+                        type: export
+                        _parentJobId: 6a2e23bbcf5b64ca6b93b757
+                        status: completed
+                        numSuccess: 1
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/apis/{_id}/test/run/{runId}/{_stepId}:
+    get:
+      x-internal: false
+      operationId: getApiTestRunStep
+      tags:
+        - APIs
+      summary: Get a step's stages from an API test run
+      description: |-
+        Returns the per-stage execution detail for a single step of a completed API test run. `runId`
+        is the parent `flowJob._id` returned by `POST /v1/apis/{_id}/test/run`, and `_stepId` is the
+        step id surfaced in that run's `metadata` map.
+
+        Each entry in `stages[]` carries the stage `name` (e.g. `request`, `parse`, `router`) plus its
+        `input`, `output`, and `errors`. Stages that did not produce data for a given direction return
+        `null` for that field. Top-level `errors` aggregates step-level errors.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: The API id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: apis
+            examples:
+              - 68ae4264b5f755d2dd3796b4
+        - name: runId
+          in: path
+          required: true
+          description: The parent job id (`flowJob._id`) returned by the test-run request.
+          schema:
+            type: string
+            examples:
+              - 6a2e23bbcf5b64ca6b93b757
+        - name: _stepId
+          in: path
+          required: true
+          description: The step id, as surfaced in the test run's `metadata` map.
+          schema:
+            type: string
+            examples:
+              - 68ae4264b5f755d2dd3796b4
+      responses:
+        '200':
+          description: Per-stage execution detail for the requested step.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  stages:
+                    type: array
+                    description: Ordered stages that ran for this step.
+                    items:
+                      type: object
+                      properties:
+                        name:
+                          type: string
+                          description: Stage name (e.g. `request`, `parse`, `router`).
+                        errors:
+                          description: Stage-level errors, or `null` when none.
+                        input:
+                          description: Input records the stage received, or `null`.
+                        output:
+                          description: Output records the stage produced, or `null`.
+                  errors:
+                    type: array
+                    description: Aggregated step-level errors.
+                    items:
+                      type: object
+              examples:
+                default:
+                  value:
+                    stages:
+                      - name: request
+                        errors: null
+                        output: null
+                        input:
+                          - record:
+                              page:
+                                _userId: 624cb0346309dc3a543733a2
+                                data:
+                                  - {}
+                            errors: []
+                            traceKey: null
+                      - name: parse
+                        errors: null
+                        input: null
+                        output:
+                          - record: {}
+                            errors: []
+                            traceKey: null
+                    errors: []
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/apis/{_id}/test/run/{runId}/{_stepId}/logs/requestAndResponse:
+    get:
+      x-internal: false
+      operationId: getApiTestRunStepLogs
+      tags:
+        - APIs
+      summary: Get request/response captures for an API test-run step
+      description: |-
+        Returns the request/response captures recorded for a single export or import step of an API
+        test run. `runId` is the parent `flowJob._id` from `POST /v1/apis/{_id}/test/run`, and
+        `_stepId` is the step id from that run's `metadata` map.
+
+        Each entry in `requests[]` is a summary identified by an opaque `key`; fetch the full decoded
+        request/response envelope with `GET /v1/apis/{_id}/{_stepId}/requests/{key}`. A step id that
+        is not an export or import (such as a router) returns a 400 `invalid_ref`, and a step that
+        captured no request/response data returns a 404 `req_res_logs_not_found`.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: The API id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: apis
+            examples:
+              - 68ae4264b5f755d2dd3796b4
+        - name: runId
+          in: path
+          required: true
+          description: The parent job id (`flowJob._id`) returned by the test-run request.
+          schema:
+            type: string
+            examples:
+              - 6a2e23bbcf5b64ca6b93b757
+        - name: _stepId
+          in: path
+          required: true
+          description: The step id, as surfaced in the test run's `metadata` map. Must be an export or import step.
+          schema:
+            type: string
+            examples:
+              - 68ae434d5fcd3b761b24253a
+      responses:
+        '200':
+          description: Request captures recorded for the step.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  requests:
+                    type: array
+                    description: Captured request summaries for the step.
+                    items:
+                      type: object
+                      properties:
+                        key:
+                          type: string
+                          description: |-
+                            Opaque key for the capture. Resolve the full decoded request/response with
+                            `GET /v1/apis/{_id}/{_stepId}/requests/{key}`.
+                        time:
+                          type: integer
+                          description: Capture time, epoch milliseconds.
+                        method:
+                          type: string
+                          description: HTTP method of the captured request, or `undefined` when not applicable.
+                        statusCode:
+                          type: string
+                          description: Response status code, as a string.
+                        stage:
+                          type: string
+                          description: The stage that produced the capture (e.g. `import`).
+              examples:
+                populated:
+                  summary: One capture for an import step
+                  value:
+                    requests:
+                      - key: 5475338577473-6c43f93c1fa84b248d64e0d7be1f275f-200-undefined-import-testMode
+                        time: 1782779822527
+                        method: undefined
+                        statusCode: '200'
+                        stage: import
+        '400':
+          description: |-
+            The `_stepId` does not resolve to an export or import step (for example, a router step
+            or a malformed id). Use a step id that ran an outbound request.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalidStep:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _expOrImpId.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            No request/response data is stored for the requested step — it captured nothing, or the
+            run/step id didn't resolve.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                noLogs:
+                  value:
+                    errors:
+                      - code: req_res_logs_not_found
+                        message: No request/response log data found.
+  /v1/apis/{_id}/{_stepId}/requests:
+    get:
+      x-internal: false
+      operationId: listApiStepRequests
+      tags:
+        - APIs
+      summary: List captured requests for an API step
+      description: |-
+        Returns the set of requests captured for a single step of an API. `_stepId` identifies the
+        step within the API's configuration. Each entry in `requests[]` is a captured request summary;
+        follow up with `GET /v1/apis/{_id}/{_stepId}/requests/{key}` to retrieve one entry in full.
+
+        An empty `requests[]` simply means nothing is currently stored for this step.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: The API id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: apis
+            examples:
+              - 68ae4264b5f755d2dd3796b4
+        - name: _stepId
+          in: path
+          required: true
+          description: The step id within the API's configuration.
+          schema:
+            type: string
+            examples:
+              - 68ae4264b5f755d2dd3796b4
+      responses:
+        '200':
+          description: Captured requests for the step. `requests[]` is empty when nothing is stored.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  requests:
+                    type: array
+                    description: Captured request entries for this step.
+                    items:
+                      type: object
+              examples:
+                empty:
+                  value:
+                    requests: []
+                populated:
+                  value:
+                    requests:
+                      - key: 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST
+                        time: 1776917346304
+                        method: POST
+                        statusCode: '200'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/apis/{_id}/{_stepId}/requests/{key}:
+    get:
+      x-internal: false
+      operationId: getApiStepRequest
+      tags:
+        - APIs
+      summary: Get one captured request for an API step by key
+      description: |-
+        Returns the full captured request/response envelope for one entry of an API step, looked up by
+        the opaque `key` values surfaced in `GET /v1/apis/{_id}/{_stepId}/requests`. Matches the exact
+        entry whose key is provided — there is no partial-match query on this endpoint.
+
+        Use the `key` exactly as returned by the parent listing; do not construct one manually. A 404
+        means the key has expired from retention or was never captured.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: The API id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: apis
+            examples:
+              - 68ae4264b5f755d2dd3796b4
+        - name: _stepId
+          in: path
+          required: true
+          description: The step id within the API's configuration.
+          schema:
+            type: string
+            examples:
+              - 68ae4264b5f755d2dd3796b4
+        - name: key
+          in: path
+          required: true
+          description: |-
+            Opaque request key from the parent `GET /v1/apis/{_id}/{_stepId}/requests` listing. Use the
+            `key` exactly as returned; do not construct one manually.
+          schema:
+            type: string
+            examples:
+              - 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST
+      responses:
+        '200':
+          description: The full captured request/response envelope for the entry.
+          content:
+            application/json:
+              schema:
+                type: object
+                description: Decoded request/response envelope for the captured entry.
+              examples:
+                default:
+                  value:
+                    time: 1776917346304
+                    request:
+                      method: POST
+                      url: /apis/v1/orders
+                      headers:
+                        content-type: application/json
+                      body: '{"orderId":"SO-1042"}'
+                    response:
+                      statusCode: 200
+                      headers:
+                        content-type: application/json
+                      body: '{"orderId":"SO-1042"}'
+                    key: 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/apis/{_id}/clone:
+    post:
+      x-internal: false
+      operationId: cloneApi
+      tags:
+        - APIs
+      summary: Clone an API
+      description: |-
+        Clones a builder-mode API along with the resources it depends on (such as its
+        backing import) and returns a manifest of every resource created.
+
+        The request body is required: `version` must be supplied, and the cloned API's
+        combination of `version`, `method`, and `relativeURI` must be unique. Reusing all
+        three returns a 422 `clone_api_already_exists`. Pass `_integrationId` to create the
+        clone inside an integration — when omitted, the clone is created standalone rather
+        than inheriting the source API's integration.
+
+        Only **builder-type** APIs can be cloned — cloning any other API type returns a 400
+        `clone_not_supported`.
+
+        To check for a version/method/relativeURI conflict without creating anything, call
+        `POST /v1/apis/{_id}/clone/validate` first.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: The id of the API to clone.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: apis
+            examples:
+              - 68ae4264b5f755d2dd3796b4
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - version
+              properties:
+                version:
+                  type: string
+                  description: |-
+                    Version identifier for the cloned API. The cloned API's combination of
+                    `version`, `method`, and `relativeURI` must be unique — reusing all three
+                    returns a 422 `clone_api_already_exists`.
+                  examples:
+                    - v2
+                name:
+                  type: string
+                  description: Name for the cloned API. Defaults to a copy of the source API's name when omitted.
+                  examples:
+                    - IDP (v2)
+                _integrationId:
+                  type: string
+                  format: objectId
+                  x-celigo-refModel: integrations
+                  description: |-
+                    Integration the cloned API is created in. When omitted, the clone is created
+                    standalone — it does not inherit the source API's integration.
+                  examples:
+                    - 6a429af50547257e3301246c
+            examples:
+              default:
+                summary: Clone to a new version
+                value:
+                  version: v2
+                  name: IDP (v2)
+      responses:
+        '201':
+          description: |-
+            The clone was created. Returns a manifest of every resource the clone created —
+            the new API plus any dependencies it copied (imports, scripts).
+          content:
+            application/json:
+              schema:
+                type: array
+                description: Manifest of resources created by the clone.
+                items:
+                  type: object
+                  properties:
+                    model:
+                      type: string
+                      description: Model name of the created resource (e.g. `Api`, `Import`).
+                      examples:
+                        - Api
+                    _id:
+                      type: string
+                      format: objectId
+                      description: Unique id of the created resource.
+                      examples:
+                        - 6a2e23bbcf5b64ca6b93b757
+              examples:
+                default:
+                  summary: Clone created an API and its backing import
+                  value:
+                    - model: Import
+                      _id: 6a2e23bbcf5b64ca6b93b73d
+                    - model: Api
+                      _id: 6a2e23bbcf5b64ca6b93b757
+        '400':
+          description: |-
+            The request was rejected. Common causes: the body omits the required `version`
+            field (`required_field_missing`), or the target API is not a builder-type API
+            (`clone_not_supported` — only builder APIs can be cloned).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                missingVersion:
+                  summary: Required version field missing
+                  value:
+                    errors:
+                      - code: required_field_missing
+                        message: 'required field: version is missing'
+                notBuilder:
+                  summary: API is not builder-type
+                  value:
+                    errors:
+                      - code: clone_not_supported
+                        message: Cloning is supported only for builder type API documents.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          description: |-
+            An API with the same `version`, `method`, and `relativeURI` already exists. Clone
+            with a different `version` (or change the method/URI) to create a distinct API.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                alreadyExists:
+                  value:
+                    errors:
+                      - code: clone_api_already_exists
+                        message: The clone API already exists with the same version, method and relative uri.
+  /v1/apis/{_id}/clone/validate:
+    post:
+      x-internal: false
+      operationId: validateApiClone
+      tags:
+        - APIs
+      summary: Validate an API clone
+      description: |-
+        Dry-run check for `POST /v1/apis/{_id}/clone`. Verifies that cloning the
+        API to the target `version` would not collide with an existing API route
+        — the clone keeps the source API's `method` and `relativeURI`, so the
+        target `version` + `method` + `relativeURI` combination must not conflict
+        with an API that is already registered in the account. Nothing is created
+        or modified.
+
+        Returns `canClone: true` when the route is free, `false` when it
+        conflicts — pick a different `version` before calling
+        `POST /v1/apis/{_id}/clone`. Only **builder-type** APIs can be validated;
+        a script-type API returns 404, the same as an unknown id.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: The id of the API to validate cloning for.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: apis
+            examples:
+              - 68ae4264b5f755d2dd3796b4
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - version
+              properties:
+                version:
+                  type: string
+                  description: |-
+                    Version identifier the clone would be created under. Omitting
+                    it returns a 400 `required_field_missing`.
+                  examples:
+                    - v2
+            examples:
+              default:
+                summary: Validate cloning to a new version
+                value:
+                  version: v2
+      responses:
+        '200':
+          description: Validation result. Returned for both outcomes — check `canClone`.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  canClone:
+                    type: boolean
+                    description: |-
+                      When true, the target `version` + `method` + `relativeURI`
+                      route is free and the clone can be created. When false, the
+                      route conflicts with an existing API — choose a different
+                      `version`.
+              examples:
+                free:
+                  summary: Route is free — safe to clone
+                  value:
+                    canClone: true
+                conflict:
+                  summary: Version/method/relativeURI already taken
+                  value:
+                    canClone: false
+        '400':
+          description: The body omits the required `version` field.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                missingVersion:
+                  summary: Required version field missing
+                  value:
+                    errors:
+                      - code: required_field_missing
+                        message: 'required field: version is missing'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            The API does not exist, is not visible to the caller, or is not a
+            builder-type API.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                notFound:
+                  summary: Unknown id or script-type API
+                  value:
+                    errors:
+                      - code: source_builder_api_not_found
+                        message: Source API of builder type could not be found.
+  /v1/apis/{_id}/template:
+    get:
+      x-internal: false
+      operationId: getApiTemplate
+      tags:
+        - APIs
+      summary: Get a downloadable template for an API
+      description: |-
+        Packages a builder-mode API as an installable template and returns a
+        signed S3 URL where the template `.zip` can be downloaded. The URL is
+        pre-signed and short-lived (approximately 15 minutes), so fetch the file
+        promptly; call the endpoint again for a fresh URL.
+
+        The `.zip` contains the API definition plus every resource it references
+        — imports, exports, connections, and scripts — grouped into one folder
+        per resource type, with an `integration.json` manifest at the root.
+
+        Only **builder-type** APIs can be exported — requesting a script-type
+        API returns 404, the same as an unknown id. Requires the
+        `create:api:template` permission.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: The id of the API to export.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: apis
+            examples:
+              - 68ae4264b5f755d2dd3796b4
+      responses:
+        '200':
+          description: Signed download URL for the API template zip.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  signedURL:
+                    type: string
+                    format: uri
+                    description: Pre-signed, short-lived S3 URL to download the template `.zip`.
+                    examples:
+                      - https://integrator-templates.s3.us-east-1.amazonaws.com/68ae4264b5f755d2dd3796b4.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=b117bf598b5535ed024cdbdfec756172f386fd39ad4e4536e40e5efbbf4ff52a
+                  key:
+                    type: string
+                    description: S3 object key for the generated template `.zip`, named `<apiId>.zip`.
+                    examples:
+                      - 68ae4264b5f755d2dd3796b4.zip
+              examples:
+                default:
+                  summary: Signed template download URL
+                  value:
+                    signedURL: https://integrator-templates.s3.us-east-1.amazonaws.com/68ae4264b5f755d2dd3796b4.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=b117bf598b5535ed024cdbdfec756172f386fd39ad4e4536e40e5efbbf4ff52a
+                    key: 68ae4264b5f755d2dd3796b4.zip
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            The API does not exist, is not visible to the caller, or is not a
+            builder-type API (script-type APIs cannot be exported as templates).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                notFound:
+                  summary: Unknown id or script-type API
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Api not found.
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  parameters:
+    After:
+      name: after
+      in: query
+      required: false
+      description: |-
+        Opaque cursor for forward pagination. Pass the value from the `Link`
+        response header (`rel="next"`) to fetch the next page.
+      schema:
+        type: string
+    Include:
+      name: include
+      in: query
+      required: false
+      description: |-
+        Comma-separated list of fields to project into each returned record.
+        Triggers summary projection: the response contains a minimal identity
+        set (`_id`, `name`, plus resource-specific fields) with the requested
+        fields added on top. Supports dot notation for nested fields.
+        Mutually exclusive with `exclude`.
+      schema:
+        type: string
+      example: _integrationId,disabled,lastModified
+    Exclude:
+      name: exclude
+      in: query
+      required: false
+      description: |-
+        Comma-separated list of fields to strip from the default response.
+        Unlike `include`, does not trigger summary projection — returns the
+        full record with the named fields removed. Protected identity fields
+        (e.g. `name`) cannot be stripped. Mutually exclusive with `include`.
+      schema:
+        type: string
+      example: createdAt,lastModified
+  schemas:
+    Script:
+      type: object
+      description: |-
+        Script-mode configuration. The referenced function receives the request object
+        and must return a response with `statusCode`, `headers`, and `body`.
+      properties:
+        _scriptId:
+          type: string
+          format: objectId
+          x-celigo-refModel: scripts
+          description: Reference to the script resource containing the handler function.
+          examples:
+            - 60a2c4e6f321d800129a1a3c
+        function:
+          type: string
+          description: Name of the function to invoke within the script.
+          examples:
+            - handleRequest
+            - processOrder
+      required:
+        - _scriptId
+        - function
+      x-celigo-ai-guidance:
+        - |-
+          In script mode, you provide a custom JavaScript function that receives the request
+          object and returns the response. This gives you complete control over the API behavior.
+    ApiRequest:
+      type: object
+      description: Request configuration for a builder-mode API endpoint.
+      properties:
+        name:
+          type: string
+          maxLength: 200
+          description: Display name.
+          examples:
+            - Get Customer
+            - Create Order
+        description:
+          type: string
+          maxLength: 10240
+          description: Optional description.
+          examples:
+            - Retrieves customer information by ID
+        relativeURI:
+          type: string
+          maxLength: 131072
+          pattern: ^\/[a-zA-Z0-9:_*\/\-\.]*$
+          description: |-
+            URI path relative to the version. Full endpoint becomes
+            `/{version}{relativeURI}`. Use colon notation for path params: `/customers/:id`.
+          examples:
+            - /customers/:id
+            - /orders
+            - /products/:productId/variants/:variantId
+          x-celigo-ai-guidance:
+            - |-
+              Full endpoint URL will be: `/{version}{relativeURI}`
+              Can include path parameters using colon notation: `/customers/:id`
+              First path segment must be alphanumeric, dash, or underscore only.
+        method:
+          type: string
+          enum:
+            - GET
+            - POST
+            - PUT
+            - PATCH
+            - DELETE
+          x-enumDescriptions:
+            GET: Retrieve data from the endpoint.
+            POST: Submit data to the endpoint.
+            PUT: Replace data at the endpoint.
+            PATCH: Partially update data at the endpoint.
+            DELETE: Remove data at the endpoint.
+          description: HTTP method for the API endpoint.
+          examples:
+            - GET
+            - POST
+        headers:
+          type: array
+          description: Expected request headers.
+          items:
+            type: object
+            properties:
+              key:
+                type: string
+                maxLength: 256
+                pattern: ^[a-zA-Z0-9_-]+$
+                description: Header name
+                examples:
+                  - Content-Type
+                  - X-API-Key
+              description:
+                type: string
+                maxLength: 10240
+                description: Description of the header's purpose
+                examples:
+                  - API key for authentication
+          x-celigo-ai-guidance:
+            - |-
+              Documents headers that clients should send. Headers are optional by default.
+              Only alphanumeric characters, hyphens, and underscores are allowed in header names.
+        pathParams:
+          type: array
+          description: Path parameters defined in the `relativeURI`.
+          items:
+            type: object
+            properties:
+              key:
+                type: string
+                maxLength: 256
+                description: Parameter name (without the colon prefix)
+                examples:
+                  - id
+                  - customerId
+              description:
+                type: string
+                maxLength: 10240
+                description: Description of the parameter
+                examples:
+                  - Unique identifier of the customer
+          x-celigo-ai-guidance:
+            - |-
+              Documents the parameters that are part of the URL path (e.g., :id, :customerId).
+              These should match the parameters defined in the relativeURI.
+        queryParams:
+          type: array
+          description: Expected query string parameters.
+          items:
+            type: object
+            properties:
+              key:
+                type: string
+                maxLength: 256
+                pattern: ^[a-zA-Z0-9_\-:\/]*$
+                description: Query parameter name
+                examples:
+                  - limit
+                  - offset
+                  - filter
+              dataType:
+                type: string
+                enum:
+                  - string
+                  - number
+                  - boolean
+                x-enumDescriptions:
+                  string: Parameter value is a text string.
+                  number: Parameter value is a numeric value.
+                  boolean: Parameter value is true or false.
+                description: Expected data type of the parameter
+                examples:
+                  - string
+              description:
+                type: string
+                maxLength: 10240
+                description: Description of the parameter
+                examples:
+                  - Maximum number of records to return
+        bodySchema:
+          type: object
+          description: |-
+            JSON Schema describing the expected request body structure. Every
+            object-typed schema node must declare at least one property for the
+            API Builder to render it; omit this field when the endpoint has no
+            body contract.
+          additionalProperties: true
+          examples:
+            - type: object
+              properties:
+                name:
+                  type: string
+                email:
+                  type: string
+                  format: email
+          x-celigo-ai-guidance:
+            - |-
+              Every object-typed schema node — the root, a nested property, or an
+              array's `items` — must carry a non-empty `properties` map. The API
+              persists a property-less object node without error, but the API
+              Builder editor crashes rendering it ("Cannot convert undefined or
+              null to object"), so the mistake only surfaces when the editor opens.
+            - |-
+              When the endpoint has no body contract (e.g. the source spec declares
+              an empty request body), omit `bodySchema` entirely — absent renders
+              fine. Do not substitute a catch-all `{"type": "object"}`, and do not
+              pre-fill `properties: {}` — the API strips empty objects on save, so
+              the empty map never survives the round-trip.
+        mockRequest:
+          type: object
+          description: Mock request data for testing the API without live calls.
+          properties:
+            body:
+              type: object
+              description: Sample request body
+            headers:
+              type: object
+              description: Sample headers
+            pathParams:
+              type: object
+              description: Sample path parameters
+            queryParams:
+              type: object
+              description: Sample query parameters
+          additionalProperties: false
+          x-celigo-ai-guidance:
+            - |-
+              Provides sample data to test the API without making actual calls.
+              Can include body, headers, pathParams, and queryParams.
+        transform:
+          type: object
+          description: Optional transformation applied to the incoming request before processing.
+          properties:
+            _scriptId:
+              type: string
+              format: objectId
+              x-celigo-refModel: scripts
+              description: Reference to a script for custom transformation logic.
+              examples:
+                - 689212a2c42d988978e27a11
+            function:
+              type: string
+              description: Function name in the script to execute.
+              examples:
+                - transformRequest
+          x-celigo-ai-guidance:
+            - |-
+              Transforms the request data before it is processed by routers or responses.
+              Useful for normalizing data or extracting specific fields.
+      required:
+        - relativeURI
+        - method
+      x-celigo-ai-guidance:
+        - |-
+          Defines how the API endpoint receives data:
+          - HTTP method and URI path
+          - Expected parameters (path, query, headers)
+          - Request body schema
+          - Optional request transformation logic
+    Router:
+      type: object
+      description: |-
+        Conditional routing within a builder-mode API. Unlike flows, APIs only
+        support `first_matching_branch` routing.
+      properties:
+        id:
+          type: string
+          description: Unique identifier for this router within the API.
+          examples:
+            - router_001
+            - validation_router
+        name:
+          type: string
+          description: Display name.
+          examples:
+            - Customer Type Router
+            - Validation Router
+        routeRecordsTo:
+          type: string
+          enum:
+            - first_matching_branch
+          x-enumDescriptions:
+            first_matching_branch: Routes the request to the first branch whose criteria match.
+          description: Routing strategy. APIs only support `first_matching_branch`.
+          default: first_matching_branch
+          examples:
+            - first_matching_branch
+        routeRecordsUsing:
+          type: string
+          enum:
+            - input_filters
+            - script
+          x-enumDescriptions:
+            input_filters: Evaluate routing criteria using declarative filter expressions.
+            script: Evaluate routing criteria using a custom JavaScript function.
+          description: Method used to evaluate routing criteria.
+          default: input_filters
+          examples:
+            - input_filters
+        script:
+          type: object
+          description: |
+            Script configuration when routeRecordsUsing="script".
+          properties:
+            _scriptId:
+              type: string
+              format: objectId
+              x-celigo-refModel: scripts
+              description: Reference to the script resource.
+              examples:
+                - 60a2c4e6f321d800129a1a3c
+            function:
+              type: string
+              description: Function name that returns the branch name.
+              examples:
+                - routeRequest
+                - determineBranch
+        branches:
+          type: array
+          description: Processing branches, evaluated in order.
+          items:
+            type: object
+            properties:
+              name:
+                type: string
+                description: Branch name
+                examples:
+                  - Premium customers
+              inputFilter:
+                type: object
+                description: Filter criteria for branch selection.
+                properties:
+                  version:
+                    type: string
+                    enum:
+                      - '1'
+                    x-enumDescriptions:
+                      '1': Version 1 of the Celigo expression-based filter format.
+                    description: Version of the filter format used by `rules`.
+                  rules:
+                    type: array
+                    description: Celigo expression-based filter rules.
+                    items: {}
+                    examples:
+                      - - equals
+                        - - get
+                          - customerType
+                        - premium
+                      - - and
+                        - - exists
+                          - - get
+                            - orderId
+                        - - greaterThan
+                          - - get
+                            - amount
+                          - 1000
+                    x-celigo-ai-guidance:
+                      - |-
+                        Array-based DSL where the first element is an operator (e.g., "equals", "and", "or"),
+                        followed by operands which can be nested expressions.
+              nextRouterId:
+                type: string
+                description: Next router to chain to (or "apiRouter" for final routing)
+                examples:
+                  - apiRouter
+              pageProcessors:
+                type: array
+                description: Processing steps to execute in this branch
+                items:
+                  type: object
+                  properties:
+                    type:
+                      type: string
+                      enum:
+                        - export
+                        - import
+                      x-enumDescriptions:
+                        export: Uses an export resource for data lookup or enrichment.
+                        import: Uses an import resource to send data to a destination system.
+                      description: Type of processor
+                    _exportId:
+                      type: string
+                      format: objectId
+                      x-celigo-refModel: exports
+                      description: Export resource reference (when type="export").
+                      examples:
+                        - 6878f4a43bc01652c09cdccc
+                    _importId:
+                      type: string
+                      format: objectId
+                      x-celigo-refModel: imports
+                      description: Import resource reference (when type="import").
+                      examples:
+                        - 6878f4a43bc01652c09cddee
+                    hooks:
+                      type: object
+                      description: Custom scripts for processing
+          x-celigo-ai-guidance:
+            - |-
+              Each branch has its own criteria and processing steps. Requests are
+              evaluated against branch criteria in the order defined.
+      required:
+        - branches
+      x-celigo-ai-guidance:
+        - |-
+          Routers evaluate the request and route it to different processing branches.
+          This enables complex business logic and conditional processing within your API.
+    ResponseRouter:
+      type: object
+      description: |-
+        Final routing step that selects which response configuration to return.
+        Must have `id: "apiRouter"`.
+      properties:
+        id:
+          type: string
+          enum:
+            - apiRouter
+          x-enumDescriptions:
+            apiRouter: Identifies this as the final router that determines which API response to return.
+          description: Must be `"apiRouter"`.
+          examples:
+            - apiRouter
+          x-celigo-ai-guidance:
+            - |-
+              Must be "apiRouter" to indicate this is the final router before
+              returning the API response.
+        routeRecordsUsing:
+          type: string
+          enum:
+            - input_filters
+            - script
+          x-enumDescriptions:
+            input_filters: Evaluate routing criteria using declarative filter expressions.
+            script: Evaluate routing criteria using a custom JavaScript function.
+          description: Method used to determine which response to use.
+          examples:
+            - input_filters
+          x-celigo-ai-guidance:
+            - |-
+              - **input_filters**: Use declarative filter expressions on each response
+              - **script**: Use custom JavaScript to return the response id
+        script:
+          type: object
+          description: Script configuration when `routeRecordsUsing` is `"script"`.
+          properties:
+            _scriptId:
+              type: string
+              format: objectId
+              x-celigo-refModel: scripts
+              description: Reference to the script resource.
+              examples:
+                - 60a2c4e6f321d800129a1a3c
+            function:
+              type: string
+              description: Function name that returns the response id.
+              examples:
+                - determineResponse
+                - routeToResponse
+      x-celigo-ai-guidance:
+        - |-
+          The response router determines which response configuration to use based on
+          the processing results. This allows you to return different responses based
+          on different conditions or outcomes.
+    ApiResponse:
+      type: object
+      description: |-
+        Response configuration in a builder-mode API. Each API requires exactly one
+        `success` and one `fail` response; additional `custom` responses are optional.
+      properties:
+        id:
+          type: string
+          description: Unique identifier for this response, referenced by the response router.
+          examples:
+            - success_response
+            - error_response
+            - custom_validation_response
+        name:
+          type: string
+          maxLength: 200
+          description: Display name.
+          examples:
+            - Success Response
+            - Error Response
+            - Validation Error
+        description:
+          type: string
+          maxLength: 10240
+          description: Optional description of when this response is used.
+          examples:
+            - Returned when customer is successfully created
+        type:
+          type: string
+          enum:
+            - success
+            - fail
+            - custom
+          x-enumDescriptions:
+            success: Default response returned when the API operation completes successfully.
+            fail: Default response returned when the API operation encounters an error.
+            custom: Additional response for specific scenarios, routed via the response router.
+          description: Response type.
+          examples:
+            - success
+          x-celigo-ai-guidance:
+            - |-
+              - **success**: Default response for successful operations (required, exactly one)
+              - **fail**: Default response for errors (required, exactly one)
+              - **custom**: Additional responses for specific scenarios (optional, multiple allowed)
+        statusCode:
+          type: integer
+          minimum: 100
+          maximum: 599
+          description: HTTP status code to return.
+          examples:
+            - 200
+            - 201
+            - 400
+            - 404
+            - 500
+        headers:
+          type: array
+          description: Response headers to include.
+          items:
+            type: object
+            properties:
+              key:
+                type: string
+                maxLength: 256
+                pattern: ^[a-zA-Z0-9_-]+$
+                description: Header name
+                examples:
+                  - Content-Type
+                  - X-Request-Id
+              value:
+                type: string
+                maxLength: 256
+                description: Header value (can include handlebars templates)
+                examples:
+                  - application/json
+                  - '{{requestId}}'
+              description:
+                type: string
+                maxLength: 10240
+                description: Description of the header
+                examples:
+                  - Content type of the response body
+        inputFilter:
+          type: object
+          description: Filter criteria for response selection by the response router.
+          properties:
+            version:
+              type: string
+              enum:
+                - '1'
+              x-enumDescriptions:
+                '1': Version 1 of the Celigo expression-based filter format.
+              description: Version of the filter format used by `rules`.
+            rules:
+              type: array
+              description: Celigo expression-based filter rules.
+              items: {}
+              examples:
+                - - equals
+                  - - boolean
+                    - - context
+                      - success
+                  - true
+                - - and
+                  - - equals
+                    - - get
+                      - statusCode
+                    - 200
+                  - - exists
+                    - - get
+                      - data
+              x-celigo-ai-guidance:
+                - |-
+                  Array-based DSL where the first element is an operator (e.g., "equals", "and", "or"),
+                  followed by operands which can be nested expressions.
+        bodySchema:
+          type: object
+          description: |-
+            JSON Schema describing the response body structure. Every object-typed
+            schema node must declare at least one property for the API Builder to
+            render it; omit this field when the response body has no defined shape.
+          additionalProperties: true
+          examples:
+            - type: object
+              properties:
+                id:
+                  type: string
+                name:
+                  type: string
+                createdAt:
+                  type: string
+                  format: date-time
+          x-celigo-ai-guidance:
+            - |-
+              Every object-typed schema node — the root, a nested property, or an
+              array's `items` — must carry a non-empty `properties` map. The API
+              persists a property-less object node without error, but the API
+              Builder editor crashes rendering it ("Cannot convert undefined or
+              null to object"), so the mistake only surfaces when the editor opens.
+            - |-
+              When copying a schema from an external spec, prune property-less
+              object nodes (e.g. an array's `items` that is a bare
+              `{"type": "object"}`) instead of reproducing them. Array-typed roots
+              (which carry `items`, not `properties`) and type-less nullable
+              leaves render fine. Do not pre-fill `properties: {}` — the API
+              strips empty objects on save.
+        mockInput:
+          type:
+            - object
+            - string
+          maxLength: 0
+          description: |-
+            Mock data for testing this response, in the integrator.io canonical
+            record-page format: `{"page_of_records": [{"record": {...}}, ...]}`.
+            The server rejects any other object shape and any non-empty string
+            with a 422; the empty string `""` (a UI draft artifact) is accepted
+            and stored verbatim.
+          required:
+            - page_of_records
+          properties:
+            page_of_records:
+              type: array
+              description: Pages of mock records fed to this response's mappings.
+              items:
+                type: object
+                required:
+                  - record
+                properties:
+                  record:
+                    type: object
+                    description: One mock input record (freeform payload).
+                  success:
+                    type: boolean
+                    description: When true, the mock record follows the success path.
+                  testMode:
+                    type: boolean
+                    description: When true, the mock record is treated as a test-mode record.
+          additionalProperties: true
+        mappings:
+          type: array
+          description: Field mappings to transform processing results into the response body.
+          items:
+            type: object
+            required:
+              - dataType
+            properties:
+              generate:
+                type: string
+                description: Target field path in the response
+                examples:
+                  - data.customerId
+              dataType:
+                type: string
+                enum:
+                  - string
+                  - number
+                  - boolean
+                  - object
+                  - stringarray
+                  - numberarray
+                  - booleanarray
+                  - objectarray
+                  - arrayarray
+                x-lowercase: true
+                x-enumDescriptions:
+                  string: Single string value
+                  number: Single numeric value
+                  boolean: Single boolean value
+                  object: Nested object value
+                  stringarray: Array of strings
+                  numberarray: Array of numbers
+                  booleanarray: Array of booleans
+                  objectarray: Array of objects
+                  arrayarray: Array of arrays
+                description: Data type of the value this mapping writes into the response body.
+                examples:
+                  - string
+                x-celigo-ai-guidance:
+                  - |-
+                    Validator-enforced on every mapping entry: writes fail with
+                    `422` ("Path 'dataType' is required."), repeated once per
+                    entry that omits it.
+              extract:
+                type: string
+                description: Source field path from input data
+                examples:
+                  - record.id
+              hardCodedValue:
+                type: string
+                description: |-
+                  Static value written to the target field instead of extracting
+                  from input data.
+                x-celigo-ai-guidance:
+                  - |-
+                    The field name is exactly `hardCodedValue` (capital C). The
+                    server does not reject unknown mapping keys: a mapping sent
+                    with `hardcodedValue` saves successfully with the value
+                    silently dropped — no error, and the target field is then
+                    simply absent from the API's responses.
+        lookups:
+          type: array
+          description: Static key-value lookup tables for value transformation.
+          items:
+            type: object
+            properties:
+              name:
+                type: string
+                description: Name of the lookup
+                examples:
+                  - statusCodeMap
+              map:
+                type: object
+                description: Key-value mapping object
+              default:
+                type: string
+                description: Default value if key not found
+                examples:
+                  - unknown
+              allowFailures:
+                type: boolean
+                description: When true, processing continues even if this lookup fails.
+        hooks:
+          type: object
+          description: Custom scripts to run during response processing.
+          properties:
+            preMap:
+              type: object
+              description: Script to run before applying mappings.
+              properties:
+                _scriptId:
+                  type: string
+                  format: objectId
+                  x-celigo-refModel: scripts
+                  description: Reference to the script resource.
+                  examples:
+                    - 689212a2c42d988978e27a11
+                function:
+                  type: string
+                  description: Function name to execute.
+                  examples:
+                    - preMapResponse
+            postMap:
+              type: object
+              description: Script to run after applying mappings.
+              properties:
+                _scriptId:
+                  type: string
+                  format: objectId
+                  x-celigo-refModel: scripts
+                  description: Reference to the script resource.
+                  examples:
+                    - 689212a2c42d988978e27a11
+                function:
+                  type: string
+                  description: Function name to execute.
+                  examples:
+                    - postMapResponse
+      x-celigo-ai-guidance:
+        - |-
+          Defines how to format and return data to the caller. Each API must have:
+          - Exactly one 'success' response (for successful operations)
+          - Exactly one 'fail' response (for errors)
+          - Zero or more 'custom' responses (for specific scenarios)
+    Builder:
+      type: object
+      description: Builder-mode configuration defining request structure, routing, and response mapping.
+      properties:
+        request:
+          $ref: '#/components/schemas/ApiRequest'
+        routers:
+          type: array
+          description: Optional routers for conditional processing before the response stage.
+          items:
+            $ref: '#/components/schemas/Router'
+          x-celigo-ai-guidance:
+            - |-
+              Routers allow you to direct requests to different processing branches
+              based on criteria. This enables complex business logic within the API.
+        responseRouter:
+          $ref: '#/components/schemas/ResponseRouter'
+        responses:
+          type: array
+          description: |-
+            Response configurations. Must include exactly one `success` and one `fail`
+            response; additional `custom` responses are optional.
+          items:
+            $ref: '#/components/schemas/ApiResponse'
+          x-celigo-ai-guidance:
+            - |-
+              Must include exactly one 'success' response and one 'fail' response.
+              Additional custom responses can be added for specific scenarios.
+      x-celigo-ai-guidance:
+        - |-
+          The builder mode allows you to define your API using visual configuration:
+          - Define the request structure (method, path, parameters)
+          - Transform incoming requests
+          - Route requests through processing logic
+          - Map and transform responses
+    Shipworks:
+      type: object
+      description: ShipWorks shipping-management credentials. Legacy feature.
+      properties:
+        username:
+          type: string
+          description: ShipWorks username.
+          examples:
+            - shipworks_user
+        password:
+          type: string
+          description: ShipWorks password. Masked as `"******"` in GET responses.
+          examples:
+            - '******'
+          x-celigo-ai-guidance:
+            - |-
+              When retrieving, this will be masked as "******" if a password is set.
+              When creating/updating, provide the actual password value.
+      required:
+        - username
+        - password
+      x-celigo-ai-guidance:
+        - |-
+          ShipWorks is a shipping management platform. This configuration stores
+          authentication credentials for ShipWorks-specific API integrations.
+    APIBase:
+      type: object
+      description: Writable fields shared by the request and response schemas.
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 100
+          description: Display name.
+          examples:
+            - Customer API
+            - Order Management API
+        _integrationId:
+          type: string
+          format: objectId
+          x-celigo-refModel: integrations
+          description: Integration this API belongs to. Omitted for standalone APIs (an API can be created without an integration).
+          examples:
+            - 5e9a8f7c6b3d2a0011c4e5f6
+          x-celigo-ai-guidance:
+            - To move the API to a different integration, PUT with a changed _integrationId; the platform registers the API's step connections in the target integration on save.
+        description:
+          type: string
+          description: Optional description of the API's purpose.
+          examples:
+            - API for managing customer records in Salesforce
+          x-celigo-ai-guidance:
+            - Use this to document the API's purpose, expected inputs/outputs, and any special considerations.
+        type:
+          type: string
+          enum:
+            - builder
+            - script
+          default: script
+          x-enumDescriptions:
+            builder: Visual configuration with request/response mapping and transformations.
+            script: Custom JavaScript function for complete control over API behavior.
+          description: |-
+            API mode. Cannot be changed after creation. Defaults to `script` when
+            omitted on create; legacy script APIs created before builder mode may
+            omit it on reads as well.
+          examples:
+            - builder
+        version:
+          type: string
+          default: v1
+          pattern: ^[a-zA-Z0-9\-_\.]+$
+          description: Version segment of the public URL (`/{version}/{relativeURI}`).
+          examples:
+            - v1
+            - v2
+            - v1.0
+        disabled:
+          type: boolean
+          default: false
+          description: When true, the API rejects all incoming requests.
+          examples:
+            - false
+        timeoutPeriod:
+          type: integer
+          minimum: 0
+          maximum: 120
+          description: |-
+            Request-timeout override in seconds (1–120). `0` is a sentinel meaning "use the
+            120-second default" — the server rewrites it on write, so a stored value is never 0.
+          examples:
+            - 120
+            - 30
+        logging:
+          type: object
+          description: |-
+            Execution-logging settings for the API. Builder-mode APIs are
+            initialized to `{"mode": "basic"}` at creation (when the account
+            license has logging enabled), so the field is present on responses
+            from the start.
+
+            POST and PUT bodies cannot set or change this field — the server
+            ignores it silently (the write succeeds and the stored value is
+            untouched). `PATCH /v1/apis/{_id}` with the `/logging/mode` and
+            `/logging/debugUntil` paths is the only way to change it.
+          x-celigo-ai-guidance:
+            - |-
+              Never send logging changes via PUT: the request returns 200 with
+              the stored value unchanged — no error, nothing persisted. PATCH
+              `/logging/mode` and `/logging/debugUntil` are the only writers.
+          properties:
+            mode:
+              type: string
+              enum:
+                - basic
+                - standard
+                - detailed
+                - accountLevel
+                - noLogging
+              x-enumDescriptions:
+                basic: Log request metadata (method, URI, status, timing) only.
+                standard: Log request metadata plus headers and summary step information.
+                detailed: Full capture including per-step trace logs, viewable in the run-history trace view.
+                accountLevel: Defer to the account's logging settings.
+                noLogging: Disable request logging entirely — no run-history entries are produced.
+              description: |-
+                Which logging level applies to requests handled by this API. Only
+                `detailed` (or a temporary debug window) produces the per-step
+                trace data used by `GET /v1/apis/{_id}/requests/{executionId}`.
+                Payload-capturing modes (`standard`, `detailed`) require payload
+                storage to be enabled for the account — without it, changing the
+                mode fails with `422` (code `payload_storage_required`).
+            debugUntil:
+              type: string
+              format: date-time
+              description: |-
+                While this timestamp is in the future, requests are captured in
+                full debug mode regardless of `mode`. Clears itself once the
+                window passes. Setting it requires payload storage to be enabled
+                for the account.
+              examples:
+                - '2026-05-15T14:00:00.000Z'
+        traceKeyTemplate:
+          type: string
+          maxLength: 1024
+          description: |-
+            Handlebars template that computes each request's trace key from the
+            request payload, used to correlate run-history entries with source
+            records. Absent from responses until set.
+          examples:
+            - '{{record.orderId}}'
+        pagination:
+          type: object
+          description: |-
+            Cursor pagination for builder-mode APIs whose volume-driver lookup
+            supports paging. When enabled, API responses are wrapped in a
+            `{data, pagination: {has_more, next_cursor}}` envelope; consumers
+            resume by sending `next_cursor` in the POST body (or the
+            `Celigo-Next-Cursor` header on GET) until `has_more` is false.
+            Invalid or mismatched cursors fail with `invalid_cursor_format`,
+            `cursor_version_unsupported`, `cursor_signature_invalid`,
+            `cursor_api_mismatch`, `cursor_filter_mismatch`, or
+            `cursor_not_supported_for_api`. Absent from responses until set.
+          properties:
+            enabled:
+              type: boolean
+              description: When true, the pagination envelope and cursor contract are active for this API.
+        script:
+          $ref: '#/components/schemas/Script'
+        builder:
+          $ref: '#/components/schemas/Builder'
+        shipworks:
+          $ref: '#/components/schemas/Shipworks'
+        draft:
+          type: boolean
+          description: |-
+            When true, this API is a draft that auto-deletes when its expiry passes
+            (`draftExpiresAt` in the response). Set at creation; an update can clear the
+            flag but never set it.
+          x-celigo-ai-guidance:
+            - |-
+              POST with `draft: true` arms the draft TTL (the server computes `draftExpiresAt`).
+              PUT with `draft: false` clears the flag and the expiry, promoting the draft to a
+              permanent API. PUT with `draft: true` on a non-draft API is silently ignored, and
+              a PUT that omits the field leaves an existing draft flag unchanged.
+    Apim:
+      type: array
+      readOnly: true
+      description: Publication status of this API in external API management systems.
+      items:
+        type: object
+        properties:
+          apiId:
+            type: string
+            description: Identifier assigned by the external API management system (a UUID, not a Celigo API _id).
+            examples:
+              - 44754dc4-15fa-4f52-b54d-c415fa5f525c
+          flowId:
+            type: string
+            description: Associated flow identifier in the external API management system (a UUID, not a Celigo flow _id). Empty when no flow is associated.
+            examples:
+              - 14b8def5-143e-4598-b8de-f5143e559832
+          status:
+            type: string
+            enum:
+              - oaspending
+              - published
+            x-enumDescriptions:
+              oaspending: OpenAPI spec generation or update is pending for this API.
+              published: The API has been published to the external API management system.
+            description: Publication status.
+          definitionVersion:
+            type: string
+            enum:
+              - v4
+            x-enumDescriptions:
+              v4: Version 4 of the API definition format used by the management system.
+            description: API definition format version.
+      x-celigo-ai-guidance:
+        - |-
+          Tracks the publication status of this API to external API management systems
+          and portals. Used for generating and syncing OpenAPI specifications.
+    API:
+      required:
+        - _id
+        - name
+        - createdAt
+        - lastModified
+      description: |-
+        API resource. Shape varies by mode: builder-mode APIs carry `type`, `version`,
+        `disabled`, and `builder`; script-mode APIs additionally carry `script` plus
+        top-level `_scriptId` / `function` copies. Legacy script APIs (pre-builder era)
+        omit `type`, `version`, `disabled`, and `builder` entirely.
+      allOf:
+        - $ref: '#/components/schemas/APIBase'
+        - type: object
+          properties:
+            _id:
+              type: string
+              format: objectId
+              readOnly: true
+              x-celigo-refModel: apis
+              description: Unique identifier for the API.
+              examples:
+                - 68ae4264b5f755d2dd3796b4
+            _apiGroupingId:
+              type:
+                - string
+                - 'null'
+              format: objectId
+              readOnly: true
+              description: |-
+                API grouping this API belongs to. Set only via
+                `PUT /apis/grouping`; the server ignores this field in POST/PUT
+                bodies on this resource. May be `null` after ungrouping.
+              examples:
+                - 60a1b2c3d4e5f60012345678
+            _scriptId:
+              type: string
+              format: objectId
+              readOnly: true
+              x-celigo-refModel: scripts
+              description: |-
+                Top-level copy of `script._scriptId`. Present on script-mode and legacy
+                script APIs for backward compatibility.
+              examples:
+                - 689212a2c42d988978e27a11
+            function:
+              type: string
+              readOnly: true
+              description: |-
+                Top-level copy of `script.function`. Present on script-mode and legacy
+                script APIs for backward compatibility.
+              examples:
+                - handleRequest
+            createdAt:
+              type: string
+              format: date-time
+              readOnly: true
+              description: Timestamp when the API was created.
+              examples:
+                - '2025-08-26T23:25:24.107Z'
+            lastModified:
+              type: string
+              format: date-time
+              readOnly: true
+              description: Timestamp when the API was last modified.
+              examples:
+                - '2026-04-07T03:48:20.795Z'
+            _templateId:
+              type: string
+              format: objectId
+              readOnly: true
+              x-celigo-refModel: templates
+              description: Template this API was created from. Present only on template-installed APIs.
+              examples:
+                - 60a2c4e6f321d800129a1a3c
+            draftExpiresAt:
+              type: string
+              format: date-time
+              readOnly: true
+              description: |-
+                Timestamp when a draft API auto-deletes. Server-computed when `draft` is set at
+                creation.
+              examples:
+                - '2026-01-15T09:30:00.000Z'
+            apim:
+              $ref: '#/components/schemas/Apim'
+      x-celigo-ai-guidance:
+        - |-
+          Contains the complete API configuration including metadata, script/builder settings,
+          and integration-specific configurations.
+    Request:
+      type: object
+      description: |-
+        Request body for creating or updating an API.
+
+        For builder-mode APIs, populate the `builder` object (at minimum
+        `builder.request.relativeURI` and `builder.request.method`); the `script`
+        field is ignored. For script-mode APIs, populate `script` with `_scriptId`
+        and `function`; the `builder` field is ignored. On PUT, send the complete
+        object — omitted fields revert to defaults.
+
+        Set `type` explicitly to `builder` or `script`. The server infers `script`
+        when `type` is omitted, but new APIs must declare it.
+      required:
+        - name
+        - type
+      allOf:
+        - $ref: '#/components/schemas/APIBase'
+    Error:
+      type: object
+      description: Standard error response envelope returned by integrator.io APIs.
+      properties:
+        errors:
+          type: array
+          description: List of errors that occurred while processing the request.
+          items:
+            type: object
+            properties:
+              code:
+                oneOf:
+                  - type: string
+                  - type: integer
+                description: |-
+                  Machine-readable error code. Usually a string like
+                  `invalid_ref`, `missing_required_field`, or `unauthorized`;
+                  may be an **integer** when the error mirrors an upstream HTTP
+                  status (e.g. `500`) — most commonly returned by connection-ping
+                  and adaptor-proxy responses.
+              message:
+                type: string
+                description: Human-readable description of the error.
+              field:
+                type: string
+                description: |-
+                  Optional pointer to the document field that caused the error.
+                  Used by structural validation errors (`missing_required_field`,
+                  `invalid_ref`) to indicate which field is at fault
+                  (e.g. `_id`, `type`, `http.baseURI`).
+              source:
+                type: string
+                description: |-
+                  Optional origin layer for the error — e.g. `application` when
+                  the error came from the remote system the adaptor called,
+                  `connector` when the adaptor itself rejected the request.
+            required:
+              - message
+      required:
+        - errors
+    ApisUsageEntry:
+      type: object
+      description: |-
+        One month's invocation record for a single API-callable endpoint. Keyed by the
+        resource + HTTP method + relativeURI combination — the same export invoked via two HTTP methods
+        produces two separate entries.
+      properties:
+        _id:
+          type: string
+          format: objectId
+          description: Unique id of this usage record (not the resource id — see `metadata._resourceId`).
+          examples:
+            - 69d054b9be4ce14fb4112827
+        method:
+          type: string
+          enum:
+            - GET
+            - POST
+            - PUT
+            - PATCH
+            - DELETE
+          x-enumDescriptions:
+            GET: Retrieve data from the endpoint.
+            POST: Submit data to the endpoint.
+            PUT: Replace data at the endpoint.
+            PATCH: Partially update data at the endpoint.
+            DELETE: Remove data at the endpoint.
+          description: HTTP method the endpoint was called with.
+        relativeURI:
+          type: string
+          description: |-
+            The endpoint path (relative to `https://api.integrator.io`) that was invoked. Common shapes:
+            `/v1/exports/{_exportId}/invoke`, `/v1/imports/{_importId}/invoke`,
+            `/v1/connections/{_connectionId}/import` for virtual imports,
+            `/v1/apis/{_apiId}/request` for script-mode APIs, and
+            `/apis/v1/<relativeURI>` for builder-mode APIs.
+          examples:
+            - /v1/exports/6878f4a43bc01652c09cdccc/invoke
+        metadata:
+          type: object
+          description: Human-readable labeling of the resource behind this usage record.
+          properties:
+            _resourceId:
+              type: string
+              format: objectId
+              description: |-
+                Id of the underlying export, import, or API resource. Omitted for some resource types
+                (e.g. connection-scoped virtual imports) where the URL itself fully identifies the target.
+              examples:
+                - 6878f4a43bc01652c09cdccc
+            name:
+              type: string
+              description: Display name of the resource at the time of invocation.
+              examples:
+                - Get Contacts
+            type:
+              type: string
+              enum:
+                - export
+                - import
+                - virtualImport
+                - script
+                - apiBuilder
+              x-enumDescriptions:
+                export: A standard export resource invoked as an API endpoint.
+                import: A standard import resource invoked as an API endpoint.
+                virtualImport: A connection-scoped import embedded in a connector.
+                script: A script-mode API driven by custom JavaScript.
+                apiBuilder: A builder-mode API configured visually with request/response mappings.
+              description: |-
+                Resource flavor. `virtualImport` is a connection-scoped import (connector-embedded).
+                `script` is a script-mode API. `apiBuilder` is a builder-mode API.
+        month:
+          type: integer
+          minimum: 1
+          maximum: 12
+          description: Calendar month (1 = January) the counters cover.
+          examples:
+            - 4
+        year:
+          type: integer
+          description: Four-digit year the counters cover.
+          examples:
+            - 2026
+        ioInvocationCount:
+          type: integer
+          description: |-
+            Number of times the endpoint was invoked through integrator.io's own API front door. This is
+            the counter that bills against the subscription's API invocation entitlement.
+          examples:
+            - 29
+        apimInvocationCount:
+          type: integer
+          description: |-
+            Number of times the endpoint was invoked through an external API Management layer (APIM) in
+            front of integrator.io. Billed separately from `ioInvocationCount`.
+          examples:
+            - 0
+        createdAt:
+          type: string
+          format: date-time
+          description: When this monthly counter record was first created (the first invocation of the month).
+          examples:
+            - '2026-04-04T00:00:57.285Z'
+    ApisUsageResponse:
+      type: object
+      description: |-
+        Month-to-date invocation counters for every API endpoint that has been called in the account.
+        Returned by `GET /v1/apis/usage`. Each entry in `usages[]` represents one resource + method +
+        relativeURI triple — the same export or import invoked via two different methods yields two
+        entries. Counters are cumulative for the month named in `month` / `year` and reset on the 1st.
+      properties:
+        usages:
+          type: array
+          description: |-
+            Per-endpoint invocation records. Empty array when the account hasn't invoked any API endpoints
+            this month. Includes entries for every resource that can be invoked as an API —
+            custom APIs, individual exports/imports (`/v1/exports/{id}/invoke`, `/v1/imports/{id}/invoke`),
+            virtual imports, and script APIs.
+          items:
+            $ref: '#/components/schemas/ApisUsageEntry'
+        externalApimCount:
+          type: integer
+          description: |-
+            Account-wide count of invocations that arrived through an external API Management layer
+            (APIM) in front of integrator.io for the current month. Aggregate counterpart to the
+            per-endpoint `apimInvocationCount` values in `usages[]`. Absent on some responses when the
+            account has never been routed through an external APIM.
+          examples:
+            - 0
+    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'
+    ApiLogEntry:
+      type: object
+      description: |-
+        Summary row returned in the `GET /v1/apis/{_id}/logs` listing. Carries just enough to identify
+        each invocation (when it ran, how it ended) so the caller can pick which ones to inspect in
+        full via `GET /v1/apis/{_id}/logs/{key}`. Full request/response payloads are **not** in the
+        list — only in the detail fetch.
+      properties:
+        key:
+          type: string
+          description: |-
+            Opaque log key. Pass to `GET /v1/apis/{_id}/logs/{key}` to retrieve the full decoded
+            transaction. Structure is `<seq>-<id>-<status>-<method>` (e.g.
+            `5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST`). The embedded `<id>` also
+            appears as `id` on the detail response.
+          examples:
+            - 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST
+        time:
+          type: integer
+          format: int64
+          description: Epoch milliseconds when the invocation was handled.
+          examples:
+            - 1776917346304
+        method:
+          type: string
+          description: HTTP method of the inbound request (`GET`, `POST`, ...).
+          examples:
+            - POST
+        statusCode:
+          type: string
+          description: |-
+            HTTP status code the API returned to the caller, as a **string** (e.g. `"200"`). Note: on
+            the detail endpoint this same value is exposed as an integer under `response.statusCode` —
+            the list surfaces it as a string.
+          examples:
+            - '200'
+    ApiLogsResponse:
+      type: object
+      description: |-
+        Request log envelope returned by `GET /v1/apis/{_id}/logs`. Contains the recent API invocation
+        traces for the API identified by `_id`. The `requests[]` array is empty when no invocations
+        have been logged — either the API has never been called, or debug capture is off, or the
+        retention window has elapsed. Each entry is a full decoded request/response pair.
+      properties:
+        requests:
+          type: array
+          description: |-
+            Invocation summaries, newest first. Each entry has just `{key, time, method, statusCode}`;
+            the decoded request/response payload lives behind `GET /v1/apis/{_id}/logs/{key}`.
+          items:
+            $ref: '#/components/schemas/ApiLogEntry'
+    ApiLogDetail:
+      type: object
+      description: |-
+        Full decoded request/response envelope for one API invocation, returned by
+        `GET /v1/apis/{_id}/logs/{key}`. Sensitive header values (`authorization`, OAuth bearer tokens,
+        and similar) are masked with `********` before storage — the originals are not recoverable.
+        The `inputToResponseBubble` block reveals the Celigo-internal state handed to the
+        response-mapping stage; it's absent for script-mode APIs and pre-mapping failures.
+      properties:
+        time:
+          type: integer
+          format: int64
+          description: Epoch milliseconds when the invocation was handled.
+          examples:
+            - 1776917346304
+        request:
+          type: object
+          description: The inbound HTTP request the API received, as decoded by the runtime.
+          properties:
+            method:
+              type: string
+              description: HTTP method of the inbound request.
+              examples:
+                - POST
+            url:
+              type: string
+              description: |-
+                The path the caller hit, relative to `https://api.integrator.io`. Includes the API
+                `{version}` and the API's configured `relativeURI` (e.g. `/apis/v1/hubspot`).
+                Query-string credentials are masked before storage.
+              examples:
+                - /apis/v1/orders
+            httpVersion:
+              type: string
+              description: HTTP protocol version the caller negotiated (e.g. `1.1`, `2`).
+              examples:
+                - '1.1'
+            headers:
+              type: object
+              description: Inbound headers. The `authorization` header (and other credential headers) are masked.
+              additionalProperties:
+                type: string
+              example:
+                content-type: application/json
+                authorization: '********'
+                accept: application/json
+                host: api.integrator.io
+            queryParams:
+              type: object
+              description: Parsed query-string parameters. Empty object when none were sent.
+              additionalProperties: true
+            body:
+              type: string
+              description: |-
+                Request body as received, verbatim string (JSON payloads arrive already serialized —
+                parse with `JSON.parse` when you need structured data). Empty string for bodyless
+                methods.
+              examples:
+                - '{"orderId":"SO-1042","total":129.99}'
+            clientAddress:
+              type: string
+              description: |-
+                IP the request arrived from, as the Celigo edge saw it. IPv6 format; may be a
+                private/loopback address (e.g. `::ffff:127.0.0.6`) when routed through an internal
+                proxy rather than the public internet.
+              examples:
+                - ::ffff:127.0.0.6
+            size:
+              type: integer
+              description: Byte size the runtime recorded for the request. Often `0` — this field is not consistently populated.
+              examples:
+                - 0
+        response:
+          type: object
+          description: The outbound HTTP response the API produced.
+          properties:
+            statusCode:
+              type: integer
+              description: |-
+                HTTP status code returned to the caller, as an **integer** here. Note the list endpoint
+                (`GET /v1/apis/{_id}/logs`) exposes the same value as a string.
+              examples:
+                - 200
+            statusMessage:
+              type: string
+              description: HTTP status reason phrase (`OK`, `Bad Request`, ...).
+              examples:
+                - OK
+            headers:
+              type: object
+              description: Response headers sent to the caller.
+              additionalProperties:
+                type: string
+              example:
+                content-type: application/json
+                x-request-id: abc123def456
+            body:
+              type: string
+              description: Response body as sent. String form; parse as JSON/XML per the `content-type` header.
+              examples:
+                - '{"orderId":"SO-1042"}'
+            size:
+              type: integer
+              description: Byte size of the serialized response body.
+              examples:
+                - 21
+            responseTime:
+              type: integer
+              description: Total time in milliseconds from request arrival to response flush.
+              examples:
+                - 312
+        inputToResponseBubble:
+          type: object
+          description: |-
+            Builder-mode APIs only. Snapshot of the state handed to the response-mapping stage — the
+            parsed input records plus any execution/configuration errors collected along the pipeline.
+            Use this to debug response-mapping issues ("what did the mapper actually see?"). Absent on
+            script-mode APIs.
+          properties:
+            sourceRecord:
+              description: Array of records (or single-record object) that the response-mapper was given as input.
+            executionErrors:
+              type: array
+              description: Runtime errors raised during processing (e.g. script exceptions, lookup failures).
+              items:
+                type: object
+                additionalProperties: true
+            configurationErrors:
+              type: array
+              description: Configuration errors detected before execution (e.g. missing required mapping fields).
+              items:
+                type: object
+                additionalProperties: true
+        key:
+          type: string
+          description: Echoes the `key` path parameter. Same structure as in the list (`<seq>-<id>-<status>-<method>`).
+          examples:
+            - 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST
+        id:
+          type: string
+          description: |-
+            Shorter internal id for this log record. Appears embedded in the `key` string as the second
+            segment. Not independently useful to the caller, but handy for correlating with audit or
+            monitoring logs that reference only the short id.
+          examples:
+            - a10af1ade8fe477a847771c1e3716e36
+    ApiRequestLogEntry:
+      type: object
+      description: One logged API request execution in the run history.
+      required:
+        - executionId
+        - time
+        - method
+        - relativeURI
+        - statusCode
+        - timeTaken
+        - logMode
+      properties:
+        executionId:
+          type: string
+          description: |-
+            Identifier of this request execution (20-character lowercase hex).
+            Pass it to `GET /v1/apis/{_id}/requests/{executionId}` to open the
+            trace view when `logMode` is `detailed` or `debug`.
+          examples:
+            - a1b2c3d4e5f678901234
+        time:
+          type: string
+          format: date-time
+          description: When the request was received (UTC).
+          examples:
+            - '2026-05-15T13:42:11.234Z'
+        method:
+          type: string
+          description: HTTP method of the request.
+          examples:
+            - POST
+        relativeURI:
+          type: string
+          description: Path of the request, without scheme or host.
+          examples:
+            - /orders
+        statusCode:
+          type: integer
+          description: HTTP status code the API responded with.
+          examples:
+            - 200
+        traceKey:
+          type: string
+          description: Correlation/trace key resolved for this request.
+          examples:
+            - trace-abc-123
+        remoteIP:
+          type: string
+          description: Client IP address the request came from.
+          examples:
+            - 192.168.1.5
+        timeTaken:
+          type: number
+          description: Processing time in milliseconds.
+          examples:
+            - 142.7
+        logMode:
+          type: string
+          enum:
+            - basic
+            - standard
+            - detailed
+            - debug
+          x-enumDescriptions:
+            basic: Request metadata only — no per-step trace data.
+            standard: Request metadata plus summary step information.
+            detailed: Full per-step trace logs, queryable via the trace view.
+            debug: Temporary full-capture mode active while `logging.debugUntil` is in the future.
+          description: |-
+            Logging mode that was active when this request was processed.
+            Determines trace availability — only `detailed` and `debug` produce
+            per-step trace logs. Requests processed with `no_logging` produce no
+            run-history rows at all.
+          examples:
+            - detailed
+    ApiRunHistoryResponse:
+      type: object
+      description: Paginated API request run history.
+      required:
+        - requests
+      properties:
+        requests:
+          type: array
+          description: Logged request executions, newest first by default.
+          items:
+            $ref: '#/components/schemas/ApiRequestLogEntry'
+        nextPageUrl:
+          type:
+            - string
+            - 'null'
+          description: |-
+            URL to fetch the next page (carries the `next` cursor and
+            `cursorExecutionId` tie-breaker); null when there is no next page.
+          examples:
+            - https://api.integrator.io/v1/apis/685021eda02a61042cee80ab/requests?pageSize=50&next=2026-05-15T13:42:11.234Z&cursorExecutionId=a1b2c3d4e5f678901234
+        prevPageUrl:
+          type:
+            - string
+            - 'null'
+          description: URL to fetch the previous page; null when there is no previous page.
+    ApiRequestTraceStep:
+      type: object
+      description: A step within an API request execution trace.
+      required:
+        - status
+        - timeTaken
+        - groupId
+        - recordId
+        - time
+      properties:
+        _expOrImpId:
+          type: string
+          description: |-
+            Export, import, or builder resource-step identifier (`resStepId`) for
+            the step. Builder bubble stages use the resource-step identifier
+            rather than a MongoDB ObjectId.
+          examples:
+            - 67ee026136f4d1eeb529ad63
+        status:
+          type: string
+          enum:
+            - success
+            - error
+            - ignore
+          x-enumDescriptions:
+            success: Record processed successfully
+            error: Record failed processing
+            ignore: Record was skipped during processing
+          description: Outcome status of the step.
+          examples:
+            - success
+        stage:
+          type: string
+          description: Processing stage; present when `status` is `error` or `ignore`.
+          examples:
+            - mapping
+        timeTaken:
+          type: number
+          description: Step processing time in milliseconds.
+          examples:
+            - 142
+        groupId:
+          type: string
+          description: Group identifier for the step's records.
+          examples:
+            - 6449f2
+        recordId:
+          type: string
+          description: Identifier of this record.
+          examples:
+            - 4a8e5c
+        parentRecordId:
+          type: string
+          description: Identifier of the parent record when this step is a child row.
+          examples:
+            - a1b2c3
+        time:
+          type: string
+          format: date-time
+          description: Timestamp when the step ran (UTC).
+          examples:
+            - '2026-05-15T13:42:11.234Z'
+      additionalProperties: true
+    ApiTraceMetadataResponse:
+      type: object
+      description: Top-level execution steps for the trace view of an API request.
+      required:
+        - steps
+      properties:
+        steps:
+          type: array
+          description: Top-level execution steps for the trace view.
+          items:
+            $ref: '#/components/schemas/ApiRequestTraceStep'
+    ApiRequestChildrenResponse:
+      type: object
+      description: Paginated child records under a parent record in an API request trace.
+      required:
+        - children
+      properties:
+        children:
+          type: array
+          description: Child step records (lookup / one-to-many expansions).
+          items:
+            $ref: '#/components/schemas/ApiRequestTraceStep'
+        nextPageUrl:
+          type:
+            - string
+            - 'null'
+          description: URL to fetch the next page; null when there is no next page.
+        prevPageUrl:
+          type:
+            - string
+            - 'null'
+          description: URL to fetch the previous page; null when there is no previous page.
+    ApiLogDataRequest:
+      type: object
+      description: |-
+        Query payload for retrieving decoded log data for a step within an API
+        request execution. Same shape as the flow log-data query; for API Builder
+        steps, `_expOrImpId` may be a MongoDB ObjectId or a builder resource-step
+        identifier (`resStepId`).
+      required:
+        - _expOrImpId
+        - stage
+        - groupId
+        - recordId
+      properties:
+        _expOrImpId:
+          type: string
+          description: Export, import, or builder resource-step identifier for the step.
+          examples:
+            - 67ee026136f4d1eeb529ad63
+        stage:
+          type: string
+          description: Processing stage to fetch data for.
+          examples:
+            - mapping
+        groupId:
+          type: string
+          description: Group identifier for the step's records.
+          examples:
+            - grp-001
+        recordId:
+          type: string
+          description: Identifier of the record to fetch.
+          examples:
+            - rec-123
+    ApiLogDataResponse:
+      type: object
+      description: Decoded log payload for a step, plus any collected error metadata.
+      required:
+        - logs
+        - errors
+      properties:
+        logs:
+          type: array
+          description: |-
+            Decoded log payload entries for the step. Large payloads are not inlined —
+            such an entry carries an `externalReference[]`, each with a `source.s3Key`;
+            pass that key to `GET /v1/apis/{_id}/requests/{executionId}/logs/signedURL`
+            to download the full content.
+          items:
+            type: object
+            properties:
+              externalReference:
+                type: array
+                description: References to externally stored payload content, present for large payloads.
+                items:
+                  type: object
+                  properties:
+                    source:
+                      type: object
+                      description: Location of the externally stored content.
+                      properties:
+                        s3Key:
+                          type: string
+                          description: Relative key to pass to the signed-URL endpoint.
+                      additionalProperties: true
+                  additionalProperties: true
+            additionalProperties: true
+        errors:
+          type: array
+          description: Error metadata collected while resolving the payload.
+          items:
+            type: object
+            additionalProperties: true
+    ApiSignedUrlResponse:
+      type: object
+      description: A short-lived signed URL for downloading a stored API request log payload object.
+      required:
+        - signedURL
+      properties:
+        signedURL:
+          type: string
+          description: Time-limited signed URL (about 120 seconds) to download the referenced log object.
+          examples:
+            - https://integrator-userdata-delete-30.s3.amazonaws.com/api-execution-logs/user/api/exec/group/file.log?Expires=1754046196&Signature=...
+    DependencyEntry:
+      type: object
+      description: A single resource that depends on the queried resource.
+      properties:
+        id:
+          type: string
+          description: Unique identifier of the dependent resource.
+          examples:
+            - 61f92026dd053843b5d72350
+        name:
+          type: string
+          description: Display name of the dependent resource.
+          examples:
+            - Import Orders to NetSuite
+        paths:
+          type: array
+          description: |-
+            Dot-notation paths within the dependent resource that reference
+            the target resource. `[*]` denotes array elements.
+          items:
+            type: string
+          examples:
+            - - hooks.preSavePage._scriptId
+        accessLevel:
+          type: string
+          description: The caller's access level on the dependent resource.
+          examples:
+            - manage
+        dependencyIds:
+          type: object
+          description: |-
+            Map of resource types to arrays of IDs that this dependent
+            resource references on the target. Keys are singular or plural
+            resource type strings; values are arrays of ID strings.
+          additionalProperties:
+            type: array
+            items:
+              type: string
+          example:
+            script:
+              - 64ff4b21612a134bd2f45531
+      required:
+        - id
+        - name
+        - paths
+        - accessLevel
+        - dependencyIds
+    DependencyResponse:
+      type: object
+      description: |
+        Map of dependent-resource types to arrays of dependency entries.
+        Keys are plural resource type strings (e.g. `flows`, `imports`,
+        `connections`). An empty object `{}` means no dependents.
+      additionalProperties:
+        type: array
+        items:
+          $ref: '#/components/schemas/DependencyEntry'
+      example:
+        exports:
+          - id: 64ff4b21612a134bd2f45534
+            name: Bank FTP Export
+            paths:
+              - hooks.preSavePage._scriptId
+            accessLevel: manage
+            dependencyIds:
+              script:
+                - 64ff4b21612a134bd2f45531
+        flows:
+          - id: 64ff4b22612a134bd2f45538
+            name: CAMT-053 to Celigo CAM Format
+            paths:
+              - pageGenerators[*]._exportId
+            accessLevel: manage
+            dependencyIds:
+              export:
+                - 64ff4b21612a134bd2f45534
+  responses:
+    401-unauthorized:
+      description: |-
+        Unauthorized. The request lacks a valid bearer token, or the provided token
+        failed to authenticate.
+
+        Note: the 401 response is produced by the auth middleware **before** the
+        request reaches the endpoint handler, so it does **not** follow the
+        standard `{errors: [...]}` envelope. Instead the body is a bare
+        `{message: string}` object with no `code`, no `errors` array. Callers
+        handling 401s should key off the HTTP status and the `message` string,
+        not try to destructure an `errors[]`.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                description: |-
+                  Human-readable description of the auth failure. Known values:
+                  - `"Unauthorized"` — no `Authorization` header on the request.
+                  - `"Bearer Authentication Failed"` — header present but token
+                    is invalid, revoked, or expired.
+            required:
+              - message
+          examples:
+            missing_token:
+              summary: No Authorization header sent
+              value:
+                message: Unauthorized
+            invalid_token:
+              summary: Bearer token invalid or revoked
+              value:
+                message: Bearer Authentication Failed
+    400-bad-request:
+      description: |
+        Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: invalid_request
+                    message: The request body failed validation.
+    422-unprocessable-entity:
+      description: |
+        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: unprocessable_entity
+                    message: The request could not be processed due to a semantic error.
+    404-not-found:
+      description: |
+        Not found. The requested resource does not exist or is not visible to the caller.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: not_found
+                    message: The requested resource was not found.
+    403-forbidden:
+      description: |
+        Forbidden. The authenticated caller does not have permission to perform this operation.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: forbidden
+                    message: You do not have permission to access this resource.
+x-enable-proxy: true
+x-internal: false