@celigo/api-specs 0.2.157 → 0.2.159

package/dist/api.yml

@@ -3038,7 +3038,13 @@ components:
                   - Premium customers
               inputFilter:
                 type: object
-                description: Filter criteria for branch selection.
+                description: |-
+                  Filter criteria for branch selection. Send `version` and `rules` directly on
+                  `inputFilter` — not inside the `{type: "expression", expression: {...}}` wrapper
+                  that export and import filters use. A wrapped filter is saved without an error,
+                  but the branch is stored with no `inputFilter` and takes every request.
+                x-celigo-ai-guidance:
+                  - Read the API back after saving a branching router and check that each filtered branch still has its `inputFilter`; a filter sent in the export-filter wrapper is dropped on save without an error.
                 properties:
                   version:
                     type: string
@@ -3073,12 +3079,22 @@ components:
                         followed by operands which can be nested expressions.
               nextRouterId:
                 type: string
-                description: Next router to chain to (or "apiRouter" for final routing)
+                description: |-
+                  Next router to chain to, or "apiRouter" for the response router. Every branch needs
+                  one: a branch without it is saved, but every test run of the API is then refused
+                  with 400 "One or more branches are not merged back. Review the setup to ensure all
+                  branches converge.", whichever branch the request takes. An id that names no router
+                  fails the save with 422 "Invalid nextRouterId is defined on the branch. Please
+                  correct the branch configuration."
                 examples:
                   - apiRouter
               pageProcessors:
                 type: array
-                description: Processing steps to execute in this branch
+                description: |-
+                  Processing steps to execute in this branch. An export is a step at most once in an
+                  API: using it again, on another branch or in the same one, fails the save with 422
+                  "The export <id> is already included as a lookup in your API and cannot be added
+                  again."
                 items:
                   type: object
                   properties:
@@ -3344,6 +3360,11 @@ components:
             matches; the typed `context.success` filter doesn't prevent that, because
             `context.success` is true whenever no step failed, including when a lookup found nothing.
             A step that fails with `proceedOnFailure` off selects the `fail` response.
+
+            Send `version` and `rules` directly on `inputFilter`, not inside the
+            `{type: "expression", expression: {...}}` wrapper that export and import filters use. A
+            wrapped filter is saved without an error, but the response is stored with no
+            `inputFilter`, so it matches every request that reaches it.
           properties:
             version:
               type: string

package/dist/editransaction.yml

@@ -561,6 +561,145 @@ paths:
                     errors:
                       - code: invalid_ref
                         message: EdiTransaction not found.
