@celigo/api-specs 0.2.19 → 0.2.21

package/dist/tool.yml

@@ -382,6 +382,86 @@ paths:
         - |-
           Updates an existing tool with the provided configuration.
           This is used for major updates to a tool's structure or behavior.
+    patch:
+      x-internal: false
+      summary: Patch a tool
+      description: |-
+        Partially updates a tool using a JSON Patch document (RFC 6902).
+        The `add`, `remove`, `replace`, and `move` operations are supported
+        (`copy` and `test` are rejected), and only on the following whitelisted
+        paths:
+
+        | Path | Description |
+        |------|-------------|
+        | `/name` | Tool display name |
+        | `/description` | Tool description |
+        | `/aiDescription` | AI-generated description object |
+        | `/input/debugUntil` | Tool Input debug capture expiry (ISO-8601, at most 1 hour in the future; 422 beyond the cap) |
+        | `/output/debugUntil` | Tool Output debug capture expiry (ISO-8601, at most 1 hour in the future; 422 beyond the cap) |
+
+        All other paths are rejected with 422 (`not a whitelisted property`).
+
+        PATCH is the intended way to update these fields without accidentally
+        resetting other tool configuration via `PUT`. In particular, it is how
+        you arm and disarm step debug capture: `replace` `/input/debugUntil` or
+        `/output/debugUntil` with a future ISO timestamp to start capturing, or
+        a past timestamp to stop. While armed, captured logs are readable at
+        `GET /v1/tools/{_id}/tool_input/requests` and
+        `GET /v1/tools/{_id}/tool_output/requests`.
+      operationId: patchTool
+      tags:
+        - Tools
+      parameters:
+        - name: _id
+          in: path
+          description: The unique identifier of the tool
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: tools
+            examples:
+              - 69d462d5b9c28ea0b7f82522
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/JsonPatchRequest'
+            examples:
+              rename:
+                summary: Rename a tool
+                value:
+                  - op: replace
+                    path: /name
+                    value: Updated Tool Name
+              update_description:
+                summary: Update tool description
+                value:
+                  - op: replace
+                    path: /description
+                    value: Updated tool description
+              arm_input_debug:
+                summary: Arm input debug capture for 30 minutes
+                value:
+                  - op: replace
+                    path: /input/debugUntil
+                    value: '2026-08-25T12:30:00.000Z'
+              disarm_output_debug:
+                summary: Disarm output debug capture
+                value:
+                  - op: replace
+                    path: /output/debugUntil
+                    value: '2020-01-01T00:00:00.000Z'
+      responses:
+        '204':
+          description: Tool patched successfully.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
     delete:
       x-internal: false
       summary: Delete a tool
@@ -1348,12 +1428,20 @@ paths:
       summary: List captured debug requests for a tool step
       description: |-
         Lists the debug request records captured for a specific step of a tool.
-        These are the raw outbound requests the step issued, retained for
-        troubleshooting. Use the `key` of an entry with
-        `GET /v1/tools/{_id}/{_stepId}/requests/{key}` to fetch the full detail
-        of a single captured request.
+        These are the raw request/response payloads the step processed, retained
+        for troubleshooting while debug capture is active for the step. Use the
+        `key` of an entry with `GET /v1/tools/{_id}/{_stepId}/requests/{key}` to
+        fetch the full detail of a single captured request.
+
+        When more records match than fit in one page, `nextPageURL` returns the
+        relative URL for the next page.
 
-        Returns `{requests: []}` when the step has captured no debug requests.
+        **Important:** Time parameters (`time_lte`, `time_gt`) must be epoch
+        milliseconds (integers), not ISO 8601 strings. When `time_lte` is
+        provided, `time_gt` is also required.
+
+        Requires the `manage:tool:logs` permission. Returns `{requests: []}` when
+        the step has captured no debug requests.
       operationId: listToolStepRequests
       tags:
         - Tools
@@ -1372,14 +1460,91 @@ paths:
           in: path
           required: true
           description: |-
-            Export or import step id whose captured debug requests you want. Must be a
-            step ObjectId — reserved path segments such as `invocations`, `invoke`, and
-            `test` are not valid step ids.
+            The step whose captured logs to list. Either the ObjectId of an
+            export or import step defined directly in this tool's routers, or one
+            of the virtual step ids `tool_input` / `tool_output` (logs captured
+            via `input.debugUntil` / `output.debugUntil`). Steps nested inside a
+            child tool are addressed on that child tool's id. Reserved path
+            segments such as `invocations`, `invoke`, and `test` are not valid
+            step ids.
           schema:
             type: string
-            format: objectId
             examples:
               - 67ee026136f4d1eeb529ad63