+  /v1/ediTransactions/{_ediTransactionId}/ediFile:
+    get:
+      x-internal: false
+      operationId: getEdiTransactionFileSignedUrl
+      tags:
+        - EDI Transactions
+      summary: Get a signed URL to download an EDI transaction file
+      description: |-
+        Returns a short-lived pre-signed S3 URL for the primary EDI document
+        (`type=nonFa`) or the functional-acknowledgement file (`type=fa`) of
+        one EDI transaction record. Fetch the URL with a plain GET right away
+        and never store it — request a new URL for a later download.
+
+        Get `_id` from a record returned by `POST /v1/ediTransactions/query`.
+        The id alone identifies the record for both X12 and EDIFACT; `type` is
+        the only query parameter.
+
+        The acknowledgement file exists only once the trading partner's 997
+        (X12) or CONTRL (EDIFACT) was ingested — a record whose `faStatus` is
+        `notReceived`, `inProgress` or `notApplicable` has none. Files are kept
+        for the account's data retention period; afterwards the record is still
+        listed but the download answers `edi_transaction_file_unavailable`.
+
+        This is the only file-download route that an application acting for a
+        signed-in user can also reach; the document-number downloads under
+        `/v1/edi/documents` are public-API only.
+
+        Downloads are rate limited per user.
+      parameters:
+        - name: _ediTransactionId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 6a0377fcbfecf34a362e9be2
+          description: The EDI transaction ID.
+        - name: type
+          in: query
+          required: true
+          schema:
+            type: string
+            enum:
+              - nonFa
+              - fa
+            x-enumDescriptions:
+              nonFa: Primary business document (850, 810, ORDERS, etc.)
+              fa: Functional acknowledgement file (997 for X12, CONTRL for EDIFACT)
+          description: |-
+            Which file to download — the original EDI business document or the
+            functional acknowledgement the trading partner returned for it.
+      responses:
+        '200':
+          description: Pre-signed download URL for the requested file.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EDITransactionFileSignedUrlResponse'
+              examples:
+                non_fa:
+                  summary: Signed URL for a primary business document
+                  value:
+                    signedURL: https://integrator-files.s3.us-east-1.amazonaws.com/26338886c17c45e1840e0a7ec81a1a2d?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ASIAEXAMPLE%2F20261021%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20261021T165300Z&X-Amz-Security-Token=EXAMPLE-STS-TOKEN&X-Amz-SignedHeaders=host&X-Amz-Signature=4f9b2c1e8a3d7f0b5c6e9a2d4f8b1c3e7a0d5f2b9c4e6a8d1f3b7c0e5a9d2f4b
+                fa:
+                  summary: Signed URL for a functional-acknowledgement file
+                  value:
+                    signedURL: https://integrator-files.s3.us-east-1.amazonaws.com/9a7c3e14b2af45d8bc0e6090c5be6afa?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ASIAEXAMPLE%2F20261021%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20261021T165300Z&X-Amz-Security-Token=EXAMPLE-STS-TOKEN&X-Amz-SignedHeaders=host&X-Amz-Signature=7d0e5a9d2f4b6c8e1a3f7b0c5e9a2d4f8b1c3e7a0d5f2b9c4e6a8d1f3b7c0e5a
+        '400':
+          description: The request failed validation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                missing_type:
+                  summary: type query parameter missing
+                  value:
+                    errors:
+                      - code: invalid_type
+                        message: The "type" query parameter must be either "nonFa" or "fa".
+                invalid_type:
+                  summary: Invalid type value
+                  value:
+                    errors:
+                      - code: invalid_type
+                        message: The "type" query parameter must be either "nonFa" or "fa".
+                invalid_id:
+                  summary: Invalid transaction ID
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _transactionId.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            The EDI transaction was not found, or the requested file is not
+            available for it — no acknowledgement was ingested, the record
+            carries no file reference, or the object aged out of storage.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                transaction_not_found:
+                  value:
+                    errors:
+                      - code: transaction_not_found_for_id
+                        message: No transaction found for the given ID.
+                file_unavailable:
+                  value:
+                    errors:
+                      - code: edi_transaction_file_unavailable
+                        message: The requested file for this transaction is not available or has expired.
+        '422':
+          description: The account has no B2B Manager (EDI) license.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                license:
+                  value:
+                    errors:
+                      - code: edi_subscription_required
+                        message: EDI is a premium feature that is not included in your account's current subscription plan. Please upgrade your account to get access to B2B Manager.
+        '500':
+          description: An unexpected error occurred while generating the signed URL.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                download_error:
+                  value:
+                    errors:
+                      - code: edi_file_download_error
+                        message: An error occurred while retrieving the EDI file. Please try again later.
   /v1/ediTransactions/{_ediTransactionId}/mdn:
     get:
       x-internal: false
@@ -683,22 +822,30 @@ paths:
       operationId: downloadEdiFile
       tags:
         - EDI Transactions
-      summary: Download an EDI file
+      summary: Download an EDI file by document number
       description: |-
-        Downloads the raw EDI file content for a specific document number.
-
-        The `documentType` query parameter is required and must be the EDI
-        document type code — for X12, the numeric transaction-set ID as a
-        string (e.g. `850`, `810`, `856`, `997`); for EDIFACT, the UNH01
-        message type (e.g. `ORDERS`, `INVOIC`, `DESADV`, `CONTRL`).
+        Streams the raw EDI document whose business document number and
+        document type match — the file an export parsed or an import
+        generated. Acknowledgement files are not served here; use
+        `GET /v1/ediTransactions/{_ediTransactionId}/ediFile?type=fa`.
 
-        The server uses `documentType` + `documentNumber` together to locate
-        the transaction record and return the associated raw EDI file.
+        A document number is not unique: the same purchase-order number can
+        exist for several trading partners, in both directions, in sandbox and
+        production, or across integrations. Add lookup filters to pick one —
+        they AND together — and when several records still match, the latest
+        by `lastModified` is returned. Partner ids use the same names as
+        `POST /v1/ediTransactions/query`: `interchangeSenderId` /
+        `interchangeReceiverId` for X12, `unbSenderId` / `unbReceiverId` for
+        EDIFACT. When no document number is known, use
+        `GET /v1/edi/documents/ediFile` with filters alone.
 
         Get `documentNumber` and `documentType` from a transaction record
-        returned by `POST /v1/ediTransactions/query`. Alternatively,
-        download via `POST /v1/jobs/{_flowJobId}/files/signedURL` using
-        the `s3Key` from the transaction record.
+        returned by `POST /v1/ediTransactions/query`; a record's `_id` is the
+        unambiguous alternative through
+        `GET /v1/ediTransactions/{_ediTransactionId}/ediFile`.
+
+        Public-API route only: there is no equivalent for applications acting
+        with a signed-in user's session. Downloads are rate limited per user.
       parameters:
         - name: documentNumber
           in: path
@@ -710,20 +857,20 @@ paths:
           description: |-
             The business document number that identifies the EDI transaction
             (e.g. a purchase-order number from an 850's BEG03). Matches the
-            `documentNumber` field on an EDI transaction record.
+            `documentNumber` field on an EDI transaction record; letters are
+            uppercased.
         - name: documentType
           in: query
           required: true
           schema:
             type: string
           description: |-
-            The EDI document type code. For X12, this is the numeric
-            transaction-set ID as a string (e.g. `850`, `810`, `856`, `997`).
-            For EDIFACT, this is the UNH01 message type (e.g. `ORDERS`,
-            `INVOIC`, `DESADV`, `CONTRL`).
-
-            Values like `X12` or `EDIFACT` are **not** valid here — those
-            identify the EDI standard family, not the document type.
+            EDI document type code — for X12 the numeric transaction-set ID as
+            a string (`850`, `810`, `856`, `997`); for EDIFACT the UNH01 message
+            type (`ORDERS`, `INVOIC`, `DESADV`, `CONTRL`). Case-insensitive. It
+            also selects the EDI standard the lookup runs against. `X12` and
+            `EDIFACT` name the standard, not a document type, and are rejected
+            here.
           examples:
             x12_850:
               value: '850'
@@ -734,13 +881,25 @@ paths:
             edifact_orders:
               value: ORDERS
               summary: EDIFACT Purchase Order
+        - $ref: '#/components/parameters/FileType'
+        - $ref: '#/components/parameters/Direction'
+        - $ref: '#/components/parameters/Sandbox'
+        - $ref: '#/components/parameters/FaStatus'
+        - $ref: '#/components/parameters/StartDate'
+        - $ref: '#/components/parameters/EndDate'
+        - $ref: '#/components/parameters/IntegrationId'
+        - $ref: '#/components/parameters/InterchangeSenderId'
+        - $ref: '#/components/parameters/InterchangeReceiverId'
+        - $ref: '#/components/parameters/UnbSenderId'
+        - $ref: '#/components/parameters/UnbReceiverId'
       responses:
         '200':
-          description: Raw EDI file content.
+          description: The raw EDI file, streamed as the response body.
           content:
-            text/plain:
+            application/octet-stream:
               schema:
                 type: string
+                format: binary
         '400':
           description: The request failed validation.
           content:
@@ -755,17 +914,42 @@ paths:
                       - code: document_type_required
                         message: The "documentType" query parameter is required to process this request.
                 invalid:
-                  summary: Invalid document type value
+                  summary: documentType names the standard (`X12` here; `EDIFACT` answers the same way), or fileType disagrees with documentType
                   value:
                     errors:
                       - code: edi_invalid_document_type
                         message: X12 is not a valid document type. Please verify the value and try again.
+                partner_id_for_other_standard:
+                  summary: EDIFACT partner id on an X12 lookup
+                  value:
+                    errors:
+                      - code: invalid_search_param_for_X12
+                        message: invalid search param unbSenderId for filetype X12
+                half_window:
+                  summary: Only one of startDate / endDate sent
+                  value:
+                    errors:
+                      - code: start_time_or_end_time_missing
+                        message: start time or end time missing
+                invalid_direction:
+                  summary: direction outside inbound / outbound
+                  value:
+                    errors:
+                      - code: invalid_direction
+                        message: 'direction is invalid. direction should be one of the following: inbound, outbound'
+                invalid_fa_status:
+                  summary: faStatus outside the status set
+                  value:
+                    errors:
+                      - code: invalid_fa_status
+                        message: 'Invalid fa status, only accepted values: notReceived,accepted,acceptedWithErrors,rejected,failed,notApplicable,inProgress'
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '404':
           description: |-
-            No transaction was found matching the provided document type and
-            document number combination.
+            No transaction matched the document number, type and filters — or
+            one did, but its file is no longer in storage (it aged out of the
+            account's data retention period, or was never captured).
           content:
             application/json:
               schema:
@@ -776,6 +960,159 @@ paths:
                     errors:
                       - code: edi_transaction_not_found
                         message: No transaction was found matching the provided document type and document number.
+                file_unavailable:
+                  value:
+                    errors:
+                      - code: edi_file_unavailable
+                        message: The EDI file for this transaction is not available.
+        '422':
+          description: The account has no B2B Manager (EDI) license.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                license:
+                  value:
+                    errors:
+                      - code: edi_subscription_required
+                        message: EDI is a premium feature that is not included in your account's current subscription plan. Please upgrade your account to get access to B2B Manager.
+  /v1/edi/documents/ediFile:
+    get:
+      x-internal: false
+      operationId: downloadEdiFileByLookup
+      tags:
+        - EDI Transactions
+      summary: Download the latest EDI file matching filters
+      description: |-
+        Streams the raw EDI document of the latest transaction (by
+        `lastModified`) that matches the lookup filters — for callers that
+        hold trading-partner context but no document number. The filters AND
+        together and at least one must be sent. Acknowledgement files are not
+        served here; use `GET /v1/ediTransactions/{_ediTransactionId}/ediFile?type=fa`.
+
+        `documentNumber` may be passed as a query parameter here; when it is,
+        `documentType` becomes required — the same contract as
+        `GET /v1/edi/documents/{documentNumber}/ediFile`. When `documentNumber`
+        and `documentType` are both omitted, the lookup runs against X12 unless
+        `fileType` says `EDIFACT` — `unbSenderId` sent on its own is refused
+        with `invalid_search_param_for_X12`. Partner ids
+        use the same names as `POST /v1/ediTransactions/query`:
+        `interchangeSenderId` / `interchangeReceiverId` for X12,
+        `unbSenderId` / `unbReceiverId` for EDIFACT.
+
+        Public-API route only: there is no equivalent for applications acting
+        with a signed-in user's session. Downloads are rate limited per user.
+      parameters:
+        - name: documentNumber
+          in: query
+          required: false
+          schema:
+            type: string
+            examples:
+              - PO03302026A
+          description: |-
+            Business document number to match (e.g. a purchase-order number from
+            an 850's BEG03); letters are uppercased. Requires `documentType`.
+        - $ref: '#/components/parameters/DocumentType'
+        - $ref: '#/components/parameters/FileType'
+        - $ref: '#/components/parameters/Direction'
+        - $ref: '#/components/parameters/Sandbox'
+        - $ref: '#/components/parameters/FaStatus'
+        - $ref: '#/components/parameters/StartDate'
+        - $ref: '#/components/parameters/EndDate'
+        - $ref: '#/components/parameters/IntegrationId'
+        - $ref: '#/components/parameters/InterchangeSenderId'
+        - $ref: '#/components/parameters/InterchangeReceiverId'
+        - $ref: '#/components/parameters/UnbSenderId'
+        - $ref: '#/components/parameters/UnbReceiverId'
+      responses:
+        '200':
+          description: |-
+            The raw EDI file of the latest matching transaction, streamed as the
+            response body.
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+        '400':
+          description: The request failed validation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                no_filter:
+                  summary: No lookup filter at all
+                  value:
+                    errors:
+                      - code: lookup_filter_required
+                        message: At least one lookup parameter is required when documentNumber is not provided (documentType, partner IDs, direction, faStatus, dates, sandbox, or _integrationId).
+                missing_type:
+                  summary: documentNumber sent without documentType
+                  value:
+                    errors:
+                      - code: document_type_required
+                        message: The "documentType" query parameter is required to process this request.
+                partner_id_for_other_standard:
+                  summary: X12 partner id on an EDIFACT lookup
+                  value:
+                    errors:
+                      - code: invalid_search_param_for_EDIFACT
+                        message: invalid search param interchangeSenderId for filetype EDIFACT
+                partner_id_without_a_standard:
+                  summary: unbSenderId with neither documentType nor fileType — the lookup ran against X12
+                  value:
+                    errors:
+                      - code: invalid_search_param_for_X12
+                        message: invalid search param unbSenderId for filetype X12
+                invalid_sandbox:
+                  summary: sandbox outside true / false
+                  value:
+                    errors:
+                      - code: invalid_sandbox
+                        message: sandbox is invalid. sandbox should be true or false
+                invalid_integration_id:
+                  summary: Malformed _integrationId
+                  value:
+                    errors:
+                      - code: invalid_integration_id
+                        message: _integrationId is not a valid identifier.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            No transaction matched the filters — or one did, but its file is no
+            longer in storage (it aged out of the account's data retention
+            period, or was never captured).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not_found:
+                  value:
+                    errors:
+                      - code: edi_transaction_not_found
+                        message: No transaction was found matching the provided lookup filters.
+                file_unavailable:
+                  value:
+                    errors:
+                      - code: edi_file_unavailable
+                        message: The EDI file for this transaction is not available.
+        '422':
+          description: The account has no B2B Manager (EDI) license.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                license:
+                  value:
+                    errors:
+                      - code: edi_subscription_required
+                        message: EDI is a premium feature that is not included in your account's current subscription plan. Please upgrade your account to get access to B2B Manager.
 components:
   securitySchemes:
     bearerAuth:
@@ -1351,6 +1688,23 @@ components:
             - https://integrator-userdata-delete-30.s3.us-east-1.amazonaws.com/ediTransactions/5e58483b68b52e5827d56a86/TransactionSummary_20260614_20260713_5e58483b68b52e5827d56a86.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=4f9b2c1e8a3d7f0b5c6e9a2d4f8b1c3e7a0d5f2b9c4e6a8d1f3b7c0e5a9d2f4b
       required:
         - url
+    EDITransactionFileSignedUrlResponse:
+      type: object
+      description: |-
+        Pre-signed S3 URL for downloading an EDI transaction file. The URL is
+        short-lived — fetch it right away and request a new one for a later
+        download rather than storing it.
+      properties:
+        signedURL:
+          type: string
+          format: uri
+          description: |-
+            Pre-signed S3 URL that streams the EDI file when fetched with a plain
+            GET (no auth headers needed). Short-lived; never store it.
+          examples:
+            - https://integrator-files.s3.us-east-1.amazonaws.com/26338886c17c45e1840e0a7ec81a1a2d?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-SignedHeaders=host&X-Amz-Signature=4f9b2c1e8a3d7f0b5c6e9a2d4f8b1c3e7a0d5f2b9c4e6a8d1f3b7c0e5a9d2f4b
+      required:
+        - signedURL
     EDITransactionMdnResponse:
       type: object
       description: |-
@@ -1439,5 +1793,169 @@ components:
               summary: Bearer token invalid or revoked
               value:
                 message: Bearer Authentication Failed
+  parameters:
+    FileType:
+      name: fileType
+      in: query
+      required: false
+      schema:
+        type: string
+        enum:
+          - X12
+          - EDIFACT
+        x-enumDescriptions:
+          X12: ANSI X12 EDI standard
+          EDIFACT: UN/EDIFACT EDI standard
+      description: |-
+        EDI standard the lookup runs against. Inferred from `documentType` when
+        one is sent, and must agree with it.
+    Direction:
+      name: direction
+      in: query
+      required: false
+      schema:
+        type: string
+        enum:
+          - inbound
+          - outbound
+        x-enumDescriptions:
+          inbound: Document received from a trading partner
+          outbound: Document sent to a trading partner
+      description: Narrows the lookup to one transaction direction. Case-insensitive.
+    Sandbox:
+      name: sandbox
+      in: query
+      required: false
+      schema:
+        type: boolean
+      description: |-
+        When true, narrows the lookup to sandbox transactions; when false, to
+        production ones.
+    FaStatus:
+      name: faStatus
+      in: query
+      required: false
+      style: form
+      explode: false
+      schema:
+        type: array
+        items:
+          type: string
+          enum:
+            - inProgress
+            - notApplicable
+            - notReceived
+            - accepted
+            - acceptedWithErrors
+            - rejected
+            - failed
+        x-enumDescriptions:
+          inProgress: Awaiting functional acknowledgment from the trading partner
+          notApplicable: No functional acknowledgment expected
+          notReceived: Functional acknowledgment expected but not yet received
+          accepted: Acknowledged and accepted
+          acceptedWithErrors: Acknowledged with errors but accepted
+          rejected: Acknowledged and rejected
+          failed: Functional acknowledgment processing failed
+      description: |-
+        Narrows the lookup to records in any of the given functional-acknowledgment
+        statuses — one value, or several comma-separated (`faStatus=rejected,failed`).
+    StartDate:
+      name: startDate
+      in: query
+      required: false
+      schema:
+        type: string
+        examples:
+          - '2026-10-01T00:00:00Z'
+          - '1759276800000'
+      description: |-
+        Lower bound of the `lastModified` window, as an ISO-8601 timestamp or
+        epoch milliseconds. Must be sent together with `endDate` and lie before it.
+    EndDate:
+      name: endDate
+      in: query
+      required: false
+      schema:
+        type: string
+        examples:
+          - '2026-10-21T00:00:00Z'
+          - '1761004800000'
+      description: |-
+        Upper bound of the `lastModified` window, as an ISO-8601 timestamp or
+        epoch milliseconds. Must be sent together with `startDate`.
+    IntegrationId:
+      name: _integrationId
+      in: query
+      required: false
+      schema:
+        type: string
+        format: objectId
+        x-celigo-refModel: integrations
+        examples:
+          - 66cc9b31f2be816bf9377036
+      description: |-
+        Narrows the lookup to transactions processed by one integration. A
+        malformed id is rejected with 400 `invalid_integration_id`.
+    InterchangeSenderId:
+      name: interchangeSenderId
+      in: query
+      required: false
+      schema:
+        type: string
+        examples:
+          - '1234567890'
+      description: |-
+        X12 only — the record's `isaSenderId` (ISA06), matched exactly or against
+        the stored value padded with trailing spaces; letters are uppercased.
+        Rejected when the lookup runs against EDIFACT.
+    InterchangeReceiverId:
+      name: interchangeReceiverId
+      in: query
+      required: false
+      schema:
+        type: string
+        examples:
+          - CELIGOLABZ
+      description: |-
+        X12 only — the record's `isaReceiverId` (ISA08), matched like
+        `interchangeSenderId`. Rejected when the lookup runs against EDIFACT.
+    UnbSenderId:
+      name: unbSenderId
+      in: query
+      required: false
+      schema:
+        type: string
+        examples:
+          - PARTNERGLN
+      description: |-
+        EDIFACT only — the record's `unbSenderId` (UNB02), matched exactly or
+        against the stored value padded with trailing spaces; letters are
+        uppercased. Rejected when the lookup runs against X12.
+    UnbReceiverId:
+      name: unbReceiverId
+      in: query
+      required: false
+      schema:
+        type: string
+        examples:
+          - CELIGOGLN
+      description: |-
+        EDIFACT only — the record's `unbReceiverId` (UNB04), matched like
+        `unbSenderId`. Rejected when the lookup runs against X12.
+    DocumentType:
+      name: documentType
+      in: query
+      required: false
+      schema:
+        type: string
+        examples:
+          - '850'
+      description: |-
+        EDI document type code — for X12 the numeric transaction-set ID as a
+        string (`850`, `810`, `856`, `997`); for EDIFACT the UNH01 message type
+        (`ORDERS`, `INVOIC`, `DESADV`, `CONTRL`). Case-insensitive. It also
+        selects the EDI standard the lookup runs against. `X12` and `EDIFACT`
+        name the standard, not a document type, and are rejected here.
 x-enable-proxy: true
 x-internal: false

package/dist/tool.yml

@@ -460,9 +460,10 @@ paths:
       summary: Delete a tool
       description: |-
         Deletes a tool. Soft-deleted and retained in the recycle bin for 30 days.
-        Fails with 422 if other resources (MCP servers, access tokens) still
-        reference this tool — call `GET /v1/tools/{_id}/dependencies` first to
-        check.
+        Fails with 422 if other resources (MCP servers, access tokens, or a
+        `ToolImport` import whose `tool._toolId` names it: "import <id> must be
+        deleted before you can delete tool <id>") still reference this tool — call
+        `GET /v1/tools/{_id}/dependencies` first to check; it lists those imports.
       operationId: deleteTool
       tags:
         - Tools
@@ -1231,8 +1232,12 @@ paths:
         '422':
           description: |-
             A step failed, or the Tool was refused before any step ran: a connection binding is
-            missing (`connection_not_overridden`) or has no `_id`, or its branches don't all merge
-            back (`tool_dangling_branch`). A failed step answers 422 even when it has
+            missing (`connection_not_overridden`) or has no `_id`, its branches don't all merge
+            back (`tool_dangling_branch`), or the input fails `input.schema` (a missing `required`
+            property answers `tool_input_schema_validation_failed`). The output stage answers 422 too when the stored
+            `output.schema` holds `additionalProperties: false` and the output mappings write a field
+            it doesn't list ("Tool output validation failed: must NOT have additional properties").
+            A failed step answers 422 even when it has
             `proceedOnFailure: true`: the later steps still run, but the response carries the error,
             not the output. Either way the response includes `invocationId` when logging is active,
             so the run can be opened in the run history.
@@ -6354,7 +6359,16 @@ components:
             JSON Schema describing the expected input data structure.
 
             Used for validation, documentation, and AI-assisted tooling.
-            Must be a valid JSON Schema document.
+            Must be a valid JSON Schema document. Leave `$schema` out or name draft-07: a
+            `$schema` naming draft 2020-12 fails the save with 422 "Invalid input.schema -
+            no schema with key or ref ...". An `$id` saves.
+
+            Each invoke's input is validated against it. A missing `required` property
+            refuses the call with 422 `tool_input_schema_validation_failed` ("Tool input
+            validation failed: must have required property '<name>'"), and a failed
+            `pattern` with 422 "Tool input validation failed: <field>: must match pattern
+            ...". A property made required later therefore breaks callers that don't send
+            it.
           additionalProperties: true
           examples:
             - type: object
@@ -6468,6 +6482,11 @@ components:
 
             Used for documentation and validation of the tool's output.
             Must be a valid JSON Schema document.
+
+            The mapped output is validated against it. While the stored schema holds
+            `additionalProperties: false`, `POST /v1/tools/{_id}/invoke` answers 422 "Tool
+            output validation failed: must NOT have additional properties" when the output
+            mappings write a field the schema doesn't list.
           additionalProperties: true
           examples:
             - type: object
@@ -6760,7 +6779,12 @@ components:
                 description: |
                   Filter criteria to determine if this branch should be selected.
 
-                  Uses Celigo's expression-based filter format.
+                  Uses Celigo's expression-based filter format. Send `version` and `rules`
+                  directly on `inputFilter` — not inside the `{type: "expression", expression: {...}}`
+                  wrapper that export and import filters use. A wrapped filter is saved without an
+                  error, but the branch is stored with no `inputFilter` and takes every input.
+                x-celigo-ai-guidance:
+                  - Read the tool back after saving a branching router and check that each filtered branch still has its `inputFilter`; a filter sent in the export-filter wrapper is dropped on save without an error.
                 properties:
                   version:
                     type: string
@@ -6800,6 +6824,13 @@ components:
 
                   Use "outputRouter" as a special terminal value to exit the tool
                   and return the processing results.
+
+                  Every branch needs one. A branch without it is saved, but every invoke is
+                  then refused with 422 and every test run with 400 `tool_dangling_branch`
+                  ("One or more branches are not merged back. Review the setup to ensure all
+                  branches converge."), whichever branch the input takes. An id that names no
+                  router fails the save with 422 "Invalid nextRouterId is defined on the branch.
+                  Please correct the branch configuration."
                 examples:
                   - router_002
                   - outputRouter
@@ -6809,7 +6840,10 @@ components:
                   Processing steps to execute in this branch.
 
                   Each processor references an export (lookup) or import resource
-                  for data retrieval or submission.
+                  for data retrieval or submission. An export is a step at most once in a
+                  tool: using it again, on another branch or in the same one, fails the save
+                  with 422 "The export <id> is already included as a pageProcessor in your
+                  flow, and cannot be added again."
                 items:
                   type: object
                   properties:
@@ -7064,6 +7098,12 @@ components:
 
             Branches can chain to other routers or use the special "outputRouter"
             terminal value to exit the tool.
+
+            A tool saves without `routers`, but it can't run: `POST /v1/tools/{_id}/invoke`
+            and a test run answer 400 `tool_empty_router` ("Tool has no steps configured.
+            Add at least one step before executing the tool."). A full PUT that omits
+            `routers` removes the steps the same way. Put linear steps in one pass-through
+            router with a single branch.
           items:
             $ref: '#/components/schemas/Router'
         aiDescription:

package/package.json

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

package/schemas.json

@@ -1,7 +1,7 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "063d41cc",
+		"iasCommit": "d6523356",
 		"generatedAt": "2026-10-21"
 	},
 	"roots": {