+              - tool_input
+              - tool_output
+        - name: time_gt
+          in: query
+          required: false
+          description: |-
+            Lower bound of the time window (exclusive), as epoch milliseconds.
+            Required when `time_lte` is provided.
+          schema:
+            type: integer
+            format: int64
+            examples:
+              - 1776917000000
+        - name: time_lte
+          in: query
+          required: false
+          description: |-
+            Upper bound of the time window (inclusive), as epoch milliseconds.
+            Defaults to now if omitted. When provided, `time_gt` is also required.
+          schema:
+            type: integer
+            format: int64
+            examples:
+              - 1776917346304
+        - name: method
+          in: query
+          required: false
+          description: |-
+            Only return records with these HTTP methods. Repeat the parameter to
+            filter on multiple values.
+          style: form
+          explode: true
+          schema:
+            type: array
+            items:
+              type: string
+            examples:
+              - - POST
+                - GET
+        - name: statusCode
+          in: query
+          required: false
+          description: |-
+            Only return records with these response status codes. Repeat the
+            parameter to filter on multiple values.
+          style: form
+          explode: true
+          schema:
+            type: array
+            items:
+              type: string
+            examples:
+              - - '200'
+                - '422'
+        - name: stage
+          in: query
+          required: false
+          description: |-
+            Only return records for these processing stages. Repeat the parameter
+            to filter on multiple values.
+          style: form
+          explode: true
+          schema:
+            type: array
+            items:
+              type: string
+        - name: nextPageToken
+          in: query
+          required: false
+          description: |-
+            Continuation token for pagination. Do not construct this manually —
+            follow the `nextPageURL` returned by the previous page instead.
+          schema:
+            type: string
       responses:
         '200':
           description: |-
@@ -1396,7 +1561,31 @@ paths:
                     description: Captured debug request records.
                     items:
                       type: object
+                      description: Summary of one captured debug request.
+                      properties:
+                        key:
+                          type: string
+                          description: |-
+                            Identifier of the captured record; pass it to
+                            `GET /v1/tools/{_id}/{_stepId}/requests/{key}`.
+                        time:
+                          type: integer
+                          description: Capture time as epoch milliseconds.
+                        method:
+                          type: string
+                          description: HTTP method of the captured request.
+                        statusCode:
+                          type: string
+                          description: Response status code of the captured request.
+                        stage:
+                          type: string
+                          description: Processing stage the record was captured in.
                       additionalProperties: true
+                  nextPageURL:
+                    type: string
+                    description: |-
+                      Relative URL of the next page. Present only when more
+                      records match than were returned.
                 required:
                   - requests
               examples:
@@ -1404,8 +1593,148 @@ paths:
                   summary: No debug requests captured
                   value:
                     requests: []
+                populated:
+                  summary: Captured debug requests for a tool step
+                  value:
+                    requests:
+                      - key: 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST
+                        time: 1776917346304
+                        method: POST
+                        statusCode: '200'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          description: 'Invalid time filter parameters. Error code: `invalid_or_missing_field`.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_time:
+                  value:
+                    errors:
+                      - code: invalid_or_missing_field
+                        message: time_lte must be an epoch millisecond value, not an ISO string.
+                missing_time_gt:
+                  value:
+                    errors:
+                      - code: invalid_or_missing_field
+                        message: 'Invalid or Missing Field: time_gt'
+    delete:
+      x-internal: false
+      summary: Delete captured debug requests for a tool step
+      description: |-
+        Deletes captured debug request records for a specific step of a tool, by
+        their `key` values from `GET /v1/tools/{_id}/{_stepId}/requests`. Between
+        1 and 1000 keys can be deleted per call.
+
+        The response lists the keys that were deleted and, separately, any keys
+        that failed to delete along with the failure reason.
+
+        Requires the `manage:tool:logs:deletion` permission.
+      operationId: deleteToolStepRequests
+      tags:
+        - Tools
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: The unique identifier of the tool.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: tools
+            examples:
+              - 69d462d5b9c28ea0b7f82522
+        - name: _stepId
+          in: path
+          required: true
+          description: |-
+            The step whose captured logs to delete. Either the ObjectId of an
+            export or import step defined directly in this tool's routers, or one
+            of the virtual step ids `tool_input` / `tool_output` (logs captured
+            via `input.debugUntil` / `output.debugUntil`).
+          schema:
+            type: string
+            examples:
+              - 67ee026136f4d1eeb529ad63
+              - tool_input
+              - tool_output
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              description: Keys of the captured debug requests to delete.
+              properties:
+                keys:
+                  type: array
+                  description: |-
+                    Keys of the records to delete, from the
+                    `GET /v1/tools/{_id}/{_stepId}/requests` listing.
+                  minItems: 1
+                  maxItems: 1000
+                  items:
+                    type: string
+              required:
+                - keys
+            examples:
+              default:
+                summary: Delete two captured debug requests
+                value:
+                  keys:
+                    - 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST
+                    - 5481201048878-b21bf2bef9ff588b958882d2f4827f47-422-POST
+      responses:
+        '200':
+          description: |-
+            Deletion outcome. `deleted` lists the removed keys; `errors` lists
+            keys that could not be removed with the failure reason.
+          content:
+            application/json:
+              schema:
+                type: object
+                description: Deletion result envelope.
+                properties:
+                  deleted:
+                    type: array
+                    description: Keys of the records that were deleted.
+                    items:
+                      type: string
+                  errors:
+                    type: array
+                    description: Records that failed to delete.
+                    items:
+                      type: object
+                      properties:
+                        key:
+                          type: string
+                          description: Key of the record that failed to delete.
+                        error:
+                          type: string
+                          description: Failure reason.
+                required:
+                  - deleted
+                  - errors
+              examples:
+                default:
+                  summary: All requested records deleted
+                  value:
+                    deleted:
+                      - 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST
+                      - 5481201048878-b21bf2bef9ff588b958882d2f4827f47-422-POST
+                    errors: []
+        '400':
+          $ref: '#/components/responses/400-bad-request'
         '401':
           $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
         '404':
           $ref: '#/components/responses/404-not-found'
   /v1/tools/{_id}/{_stepId}/requests/{key}:
@@ -1416,6 +1745,14 @@ paths:
         Returns the full detail of a single captured debug request for a tool
         step, identified by its `key`. Obtain the `key` from
         `GET /v1/tools/{_id}/{_stepId}/requests`.
+
+        The record carries the captured request/response payloads for the step,
+        plus the `key`, record `id`, and capture `time`. For `tool_input`,
+        `tool_output`, and ToolImport steps the stored body is the in-memory JSON
+        record (not adaptor-masked). Router Import/Export bubbles keep existing
+        adaptor masking.
+
+        Requires the `manage:tool:logs` permission.
       operationId: getToolStepRequest
       tags:
         - Tools
@@ -1434,14 +1771,19 @@ paths:
           in: path
           required: true
           description: |-
-            Export or import step id the captured request belongs to. Must be a step
-            ObjectId — reserved path segments such as `invocations`, `invoke`, and
-            `test` are not valid step ids.
+            The step the captured request belongs to. Either the ObjectId of an
+            export or import step defined directly in this tool's routers, or one
+            of the virtual step ids `tool_input` / `tool_output` (logs captured
+            via `input.debugUntil` / `output.debugUntil`). Steps nested inside a
+            child tool are addressed on that child tool's id. Reserved path
+            segments such as `invocations`, `invoke`, and `test` are not valid
+            step ids.
           schema:
             type: string
-            format: objectId
             examples:
               - 67ee026136f4d1eeb529ad63
+              - tool_input
+              - tool_output
         - name: key
           in: path
           required: true
@@ -1457,18 +1799,131 @@ paths:
             application/json:
               schema:
                 type: object
-                description: A single captured debug request record.
+                description: |-
+                  A single captured debug request record, including the captured
+                  request/response payloads.
+                properties:
+                  key:
+                    type: string
+                    description: Echoes the `key` path parameter.
+                  id:
+                    type: string
+                    description: Internal storage id parsed from the log filename.
+                  time:
+                    type: integer
+                    format: int64
+                    description: Epoch milliseconds when this pair was stored.
+                  request:
+                    type: object
+                    description: |-
+                      The captured request envelope. Synthetic `tool_input` /
+                      `tool_output` / ToolImport logs store the in-memory JSON
+                      record; router Import/Export bubbles store the adaptor HTTP
+                      request.
+                    properties:
+                      method:
+                        type: string
+                        description: HTTP method (`GET`, `POST`, …). Synthetic captures use `POST`.
+                        examples:
+                          - POST
+                      url:
+                        type: string
+                        description: |-
+                          Fully-resolved URL sent. Present on adaptor HTTP
+                          captures; omitted on synthetic `tool_input` /
+                          `tool_output` / ToolImport logs.
+                      headers:
+                        type: object
+                        description: |-
+                          Headers sent with the request. Adaptor HTTP captures
+                          mask credentials; synthetic captures have no adaptor
+                          masking.
+                        additionalProperties: true
+                      body:
+                        description: |-
+                          Captured request payload. Object for synthetic
+                          `tool_input` / `tool_output` / ToolImport logs (the
+                          in-memory JSON record). String for adaptor HTTP
+                          router-bubble captures.
+                  response:
+                    type: object
+                    description: The captured response envelope.
+                    properties:
+                      statusCode:
+                        type: integer
+                        description: HTTP status code (`200` on success, `422` on schema/transform failure for synthetic captures).
+                        examples:
+                          - 200
+                      headers:
+                        type: object
+                        description: Response headers. Empty object on synthetic captures that did not issue HTTP.
+                        additionalProperties: true
+                      body:
+                        description: |-
+                          Captured response payload. Object for synthetic
+                          `tool_input` / `tool_output` / ToolImport logs. String
+                          for adaptor HTTP router-bubble captures.
+                      receivedAt:
+                        type: integer
+                        format: int64
+                        description: Epoch milliseconds when this pair was captured. Present on synthetic logs.
+                  context:
+                    type: object
+                    description: |-
+                      Run correlation for synthetic logs keyed by tool id. Present
+                      on `tool_input` / `tool_output` / ToolImport captures so the
+                      originating flow or job can be recovered; omitted on adaptor
+                      HTTP router-bubble logs.
+                    properties:
+                      _rootContainerId:
+                        type: string
+                        description: Owning flow, API, or tool id of the run that produced this capture.
+                      _jobId:
+                        type: string
+                        description: Job id of the run that produced this capture.
                 additionalProperties: true
               examples:
-                default:
-                  summary: One captured debug request
+                adaptor_http:
+                  summary: Router-bubble HTTP capture
+                  value:
+                    key: 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST
+                    id: a10af1ade8fe477a847771c1e3716e36
+                    time: 1776917346304
+                    request:
+                      method: POST
+                      url: https://httpbin.org/post
+                      headers:
+                        content-type: application/json
+                      body: '{"orderId":"SO-1042"}'
+                    response:
+                      statusCode: 200
+                      headers:
+                        content-type: application/json
+                      body: '{"ok":true}'
+                tool_input:
+                  summary: Synthetic Tool Input capture
                   value:
-                    key: 6a2e23bbcf5b64ca6b93b774
-                    method: POST
-                    url: https://httpbin.org/post
-                    statusCode: 200
+                    key: 5481201053696-b20bf2bde8fe477a847771c1e3716e36-200-POST
+                    id: b20bf2bde8fe477a847771c1e3716e36
+                    time: 1776917346304
+                    request:
+                      method: POST
+                      headers: {}
+                      body:
+                        customerId: CUST-1001
+                    response:
+                      statusCode: 200
+                      headers: {}
+                      receivedAt: 1776917346304
+                      body:
+                        customerId: CUST-1001
+                        validated: true
+                    context:
+                      _jobId: 69d462d5b9c28ea0b7f82533
         '401':
           $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
         '404':
           $ref: '#/components/responses/404-not-found'
 components:
@@ -3894,6 +4349,18 @@ components:
                   format: email
         transform:
           $ref: '#/components/schemas/Transform'
+        debugUntil:
+          type: string
+          format: date-time
+          description: |
+            Enables debug capture for the tool input stage until this timestamp.
+            While it is in the future, invocations write input-stage
+            request/response logs, listed at
+            `GET /v1/tools/{_id}/tool_input/requests`. At most 1 hour in the
+            future. A past timestamp (or omitting the field) stops capture.
+            Arm/disarm with `PATCH /v1/tools/{_id}` path `/input/debugUntil`.
+          examples:
+            - '2026-08-25T12:30:00.000Z'
         mockInput:
           type: object
           description: |
@@ -4039,6 +4506,18 @@ components:
                   examples:
                     - postProcessOutput
                     - validateOutput
+        debugUntil:
+          type: string
+          format: date-time
+          description: |
+            Enables debug capture for the tool output stage until this timestamp.
+            While it is in the future, invocations write output-stage
+            request/response logs, listed at
+            `GET /v1/tools/{_id}/tool_output/requests`. At most 1 hour in the
+            future. A past timestamp (or omitting the field) stops capture.
+            Arm/disarm with `PATCH /v1/tools/{_id}` path `/output/debugUntil`.
+          examples:
+            - '2026-08-25T12:30:00.000Z'
         mockInput:
           type: object
           description: |
@@ -4597,6 +5076,41 @@ components:
               - message
       required:
         - errors
+    JsonPatchOperation:
+      type: object
+      description: A single JSON Patch operation (RFC 6902).
+      required:
+        - op
+        - path
+      properties:
+        op:
+          type: string
+          enum:
+            - replace
+            - add
+            - remove
+          x-enumDescriptions:
+            replace: Replaces the value at the specified path.
+            add: Sets the value at the specified path.
+            remove: Removes the value at the specified path.
+          description: The operation to perform.
+        path:
+          type: string
+          description: |-
+            JSON Pointer (RFC 6901) to the field to patch. Only
+            whitelisted paths are accepted — unlisted paths return
+            `422` with `"<path> is not a whitelisted property"`.
+        value:
+          description: The new value to set. Required for `replace` and `add`, omit for `remove`.
+    JsonPatchRequest:
+      type: array
+      description: |-
+        A JSON Patch document (RFC 6902). Send an array of patch
+        operations on whitelisted fields — all other paths are rejected
+        with 422.
+      minItems: 1
+      items:
+        $ref: '#/components/schemas/JsonPatchOperation'
     IAResourceResponse:
       type: object
       description: Integration app response fields for resources that are part of integration apps
@@ -4887,11 +5401,13 @@ components:
                 When true, rate-limit errors from the target system trigger automatic recovery: concurrency
                 drops to 1, the rate-limited requests are retried with doubling waits (1 to 1024 minutes,
                 after which the flag switches itself off), and concurrency climbs back toward
-                `targetConcurrencyLevel`. While true, `concurrencyLevel` is platform-managed and writes to
-                it are ignored — `targetConcurrencyLevel` is the lever.
+                `targetConcurrencyLevel`. While true, `targetConcurrencyLevel` is the throughput lever: a
+                `concurrencyLevel` sent in a PUT is ignored, and one sent in a PATCH is stored but the
+                recovery machinery moves it back toward the target.
               x-celigo-ai-guidance:
-                - To change throughput while this is true, write `targetConcurrencyLevel`; a `concurrencyLevel` write returns 200 and changes nothing.
-                - Turning it on copies `concurrencyLevel` into `targetConcurrencyLevel`; turning it off copies the target back into `concurrencyLevel` and unsets the target.
+                - To change throughput while this is true, write `targetConcurrencyLevel`; a `concurrencyLevel` sent in a PUT returns 200 and changes nothing.
+                - Turning it on copies `concurrencyLevel` into `targetConcurrencyLevel`; turning it off unsets the target and leaves `concurrencyLevel` at its current value, which may be below the old target if a recovery was in progress. A `targetConcurrencyLevel` written while this is false is unset by the save.
+                - These four settings (`concurrencyLevel`, `targetConcurrencyLevel`, `_borrowConcurrencyFromConnectionId`, this flag) accept a credential-free `PATCH /v1/connections/{_id}`. A PUT must re-send the credentials — omitting them or echoing their masked `******` values clears them.
             enableMicroBatchForOneToMany:
               type: boolean
               default: true
@@ -6168,7 +6684,7 @@ components:
             Higher values increase throughput but may trigger API rate limits.
             Set this based on the target API's rate limit documentation.
             Values above the account's licensed maximum (25 standard, 50 with an Environments license) are silently clamped down.
-            Platform-managed while `autoRecoverRateLimitErrors` is true — writes are ignored; set `targetConcurrencyLevel` instead.
+            Platform-managed while `autoRecoverRateLimitErrors` is true — a PUT ignores the value and the recovery machinery moves it toward the target; set `targetConcurrencyLevel` instead.
           minimum: 1
           maximum: 50
           default: 25
@@ -16602,7 +17118,7 @@ components:
         For most file imports, you need at minimum:
         - `fileName`: The output file name (supports Handlebars like `{{timestamp}}`)
         - `type`: The file format (json, csv, xml, xlsx)
-        - `skipAggregation`: Usually `false` for standard imports
+        - `aggregation.type`: How the run's records are batched into files (`all` for one file per run)
 
         **Example (S3 Import)**
 
@@ -16610,7 +17126,7 @@ components:
         {
           "file": {
             "fileName": "customers-{{timestamp}}.json",
-            "skipAggregation": false,
+            "aggregation": { "type": "all" },
             "type": "json"
           },
           "s3": {
@@ -16652,18 +17168,22 @@ components:
         skipAggregation:
           type: boolean
           description: |-
-            Controls whether records are aggregated into a single file or processed individually.
-
-            **Values**
-            - `false` (DEFAULT): Records are aggregated into a single output file
-            - `true`: Each record is written as a separate file
-
-            **When to use**
-            - **`false`**: Standard batch imports where all records go into one file
-            - **`true`**: When each record needs its own file (e.g., individual documents)
-
-            **Default:** `false`
+            Legacy companion of `aggregation.type`: `true` when the run's records are written one
+            file per page, `false` when they are combined across the run or grouped by key.
+            Validation reads the value sent — an EDI file definition needs `true` unless
+            `aggregation.type` is `key`, and `batchSize` needs `true` — then the save rewrites it
+            from `aggregation.type`, so send the two as a consistent pair.
           default: false
+          x-celigo-ai-guidance:
+            - |-
+              Send `skipAggregation` and `aggregation.type` as a consistent pair, exactly as the UI
+              does: `page` with `true`; `all` or `key` with `false`. Validation reads the SENT flag —
+              a `file.type: filedefinition` import saved with `page` and no `skipAggregation: true`
+              fails with 422 `not_supported` ("Aggregation is not supported for EDI files, please set
+              skipAggregation to true in Imports"), and `batchSize` fails with 422 `not_supported`
+              ("File imports do not support batching with aggregation") unless the sent flag is
+              `true`. The SAVED flag is then derived from `aggregation.type`, so this flag alone never
+              says which mode is active — read `aggregation.type`. It does not mean one file per record.
         type:
           type: string
           enum:
@@ -16769,7 +17289,15 @@ components:
             - When target system has file size limitations
 
             **Note**
-            - Only applicable when `skipAggregation` is `true`
+            - Offered when records are written one file per page (`aggregation.type: page` with
+              `skipAggregation: true`)
+          x-celigo-ai-guidance:
+            - |-
+              Probed for `all` and `page`: the save rejects `batchSize` with 422 `not_supported`
+              ("File imports do not support batching with aggregation") when the sent
+              `skipAggregation` is not `true`, and accepts it with `page` + `skipAggregation: true`.
+              The `key` + `batchSize` combination has not been probed (it needs a B2B Manager
+              account) — treat it as unverified, neither allowed nor forbidden.
         encrypt:
           type: boolean
           description: |-
@@ -16875,21 +17403,45 @@ components:
         aggregation:
           type: object
           description: |-
-            Controls how records are batched into output files. Newer imports use this object; the
-            legacy skipAggregation flag is the older equivalent.
+            Controls how a flow run's records are batched into output files — the transfer form's
+            "How many files would you like to generate?" setting. The legacy `skipAggregation` flag
+            mirrors `type` and is maintained by the platform.
           properties:
             type:
               type: string
               enum:
                 - all
                 - page
+                - key
               x-enumDescriptions:
-                all: Aggregate every record from the flow run into a single output file.
-                page: Write one output file per page of records.
-              description: Whether all records across the flow run go to one file, or one file is written per page.
+                all: One file per flow run — every record from the run (per export, or per request on real-time flows) in a single file
+                page: One file per page of records
+                key: One file per aggregation key — EDI file definitions only; records sharing the key derived from the file definition's document type are combined into one document
+              description: |-
+                Which batches of a run's records become separate output files. EDI file definitions
+                (`file.type: filedefinition`) are written per page or per key, never per run; `key`
+                is accepted only for them and only when the account has B2B Manager. The grouping
+                key and the line-item loop it merges come from the EDI file definition's document
+                type, so there is no separate key field to configure.
               examples:
                 - all
                 - page
+                - key
+              x-celigo-ai-guidance:
+                - |-
+                  Validated on save: an unknown value fails with 422 `enum`; `key` fails with 422
+                  `not_supported` unless `file.type` is `filedefinition` ("Aggregation type key is
+                  only supported for file type filedefinition") and the account has B2B Manager
+                  ("Aggregation type key is only supported for B2B Manager").
+                - |-
+                  For `file.type: filedefinition` send `page` (with `skipAggregation: true`) or `key`
+                  (with `false`); `all` is not an EDI option — the validator enforces this through the
+                  `skipAggregation` rule (see that field). For every other file type the choices are
+                  `all` and `page`. The UI offers exactly these splits.
+                - |-
+                  A user asking where the "aggregation key" is configured is asking about this
+                  field: the key itself is derived from the file definition's document type, never
+                  entered.
         lookups:
           type: array
           description: |-
@@ -17140,14 +17692,22 @@ components:
         AI Agent configuration used by both AiAgentImport and GuardrailImport (ai_agent type).
 
         Configures which AI provider and model to use, along with instructions, parameter
-        tuning, output format, and available tools. Three providers are supported:
-
-        - **openai**: OpenAI models (GPT-4, GPT-4o, GPT-4o-mini, GPT-5, etc.). Configure via the `openai` object.
-        - **gemini**: Google Gemini models via the LiteLLM proxy. Configure via `litellm` with overrides in `litellm._overrides.gemini`.
-        - **anthropic**: Anthropic Claude models via the LiteLLM proxy. Configure via `litellm` with overrides in `litellm._overrides.anthropic`.
-
-        A `_connectionId` is optional (BYOK). If not provided on the parent import,
-        platform-managed credentials are used.
+        tuning, output format, and available tools. Providers come in two families with
+        two configuration formats:
+
+        - **Built-in providers** — each has its own configuration block.
+          - **openai**: OpenAI models (GPT-4.1, GPT-5, etc.). Configure via the `openai` object.
+          - **gemini**: Google Gemini models via the LiteLLM proxy. Configure via `litellm` with overrides in `litellm._overrides.gemini`.
+          - **anthropic**: Anthropic Claude models via the LiteLLM proxy. Configure via `litellm` with overrides in `litellm._overrides.anthropic`.
+        - **Catalog providers** — `mistral`, `xai`, `huggingface`, `deepseek`, `cohere`, `groq`. Added
+          as catalog data rather than platform code, they share one generic flat format:
+          `model`, `modelOptions`, `instructions`, `output`, and the `tools` / `prompts` /
+          `resources` arrays directly on this object.
+
+        A `_connectionId` on the parent import selects bring-your-own-key (BYOK)
+        credentials. Without one, built-in providers run on platform-managed
+        credentials; catalog providers have no platform-managed credentials, so they
+        save without a connection but cannot run until one is attached.
       required:
         - provider
       properties:
@@ -17157,18 +17717,224 @@ components:
             - openai
             - gemini
             - anthropic
+            - mistral
+            - xai
+            - huggingface
+            - deepseek
+            - cohere
+            - groq
           x-enumDescriptions:
-            openai: Use OpenAI models via the OpenAI Responses API.
-            gemini: Use Google Gemini models via the LiteLLM proxy.
-            anthropic: Use Anthropic Claude models via the LiteLLM proxy.
+            openai: Use OpenAI models via the OpenAI Responses API (built-in; `openai` block).
+            gemini: Use Google Gemini models via the LiteLLM proxy (built-in; `litellm` block).
+            anthropic: Use Anthropic Claude models via the LiteLLM proxy (built-in; `litellm` block).
+            mistral: Use Mistral models (catalog provider; generic flat format, BYOK).
+            xai: Use xAI Grok models (catalog provider; generic flat format, BYOK).
+            huggingface: Use Hugging Face inference endpoint models (catalog provider; generic flat format, BYOK).
+            deepseek: Use DeepSeek models (catalog provider; generic flat format, BYOK).
+            cohere: Use Cohere models (catalog provider; generic flat format, BYOK).
+            groq: Use Groq-hosted models (catalog provider; generic flat format, BYOK).
           description: AI provider to use.
           x-celigo-ai-guidance:
             - |-
-              - **openai**: Uses OpenAI Responses API. Configure via the `openai` object.
-              - **gemini**: Uses Google Gemini via LiteLLM. Configure via `litellm` with
-                Gemini-specific overrides in `litellm._overrides.gemini`.
-              - **anthropic**: Uses Anthropic Claude via LiteLLM. Configure via `litellm` with
-                Claude-specific overrides in `litellm._overrides.anthropic`.
+              The provider decides the configuration format, and the server rejects a
+              mismatch with 422 `invalid_provider_config_format`: `openai` needs the
+              `openai` block, `gemini` and `anthropic` need the `litellm` block (Gemini- or
+              Claude-specific settings under `litellm._overrides`), and the catalog
+              providers (`mistral`, `xai`, `huggingface`, `deepseek`, `cohere`, `groq`) need the
+              generic flat format — `model` and `modelOptions` directly on this object,
+              never an `openai` or `litellm` block.
+            - |-
+              Catalog providers are BYOK-only at run time: the agent saves without a
+              `_connectionId`, but its first run fails with 422 `invalid_request` ("No API
+              key configured for provider …"). Always attach an HTTP connection to the
+              vendor's API (token auth) when the provider is a catalog provider.
+        model:
+          type: string
+          description: |-
+            Model identifier for a catalog provider (generic flat format) — for example
+            `grok-4.6`. Built-in providers set the model inside their own block
+            (`openai.model`, `litellm.model`) instead.
+          x-celigo-ai-guidance:
+            - |-
+              Required for every catalog provider — omitting it or sending an empty string
+              fails the save with 422 `missing_required_field`.
+            - |-
+              Without a `_connectionId` on the parent import the model must be one the
+              catalog lists for the provider: an unknown id fails the save with 422
+              `model_not_found`, a listed-but-disabled id with 422 `model_disabled`. With a
+              `_connectionId` (BYOK) any model string saves — the server does not check it
+              against the catalog or the vendor.
+        modelOptions:
+          type: object
+          description: |-
+            Model tuning for a catalog provider (generic flat format). Which keys, values, and
+            ranges are accepted is defined per catalog model and validated on save when the
+            model is a catalog entry.
+          properties:
+            maxOutputTokens:
+              type: number
+              description: Maximum number of tokens the model may generate.
+            temperature:
+              type: number
+              description: Sampling temperature.
+            topP:
+              type: number
+              description: Nucleus sampling threshold.
+            reasoning_effort:
+              type: string
+              enum:
+                - low
+                - medium
+                - high
+                - xhigh
+              x-enumDescriptions:
+                low: Minimal reasoning before answering.
+                medium: Moderate reasoning.
+                high: Extensive reasoning.
+                xhigh: Maximum reasoning.
+              description: Reasoning depth for models that expose it.
+          x-celigo-ai-guidance:
+            - |-
+              When the model is a catalog entry, the server validates this object against
+              that model's schema and fails the save with 422 `invalid_model_options`
+              naming the key: unknown keys are rejected, `reasoning_effort` must be one of
+              the enum values where the model accepts it at all (xAI's `grok-4.6` does;
+              DeepSeek's `deepseek-chat` rejects the key), and numeric bounds apply —
+              on `grok-4.6`, `temperature` ≤ 2, `topP` ≤ 1, `maxOutputTokens` ≥ 100.
+            - |-
+              With a `_connectionId` and a model the catalog does not list, the object is
+              passed through unvalidated — send only options the vendor's API accepts.
+        instructions:
+          type: string
+          description: |-
+            System prompt for a catalog provider (generic flat format). Built-in providers
+            set it inside their own block (`openai.instructions`,
+            `litellm._overrides.anthropic.systemInstruction`).
+        output:
+          type: object
+          description: |-
+            Output format for a catalog provider (generic flat format). Built-in providers
+            configure it inside their own block (`openai.output`, `litellm.responseFormat`).
+          properties:
+            format:
+              type: object
+              description: Controls the structure of the model's output.
+              properties:
+                type:
+                  type: string
+                  enum:
+                    - text
+                    - json_schema
+                  x-enumDescriptions:
+                    text: Free-form text.
+                    json_schema: Structured JSON conforming to `jsonSchema`.
+                  description: Output type.
+                  x-celigo-ai-guidance:
+                    - |-
+                      `blob` is not accepted here — the save fails with 422
+                      `unsupported_output_format` naming the model (verified on `grok-4.6`).
+                name:
+                  type: string
+                  description: Name of the JSON schema, for `json_schema` output.
+                strict:
+                  type: boolean
+                  description: When true, the model must conform exactly to `jsonSchema`.
+                jsonSchema:
+                  type: object
+                  additionalProperties: true
+                  description: JSON Schema the structured output must conform to, for `json_schema` output.
+            verbose:
+              type: string
+              description: Level of detail in the model's response, for models that expose it.
+        tools:
+          type: array
+          description: |-
+            Tools available to a catalog-provider agent (generic flat format). Entries mirror
+            the built-in providers' tool entries: a Celigo Tool by `_toolId`, an MCP server by
+            `_mcpConnectionId`, or a vendor web-search tool.
+          items:
+            type: object
+            properties:
+              type:
+                type: string
+                enum:
+                  - tool
+                  - mcp
+                  - web_search
+                x-enumDescriptions:
+                  tool: Reference a reusable Celigo Tool resource.
+                  mcp: Connect to an MCP server for additional external tools.
+                  web_search: Search the web for real-time information, where the vendor's model supports it.
+                description: Type of tool entry.
+              tool:
+                type: object
+                description: Reference to a Celigo Tool resource, used when type is "tool".
+                properties:
+                  _toolId:
+                    type: string
+                    format: objectId
+                    x-celigo-refModel: tools
+                    description: The Celigo Tool to call.
+              mcp:
+                type: object
+                description: MCP server connection, used when type is "mcp".
+                properties:
+                  _mcpConnectionId:
+                    type: string
+                    format: objectId
+                    x-celigo-refModel: connections
+                    description: Connection to the MCP server.
+                  allowedTools:
+                    type: array
+                    description: |-
+                      Specific tools to allow from the MCP server (all if omitted). Each entry
+                      is either a plain tool name or an object carrying display metadata.
+                    items:
+                      type:
+                        - string
+                        - object
+              config:
+                type: object
+                additionalProperties: true
+                description: Tool-specific options for vendor-native tools (for example web-search settings).
+          x-celigo-ai-guidance:
+            - |-
+              References are checked on save: an unknown `_toolId` or `_mcpConnectionId`
+              fails with 422 `invalid_ref` naming the array index.
+        prompts:
+          type: array
+          description: |-
+            MCP prompt entries available to a catalog-provider agent (generic flat format).
+            Each entry references one MCP connection and the prompt names allowed from it.
+          items:
+            type: object
+            properties:
+              type:
+                type: string
+                enum:
+                  - mcp
+                x-enumDescriptions:
+                  mcp: Reference prompts exposed by an MCP server.
+                description: Type of prompt entry. Always "mcp".
+              mcp:
+                type: object
+                properties:
+                  _mcpConnectionId:
+                    type: string
+                    format: objectId
+                    x-celigo-refModel: connections
+                    description: Connection to the MCP server that exposes the prompts.
+                  allowedPrompts:
+                    type: array
+                    description: Prompt names the agent may fetch from the server.
+                    items:
+                      type: string
+          x-celigo-ai-guidance:
+            - |-
+              An unknown `_mcpConnectionId` fails the save with 422 `invalid_ref` naming
+              the array index.
+        resources:
+          $ref: '#/components/schemas/McpResources'
         openai:
           type: object
           description: |
@@ -17199,10 +17965,11 @@ components:
               x-celigo-ai-guidance:
                 - |-
                   With platform-managed credentials (no `_connectionId` on the parent
-                  import), the model must be on the platform's allowlist — an
-                  unlisted model fails the save with 422. A BYOK connection bypasses
-                  the allowlist and the model string is passed through to the
-                  provider as-is.
+                  import), the model must be one the platform hosts. The save does not
+                  check this — an unlisted model saves, and the agent's first run fails
+                  with 422 `invalid_model`, whose message lists the hosted models. A
+                  BYOK connection bypasses the hosted list and the model string is
+                  passed through to the provider as-is.
             reasoning:
               type: object
               description: Controls depth of reasoning for complex tasks.
@@ -17605,6 +18372,13 @@ components:
                 - claude-sonnet-4-6
                 - claude-opus-4-7
               x-celigo-ui-override: Required by the AI agent configuration form. Encoded here to mirror the form so builders produce connectable configurations.
+              x-celigo-ai-guidance:
+                - |-
+                  With platform-managed credentials (no `_connectionId` on the parent
+                  import), the model must be one the platform hosts for the provider —
+                  Gemini and Anthropic Claude both have a hosted list. The save does not
+                  check this — an unlisted model saves, and the agent's first run fails
+                  with 422 `invalid_model`, whose message lists the hosted models.
             temperature:
               type: number
               minimum: 0
@@ -18259,6 +19033,22 @@ components:
             litellm:
               required:
                 - model
+        else:
+          if:
+            properties:
+              provider:
+                enum:
+                  - mistral
+                  - xai
+                  - huggingface
+                  - deepseek
+                  - cohere
+                  - groq
+            required:
+              - provider
+          then:
+            required:
+              - model
     GuardrailConfig:
       type: object
       description: |-
@@ -20028,7 +20818,7 @@ components:
             MongodbImport: MongoDB database import for document-based operations.
             DynamodbImport: Amazon DynamoDB import for NoSQL table operations.
             WrapperImport: Custom adaptor import built outside of Celigo (rarely used).
-            AiAgentImport: AI agent import using OpenAI, Gemini, or Anthropic Claude models for data processing.
+            AiAgentImport: AI agent import using OpenAI, Gemini, Anthropic Claude, or a BYOK catalog provider (Mistral, xAI, Hugging Face, DeepSeek, Cohere, Groq) for data processing.
             GuardrailImport: Safety and compliance check import for PII detection, moderation, or AI evaluation.
             FileSystemImport: Local or network file system import.
             ToolImport: Import that executes a reusable Celigo Tool resource.
@@ -33152,9 +33942,9 @@ components:
                 errors:
                   - code: dependencies_not_deleted
                     message: export 6902d88c10b42b2eaac9b2a1 must be deleted before you can delete connection 6398ddf316be761fb16a6523
-    403-forbidden:
+    422-unprocessable-entity:
       description: |
-        Forbidden. The authenticated caller does not have permission to perform this operation.
+        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
       content:
         application/json:
           schema:
@@ -33163,11 +33953,11 @@ components:
             default:
               value:
                 errors:
-                  - code: forbidden
-                    message: You do not have permission to access this resource.
-    422-unprocessable-entity:
+                  - code: unprocessable_entity
+                    message: The request could not be processed due to a semantic error.
+    403-forbidden:
       description: |
-        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
+        Forbidden. The authenticated caller does not have permission to perform this operation.
       content:
         application/json:
           schema:
@@ -33176,7 +33966,7 @@ components:
             default:
               value:
                 errors:
-                  - code: unprocessable_entity
-                    message: The request could not be processed due to a semantic error.
+                  - code: forbidden
+                    message: You do not have permission to access this resource.
 x-enable-proxy: true
 x-internal: false