@celigo/api-specs 0.2.1

package/dist/tradingpartnerconnector.yml

@@ -0,0 +1,1490 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: Trading Partner Connectors
+  description: API for managing Celigo trading partner connectors — reusable templates for onboarding EDI trading partners.
+  x-celigo-ai-guidance:
+    - |-
+      Trading partner connectors define reusable templates for onboarding EDI trading partners.
+      They specify pre-configured field values and fields the user must set for connections,
+      exports, imports, and EDI profiles when creating a trading partner.
+    - |-
+      Each connector can define conditions (expression-based filters) that control
+      when certain field configurations apply.
+      Connectors can be published to make them available across the platform,
+      but publishing requires special user permissions.
+servers:
+  - url: https://api.integrator.io
+    description: Production (US / default region)
+  - url: https://api.eu.integrator.io
+    description: Production (EU region)
+  - url: https://api.au.integrator.io
+    description: Production (AU region)
+  - url: https://api.ca.integrator.io
+    description: Production (CA region)
+security:
+  - bearerAuth: []
+tags:
+  - name: Trading Partner Connectors
+    description: |-
+      Trading partner connectors are reusable templates for onboarding EDI
+      trading partners. Each connector defines pre-configured field values
+      and fields the user must set for connections, exports, imports, and
+      EDI profiles.
+
+      Connectors support expression-based conditions that control when
+      certain field configurations apply. Publishing a connector makes it
+      available to all accounts but requires the
+      `allowedToPublishTPConnectors` permission.
+
+      ## Trading partner connector schema
+
+      {% openapi-schemas spec="tradingpartnerconnector" schemas="TradingPartnerConnector" grouped="true" %}
+paths:
+  /v1/tpconnectors:
+    get:
+      x-internal: false
+      summary: List trading partner connectors
+      description: |-
+        Returns all trading partner connectors visible to the caller. Published
+        connectors are visible to everyone; unpublished connectors are visible
+        only to their owner.
+
+        The list response is a summary shape — it includes `_id`, `name`,
+        `_userId`, `helpURL`, timestamps, and the categorization fields (`type`,
+        `region`, `model`, `baseName`) when set, but omits `published` and
+        `supportedBy`. Use GET by ID to retrieve the full configuration.
+      operationId: listTradingPartnerConnectors
+      tags:
+        - Trading Partner Connectors
+      parameters:
+        - name: publishedOnly
+          in: query
+          description: When set to `true`, only published connectors are returned.
+          required: false
+          schema:
+            type: string
+            enum:
+              - 'true'
+              - 'false'
+            x-enumDescriptions:
+              'true': Return only published connectors.
+              'false': Return all connectors including unpublished ones.
+            examples:
+              - 'true'
+        - name: baseName
+          in: query
+          required: false
+          description: |-
+            Filter to connectors whose `baseName` exactly matches this value —
+            typically one trading partner's group of connector variants. Must be
+            supplied once; repeating the parameter returns `422
+            invalid_query_param`. Returns `204` when nothing matches.
+          schema:
+            type: string
+            examples:
+              - Acme Corp
+        - name: distinct
+          in: query
+          required: false
+          description: |-
+            Changes the response shape: instead of connector objects, returns a
+            sorted array of the distinct `baseName` values across **published**
+            connectors (unpublished connectors are excluded even for their
+            owner). Combine with other filters to scope the set. Returns `204`
+            when no published connector has a `baseName`. Any value other than
+            `baseName` fails with `422 invalid_query_param`
+            ("distinct must be 'baseName'.").
+          schema:
+            type: string
+            enum:
+              - baseName
+            x-enumDescriptions:
+              baseName: Return the distinct `baseName` values as a sorted string array.
+      responses:
+        '200':
+          description: |-
+            Successfully retrieved list of trading partner connectors. With
+            `?distinct=baseName` the body is instead a sorted array of strings
+            (the distinct `baseName` values), e.g. `["Acme Corp", "Bravo Inc"]`.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/TradingPartnerConnector'
+              examples:
+                default:
+                  value:
+                    - _id: 66a8da952ae7e03e6e4c21ed
+                      name: AAFES AS2
+                      createdAt: '2024-07-30T12:20:37.904Z'
+                      lastModified: '2026-05-04T12:21:47.361Z'
+                      _userId: 6316f2b1e37e79778a43391c
+                      helpURL: https://docs.celigo.com/hc/en-us/articles/39875657389595
+                    - _id: 66a8da972a54be163b5610a5
+                      name: AAFES FTP
+                      createdAt: '2024-07-30T12:20:39.110Z'
+                      lastModified: '2026-05-04T12:21:47.542Z'
+                      _userId: 6316f2b1e37e79778a43391c
+                      helpURL: https://docs.celigo.com/hc/en-us/articles/39875657389595
+                    - _id: 6a55bd1004eae44075e8250e
+                      name: Acme Corp FTP
+                      createdAt: '2026-07-14T04:37:36.576Z'
+                      lastModified: '2026-07-14T04:37:36.576Z'
+                      _userId: 6316f2b1e37e79778a43391c
+                      type: FTP
+                      region: North America
+                      model: Dropship
+                      baseName: Acme Corp
+        '204':
+          description: No trading partner connectors exist, or none matches the supplied filter.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          description: |-
+            The `baseName` query parameter was supplied more than once (or is
+            otherwise not a single string), or `distinct` was set to a value
+            other than `baseName`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                baseNameNotAString:
+                  summary: Repeated baseName parameter
+                  value:
+                    errors:
+                      - code: invalid_query_param
+                        message: baseName must be a string.
+    post:
+      x-internal: false
+      summary: Create a trading partner connector
+      description: |-
+        Creates a new trading partner connector. Only `name` is required.
+        Setting `published: true` requires the
+        `allowedToPublishTPConnectors` permission; without it the field is
+        silently ignored.
+      x-celigo-ai-guidance:
+        - |-
+          Creates a new trading partner connector that defines reusable templates for
+          onboarding EDI trading partners.
+        - |-
+          The `published` flag can only be set by users with the
+          `allowedToPublishTPConnectors` permission.
+          Published connector names must be unique across all published connectors.
+      operationId: createTradingPartnerConnector
+      tags:
+        - Trading Partner Connectors
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              minimal:
+                summary: Minimal create
+                value:
+                  name: Acme Corp FTP
+              categorized:
+                summary: Create with categorization fields
+                value:
+                  name: Acme Corp FTP
+                  type: FTP
+                  region: North America
+                  model: Dropship
+                  baseName: Acme Corp
+              with-supportedBy:
+                summary: With connection template
+                value:
+                  name: Acme Corp FTP
+                  helpURL: https://docs.celigo.com/hc/en-us/articles/12345
+                  supportedBy:
+                    connection:
+                      preConfiguredFields:
+                        - path: type
+                          values:
+                            - ftp
+                        - path: ftp.type
+                          values:
+                            - sftp
+                      fieldsUserMustSet:
+                        - path: name
+                        - path: ftp.username
+                        - path: ftp.password
+                        - path: ftp.hostURI
+                          inputType: uri
+                    export:
+                      preConfiguredFields:
+                        - path: file.type
+                          values:
+                            - filedefinition
+                      fieldsUserMustSet:
+                        - path: name
+                    import:
+                      preConfiguredFields:
+                        - path: file.type
+                          values:
+                            - filedefinition
+                      fieldsUserMustSet:
+                        - path: name
+                    ediProfile:
+                      preConfiguredFields:
+                        - path: fileType
+                          values:
+                            - edix12
+                      fieldsUserMustSet:
+                        - path: myInterchangeId
+                        - path: myGroupId
+      responses:
+        '201':
+          description: Trading partner connector created successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TradingPartnerConnector'
+              examples:
+                default:
+                  value:
+                    _id: 6a07d850f8b91b72d73fd4ab
+                    _userId: 5c9d42dad46d11272527e301
+                    name: Acme Corp FTP
+                    published: false
+                    region: North America
+                    model: none
+                    createdAt: '2026-05-16T02:37:04.403Z'
+                    lastModified: '2026-05-16T02:37:04.403Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/tpconnectors/{_id}:
+    get:
+      x-internal: false
+      summary: Get a trading partner connector
+      description: |-
+        Returns the complete configuration of a trading partner connector,
+        including all `supportedBy` sections. Unpublished connectors are
+        only visible to their owner. The list endpoint returns a summary
+        that omits `published` and `supportedBy`.
+      x-celigo-ai-guidance:
+        - |-
+          Returns the complete configuration of a specific trading partner connector,
+          including all supportedBy sections with conditions, pre-configured fields,
+          and fields the user must set.
+        - |-
+          For the dedicated list/get endpoints,
+          only published connectors are returned unless the requesting user owns the connector.
+      operationId: getTradingPartnerConnectorById
+      tags:
+        - Trading Partner Connectors
+      parameters:
+        - name: _id
+          in: path
+          description: The unique identifier of the trading partner connector.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: tradingpartnerconnectors
+            examples:
+              - 5f8d43a1b9e5a80011a35f2c
+      responses:
+        '200':
+          description: Trading partner connector retrieved successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TradingPartnerConnector'
+              examples:
+                default:
+                  value:
+                    _id: 66a8da972a54be163b5610a5
+                    _userId: 6316f2b1e37e79778a43391c
+                    name: AAFES FTP
+                    published: true
+                    helpURL: https://docs.celigo.com/hc/en-us/articles/39875657389595
+                    createdAt: '2024-07-30T12:20:39.110Z'
+                    lastModified: '2026-05-04T12:21:47.542Z'
+                    supportedBy:
+                      connection:
+                        preConfiguredFields:
+                          - path: type
+                            values:
+                              - ftp
+                          - path: ftp.type
+                            values:
+                              - sftp
+                        fieldsUserMustSet:
+                          - path: name
+                          - path: ftp.username
+                          - path: ftp.password
+                          - path: ftp.hostURI
+                            values:
+                              - ' '
+                      export:
+                        preConfiguredFields:
+                          - path: file.type
+                            values:
+                              - filedefinition
+                        fieldsUserMustSet:
+                          - path: name
+                          - path: ftp.directoryPath
+                      import:
+                        preConfiguredFields:
+                          - path: file.type
+                            values:
+                              - filedefinition
+                        fieldsUserMustSet:
+                          - path: name
+                          - path: ftp.directoryPath
+                      ediProfile:
+                        preConfiguredFields:
+                          - path: fileType
+                            values:
+                              - edix12
+                          - path: tpInterchangeId
+                            values:
+                              - 001695568GP
+                          - path: tpGroupId
+                            values:
+                              - 001695568GP
+                        fieldsUserMustSet:
+                          - path: myInterchangeId
+                          - path: myGroupId
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    put:
+      x-internal: false
+      summary: Update a trading partner connector
+      description: |-
+        Replaces a trading partner connector. This is a full replace and an
+        upsert -- if no connector exists for the given ID, one is created.
+        When `published` is set to `true`, the `supportedBy` sections are
+        validated for required fields.
+      x-celigo-ai-guidance:
+        - |-
+          Updates an existing trading partner connector with the provided configuration.
+          This endpoint can also create a connector if no document exists for the given ID.
+        - |-
+          When `published` is set to true,
+          validation is enforced on the `supportedBy` sections to ensure all required
+          fields are present for connection,
+          export, import, and EDI profile configurations.
+      operationId: updateTradingPartnerConnector
+      tags:
+        - Trading Partner Connectors
+      parameters:
+        - name: _id
+          in: path
+          description: The unique identifier of the trading partner connector.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: tradingpartnerconnectors
+            examples:
+              - 5f8d43a1b9e5a80011a35f2c
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              update-name:
+                summary: Rename connector
+                value:
+                  name: Acme Corp SFTP (updated)
+                  helpURL: https://docs.celigo.com/hc/en-us/articles/12345
+              add-connection-template:
+                summary: Add connection template
+                value:
+                  name: Acme Corp SFTP
+                  supportedBy:
+                    connection:
+                      preConfiguredFields:
+                        - path: type
+                          values:
+                            - ftp
+                        - path: ftp.type
+                          values:
+                            - sftp
+                      fieldsUserMustSet:
+                        - path: name
+                        - path: ftp.username
+                        - path: ftp.password
+                        - path: ftp.hostURI
+                          inputType: uri
+      responses:
+        '200':
+          description: Trading partner connector updated successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TradingPartnerConnector'
+              examples:
+                default:
+                  value:
+                    _id: 6a07d850f8b91b72d73fd4ab
+                    _userId: 5c9d42dad46d11272527e301
+                    name: Acme Corp SFTP (updated)
+                    published: false
+                    helpURL: https://docs.celigo.com/hc/en-us/articles/12345
+                    createdAt: '2026-05-16T02:37:04.403Z'
+                    lastModified: '2026-05-16T02:40:31.064Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    delete:
+      x-internal: false
+      summary: Delete a trading partner connector
+      description: Soft-deletes a trading partner connector.
+      operationId: deleteTradingPartnerConnector
+      tags:
+        - Trading Partner Connectors
+      parameters:
+        - name: _id
+          in: path
+          description: The unique identifier of the trading partner connector.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: tradingpartnerconnectors
+            examples:
+              - 5f8d43a1b9e5a80011a35f2c
+      responses:
+        '204':
+          description: Trading partner connector deleted successfully.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    Filter:
+      type: object
+      description: |
+        Configuration for selectively processing records based on specified criteria. This object enables
+        precise control over which items are included or excluded from processing operations.
+
+        **Filter behavior**
+
+        When configured, the filter is applied before processing begins:
+        - Items that match the filter criteria are processed
+        - Items that don't match are completely skipped
+        - No partial processing is performed
+
+        **Implementation approaches**
+
+        There are two distinct filtering mechanisms available:
+
+        **Rule-Based Filtering (`type: "expression"`)**
+        - **Best For**: Common filtering patterns based on standard attributes
+        - **Capabilities**: Filter by names, values, dates, numerical ranges, text patterns
+        - **Advantages**: Declarative, no coding required, consistent performance
+        - **Configuration**: Define rules in the `expression` object
+        - **Use When**: You have clear, static criteria for selection
+
+        **Script-Based Filtering (`type: "script"`)**
+        - **Best For**: Complex logic, dynamic criteria, or business rules
+        - **Capabilities**: Full programmatic control, access to complete metadata
+        - **Advantages**: Maximum flexibility, can implement any filtering logic
+        - **Configuration**: Reference a script in the `script` object
+        - **Use When**: Simple rules aren't sufficient or logic needs to be dynamic
+      properties:
+        type:
+          type: string
+          description: |
+            Determines which filtering mechanism to use. This choice affects which properties
+            must be configured and how filtering logic is implemented.
+
+            **Available types**
+
+            **Rule-Based Filtering (`"expression"`)**
+            - **Required Config**: The `expression` object with rule definitions
+            - **Behavior**: Evaluates declarative rules against item attributes
+            - **Best For**: Common patterns like name matching, date ranges, value limits
+            - **Advantages**: Simpler to configure, no custom code required
+
+            **Script-Based Filtering (`"script"`)**
+            - **Required Config**: The `script` object with _scriptId and function
+            - **Behavior**: Executes custom JavaScript to determine which items to process
+            - **Best For**: Complex conditions, business logic, dynamic criteria
+            - **Advantages**: Maximum flexibility, can implement any logic
+
+            **Implementation guidance**
+
+            1. For standard filtering needs (name, size, date), use `"expression"`
+            2. For complex logic or conditions not covered by expressions, use `"script"`
+            3. When selecting a type, you must configure the corresponding object:
+                - `type: "expression"` requires the `expression` object
+                - `type: "script"` requires the `script` object
+          enum:
+            - expression
+            - script
+          x-enumDescriptions:
+            expression: Rule-based filtering using declarative conditions.
+            script: Script-based filtering using custom JavaScript logic.
+          examples:
+            - expression
+            - script
+        expression:
+          type: object
+          description: |
+            Configuration for declarative rule-based filtering. This object enables filtering
+            items based on common attributes without requiring custom code.
+
+            **Usage context**
+
+            This object is REQUIRED when `filter.type` is set to "expression" and should not be
+            configured otherwise. It provides a standardized way to define filtering rules that
+            can match against item attributes like name, type, value, date, and other properties.
+
+            **Implementation guidance**
+
+            The expression system uses a rule-based approach where:
+            - Rules can be combined with AND/OR logic
+            - Each rule can check a specific attribute
+            - Multiple conditions can be applied (ranges, pattern matching, exact matches)
+
+            **Common filter patterns**
+
+            1. **Pattern matching**: Using wildcards like `*` and `?`
+            2. **Value range filtering**: Numbers between min and max values
+            3. **Date range filtering**: Items created/modified within specific time ranges
+            4. **Status checking**: Items with specific status values or properties
+
+            For AI agents: Rule-based filtering should be your first choice when the filtering criteria
+            can be expressed in terms of standard attributes. Only use script-based filtering when
+            more complex logic is required.
+          properties:
+            version:
+              type: string
+              description: |
+                Version identifier for the expression format. Currently only version "1" is supported.
+
+                This field ensures future compatibility if the expression format evolves. Always set to "1"
+                for current implementations.
+              enum:
+                - '1'
+              x-enumDescriptions:
+                '1': Current and only supported filter expression version.
+              examples:
+                - '1'
+            rules:
+              type: array
+              description: |
+                Expression array defining filter conditions using prefix notation. The first element is the operator,
+                followed by its operands which may themselves be nested expression arrays.
+
+                The rule expression follows this pattern:
+                - First element: Operator name (string)
+                - Remaining elements: Operands for that operator (values or nested expressions)
+
+                **Expression structure**
+
+                Filter expressions use a prefix notation where operators appear before their operands:
+                ```
+                [operator, operand1, operand2, ...]
+                ```
+
+                **Comparison Operators**
+                - `"equals"`: Exact match (equals)
+                - `"notequals"`: Not equal to value (not equals)
+                - `"greaterthan"`: Value is greater than specified value (is greater than)
+                - `"greaterthanequals"`: Value is greater than or equal to specified value (is greater than or equals)
+                - `"lessthan"`: Value is less than specified value (is less than)
+                - `"lessthanequals"`: Value is less than or equal to specified value (is less than or equals)
+                - `"startswith"`: String starts with specified prefix (starts with)
+                - `"endswith"`: String ends with specified suffix (ends with)
+                - `"contains"`: String contains specified substring (contains)
+                - `"doesnotcontain"`: String does not contain specified substring (does not contain)
+                - `"isempty"`: Field is empty or null (is empty)
+                - `"isnotempty"`: Field contains a value (is not empty)
+                - `"matches"`: Matches specified pattern (matches)
+
+                **Logical Operators**
+                - `"and"`: All conditions must be true
+                - `"or"`: At least one condition must be true
+                - `"not"`: Negates the condition
+
+                **Field Access and Type Conversion**
+                - `"extract"`: Access a field from the item by name
+                - `"settings"`: Access a custom setting from the flow, flow step, or integration configuration
+                - `"boolean"`: Convert value to Boolean type
+                - `"epochtime"`: Convert value to Epoch Time (Unix timestamp)
+                - `"number"`: Convert value to Number type
+                - `"string"`: Convert value to String type
+
+                **Field Access Details**
+
+                **Using `extract` to access record fields:**
+                - Retrieves values from the current record being processed
+                - Can access nested properties using dot notation (e.g., `"customer.email"`)
+                - Returns the raw field value which may need type conversion
+
+                **Using `settings` to access configuration values:**
+                - Retrieves values from the integration's configuration settings
+                - Supports different scopes with prefix notation:
+                  - `flow.settingName`: Access flow-level settings
+                  - `export.settingName`: Access export-level settings
+                  - `import.settingName`: Access import-level settings
+                  - `integration.settingName`: Access integration-level settings
+                - Useful for dynamic filtering based on configuration
+
+                **Field Transformations**
+                - `"lowercase"`: Convert string to lowercase
+                - `"uppercase"`: Convert string to uppercase
+                - `"ceiling"`: Round number up to the nearest integer
+                - `"floor"`: Round number down to the nearest integer
+                - `"abs"`: Get absolute value of a number
+
+                Type conversion operators are often necessary when comparing extracted field values against literals or when the field type doesn't match the comparison operator's expected type. For example:
+
+                ```json
+                [
+                  "equals",
+                  [
+                    "number",  // Convert to number before comparison
+                    [
+                      "extract",
+                      "quantity"
+                    ]
+                  ],
+                  100
+                ]
+                ```
+
+                Example with datetime conversion:
+                ```json
+                [
+                  "greaterthan",
+                  [
+                    "epochtime",  // Convert to Unix timestamp before comparison
+                    [
+                      "extract",
+                      "createdDate"
+                    ]
+                  ],
+                  1609459200000  // January 1, 2021 as Unix timestamp in milliseconds
+                ]
+                ```
+
+                Example with transformations:
+                ```json
+                [
+                  "and",
+                  [
+                    "matches",
+                    [
+                      "lowercase",  // Convert to lowercase before matching
+                      [
+                        "string",
+                        [
+                          "extract",
+                          "categories"
+                        ]
+                      ]
+                    ],
+                    "netsuite"
+                  ],
+                  [
+                    "notequals",
+                    [
+                      "string",
+                      [
+                        "extract",
+                        "recurrence.pattern.type"
+                      ]
+                    ],
+                    ""
+                  ]
+                ]
+                ```
+
+                Example comparing a record field with a flow setting:
+                ```json
+                [
+                  "equals",
+                  [
+                    "string",
+                    [
+                      "extract",
+                      "trantype"
+                    ]
+                  ],
+                  [
+                    "string",
+                    [
+                      "settings",
+                      "flow.trantype"
+                    ]
+                  ]
+                ]
+                ```
+
+                **Examples**
+
+                Example 1: Status field is not equal to "cancelled"
+                ```json
+                [
+                  "notequals",
+                  [
+                    "extract",
+                    "status"
+                  ],
+                  "cancelled"
+                ]
+                ```
+
+                Example 2: Filename starts with "HC"
+                ```json
+                [
+                  "startswith",
+                  [
+                    "extract",
+                    "filename"
+                  ],
+                  "HC"
+                ]
+                ```
+
+                Example 3: Amount is greater than 100
+                ```json
+                [
+                  "greaterthan",
+                  [
+                    "number",
+                    [
+                      "extract",
+                      "amount"
+                    ]
+                  ],
+                  100
+                ]
+                ```
+
+                Example 4: Order date is after January 1, 2023
+                ```json
+                [
+                  "greaterthan",
+                  [
+                    "extract",
+                    "orderDate"
+                  ],
+                  "2023-01-01T00:00:00Z"
+                ]
+                ```
+
+                Example 5: Category contains any of ["Urgent", "High Priority"]
+                ```json
+                [
+                  "anyof",
+                  [
+                    "extract",
+                    "category"
+                  ],
+                  ["Urgent", "High Priority"]
+                ]
+                ```
+              items:
+                oneOf:
+                  - title: String
+                    type: string
+                  - title: Number
+                    type: number
+                  - title: Boolean
+                    type: boolean
+                  - title: Object
+                    type: object
+                  - title: Array
+                    type: array
+                  - title: 'Null'
+                    type: 'null'
+        script:
+          type: object
+          description: |
+            Configuration for programmable script-based filtering. This object enables complex, custom
+            filtering logic beyond what expression-based filtering can provide.
+
+            **Usage context**
+
+            This object is REQUIRED when `filter.type` is set to "script" and should not be configured
+            otherwise. It provides a way to execute custom JavaScript code to determine which items
+            should be processed.
+
+            **Implementation approach**
+
+            Script-based filtering works by:
+            1. Executing the specified function from the referenced script
+            2. Passing item data to the function
+            3. Using the function's return value (true/false) to determine inclusion
+
+            **Common use cases**
+
+            Script filtering is ideal for:
+            - Complex business logic that can't be expressed as simple rules
+            - Dynamic filtering criteria that change based on external factors
+            - Content-based filtering that requires deep inspection
+            - Advanced pattern matching beyond simple wildcards
+            - Multi-stage filtering with intermediate logic
+
+            For AI agents: Only use script-based filtering when expression-based filtering is insufficient.
+            Script filtering requires maintaining custom code, which adds complexity to the integration.
+          properties:
+            _scriptId:
+              type: string
+              x-celigo-refModel: scripts
+              description: |
+                Reference to the Script resource that contains the filtering logic. This must be a valid
+                ObjectId of a Script resource that exists in the system.
+
+                The referenced script must contain the function specified in the `function` field
+                and must be written to handle filtering specifically. The script receives
+                item data as its input and must return a boolean value indicating whether
+                to process the item (true) or skip it (false).
+
+                Format: 24-character hexadecimal string (MongoDB ObjectId)
+              examples:
+                - 60a2c4e6f321d800129a1a3c
+                - 5f8d43a1b9e5a80011a35f2c
+            function:
+              type: string
+              description: |
+                Name of the function within the script to execute for filtering decisions. This function
+                must exist in the script referenced by _scriptId.
+
+                **Function requirements**
+
+                The specified function must:
+                - Accept item data as its first parameter
+                - Return a boolean value (true to process the item, false to skip it)
+                - Handle errors gracefully
+                - Execute efficiently (as it may run for many items)
+
+                **Function signature**
+
+                ```javascript
+                function filterItems(itemData) {
+                  // itemData contains properties of the item being evaluated
+                  // Custom logic here
+                  return true; // or false to skip the item
+                }
+                ```
+
+                For AI agents: Ensure the function name exactly matches a function defined in the
+                referenced script, as mismatches will cause the filter to fail.
+              examples:
+                - filterItems
+                - shouldProcess
+                - evaluateMatch
+    PreConfiguredField:
+      type: object
+      description: A field automatically set to a predefined value during onboarding.
+      x-celigo-ai-guidance:
+        - |-
+          A field that is automatically set to a predefined value during trading partner onboarding.
+          The `path` identifies which field on the target resource to set,
+          and `values` provides the value(s) to assign.
+      properties:
+        _id:
+          type: string
+          format: objectId
+          description: |-
+            Server-assigned subdocument ID, present on every stored entry.
+            Include it on updates to preserve entry identity.
+          examples:
+            - 6a2a623c715132b80ae5d066
+        path:
+          type: string
+          description: Dot-notation path of the field on the target resource.
+          examples:
+            - type
+            - ftp.type
+            - file.type
+            - as2.partnerId
+        values:
+          type: array
+          description: Value(s) to assign. Typically a single-element array.
+          items:
+            oneOf:
+              - title: String
+                type: string
+              - title: Number
+                type: number
+              - title: Boolean
+                type: boolean
+              - title: Object
+                type: object
+        _conditionIds:
+          type: array
+          description: Condition IDs that must be satisfied for this field to apply. If absent, always applies.
+          items:
+            type: string
+            format: objectId
+            examples:
+              - 5f8d43a1b9e5a80011a35f2c
+    FieldUserMustSet:
+      type: object
+      description: A field the user must provide during onboarding.
+      x-celigo-ai-guidance:
+        - A field that the user must provide a value for during trading partner onboarding.
+      properties:
+        _id:
+          type: string
+          format: objectId
+          description: |-
+            Server-assigned subdocument ID, present on every stored entry.
+            Include it on updates to preserve entry identity.
+          examples:
+            - 6a2a623c715132b80ae5d06c
+        path:
+          type: string
+          description: Dot-notation path of the field on the target resource.
+          x-celigo-ai-guidance:
+            - Dot-notation path of the field on the target resource that the user must set.
+          examples:
+            - name
+            - ftp.username
+            - ftp.hostURI
+            - ftp.directoryPath
+        values:
+          type: array
+          description: Optional suggested or constrained values.
+          items:
+            oneOf:
+              - title: String
+                type: string
+              - title: Number
+                type: number
+              - title: Boolean
+                type: boolean
+              - title: Object
+                type: object
+        _conditionIds:
+          type: array
+          description: Condition IDs that must be satisfied for this field to apply.
+          items:
+            type: string
+            format: objectId
+            examples:
+              - 5f8d43a1b9e5a80011a35f2c
+        helpURL:
+          type: string
+          format: uri
+          description: URL to documentation for this field.
+          examples:
+            - https://docs.celigo.com/hc/en-us
+        labelOverride:
+          type: string
+          description: Custom label to display in the UI instead of the default.
+          x-celigo-ai-guidance:
+            - Custom label to display for this field in the UI instead of the default
+          examples:
+            - SFTP Host
+    SupportedBySection:
+      type: object
+      description: |-
+        Conditions, pre-configured field values, and fields the user must set
+        for a resource type (export, import, or EDI profile) during trading
+        partner onboarding.
+      x-celigo-ai-guidance:
+        - |-
+          A section within `supportedBy` that defines conditions,
+          pre-configured field values,
+          and fields the user must set when creating a trading partner resource (connection,
+          export, import, or EDI profile).
+        - |-
+          Conditions use expression-based filters to control which field configurations
+          apply based on resource attributes.
+          Pre-configured fields are automatically set,
+          while fields the user must set require input during trading partner onboarding.
+      properties:
+        conditions:
+          type: array
+          description: |-
+            Expression-based filters referenced by `_conditionIds` in
+            `preConfiguredFields` and `fieldsUserMustSet`.
+          x-celigo-ai-guidance:
+            - |-
+              Array of condition objects.
+              Each condition contains an expression-based filter that can be referenced by
+              `_conditionIds` in `preConfiguredFields` and `fieldsUserMustSet` to
+              conditionally apply those field configurations.
+          items:
+            type: object
+            properties:
+              _id:
+                type: string
+                format: objectId
+                description: Referenced by `_conditionIds` in field entries.
+                x-celigo-ai-guidance:
+                  - |-
+                    Unique identifier for this condition,
+                    referenced by `_conditionIds` in field entries
+                examples:
+                  - 5f8d43a1b9e5a80011a35f2c
+              condition:
+                $ref: '#/components/schemas/Filter'
+        preConfiguredFields:
+          type: array
+          description: Fields automatically set during onboarding. Not editable by the user.
+          x-celigo-ai-guidance:
+            - |-
+              Array of fields that are automatically set to predefined values when creating a
+              trading partner resource using this connector.
+              These fields are not editable by the user during onboarding.
+          items:
+            $ref: '#/components/schemas/PreConfiguredField'
+        fieldsUserMustSet:
+          type: array
+          description: Fields the user must provide values for during onboarding.
+          x-celigo-ai-guidance:
+            - |-
+              Array of fields that the user must provide values for during trading partner onboarding.
+              These fields may have suggested values or constraints.
+          items:
+            $ref: '#/components/schemas/FieldUserMustSet'
+    ConnectionFieldUserMustSet:
+      type: object
+      description: |-
+        Connection field the user must provide during onboarding. Adds
+        `inputType` to control the UI input widget.
+      x-celigo-ai-guidance:
+        - |-
+          A field that the user must provide a value for on the connection during trading
+          partner onboarding.
+          Extends the base field with an `inputType` property to control the UI input widget.
+      properties:
+        _id:
+          type: string
+          format: objectId
+          description: |-
+            Server-assigned subdocument ID, present on every stored entry.
+            Include it on updates to preserve entry identity.
+          examples:
+            - 6a2a623c715132b80ae5d06c
+        inputType:
+          type: string
+          enum:
+            - number
+            - password
+            - uri
+          x-enumDescriptions:
+            number: Renders a numeric input field.
+            password: Renders a masked password input field.
+            uri: Renders a URI input field with URL validation.
+          description: UI input widget type for this field.
+          x-celigo-ai-guidance:
+            - |-
+              The type of input widget to render in the UI for this field.
+              Only applicable to connection fields.
+          examples:
+            - password
+            - uri
+        path:
+          type: string
+          description: Dot-notation path of the field on the connection.
+          x-celigo-ai-guidance:
+            - Dot-notation path of the field on the connection that the user must set.
+          examples:
+            - name
+            - ftp.username
+            - ftp.hostURI
+            - ftp.password
+        values:
+          type: array
+          description: Optional suggested or constrained values.
+          items:
+            oneOf:
+              - title: String
+                type: string
+              - title: Number
+                type: number
+              - title: Boolean
+                type: boolean
+              - title: Object
+                type: object
+        _conditionIds:
+          type: array
+          description: Condition IDs that must be satisfied for this field to apply.
+          items:
+            type: string
+            format: objectId
+            examples:
+              - 5f8d43a1b9e5a80011a35f2c
+        helpURL:
+          type: string
+          format: uri
+          description: URL to documentation for this field.
+          examples:
+            - https://docs.celigo.com/hc/en-us
+        labelOverride:
+          type: string
+          description: Custom label to display in the UI.
+          x-celigo-ai-guidance:
+            - Custom label to display for this field in the UI
+          examples:
+            - SFTP Password
+    ConnectionSupportedBySection:
+      type: object
+      description: |-
+        Connection-specific section. Same as other `supportedBy` sections but
+        `fieldsUserMustSet` entries may include `inputType` to control the UI
+        input widget.
+      properties:
+        conditions:
+          type: array
+          description: Expression-based filters for the connection section.
+          items:
+            type: object
+            properties:
+              _id:
+                type: string
+                format: objectId
+                description: Referenced by `_conditionIds` in field entries.
+                x-celigo-ai-guidance:
+                  - Unique identifier for this condition
+                examples:
+                  - 5f8d43a1b9e5a80011a35f2c
+              condition:
+                $ref: '#/components/schemas/Filter'
+        preConfiguredFields:
+          type: array
+          description: Fields automatically set on the connection during onboarding.
+          items:
+            $ref: '#/components/schemas/PreConfiguredField'
+        fieldsUserMustSet:
+          type: array
+          description: Fields the user must provide for the connection.
+          x-celigo-ai-guidance:
+            - |-
+              Fields the user must provide for the connection.
+              May include `inputType` to control the UI input widget.
+          items:
+            $ref: '#/components/schemas/ConnectionFieldUserMustSet'
+    TradingPartnerConnectorBase:
+      type: object
+      description: Writable fields shared by the request and response schemas.
+      properties:
+        name:
+          type: string
+          description: Connector name. Must be unique across all published connectors.
+          x-celigo-ai-guidance:
+            - |-
+              Name of the trading partner connector.
+              Must be unique across all published connectors.
+              Used to identify the connector during trading partner onboarding.
+          examples:
+            - AS2 EDI X12 Connector
+            - SFTP EDIFACT Connector
+        published:
+          type: boolean
+          default: false
+          description: |-
+            Whether this connector is published and available platform-wide.
+            Requires the `allowedToPublishTPConnectors` permission — without
+            it, this field is silently ignored.
+          x-celigo-ai-guidance:
+            - |-
+              Only users with the `allowedToPublishTPConnectors` permission can set this to true.
+              When publishing,
+              all `supportedBy` sections are validated to ensure required fields are present.
+              Published connector names must be unique.
+        helpURL:
+          type: string
+          anyOf:
+            - format: uri
+            - const: ''
+          description: |-
+            URL to documentation for this trading partner connector. May be an
+            empty string when no documentation link exists.
+          examples:
+            - https://docs.celigo.com/hc/en-us/articles/trading-partners
+        type:
+          type: string
+          description: |-
+            Categorizes the connector by the transport its templates configure.
+            Allowed values are configured per deployment — `FTP`, `AS2`, and `S3`
+            by default. Absent from responses when never set (connectors created
+            before this field existed omit it).
+          examples:
+            - AS2
+        region:
+          type: string
+          description: |-
+            Geographic region the trading partner operates in, used to group
+            connectors in the catalog. Defaults to `North America` at creation
+            when omitted; allowed values are configured per deployment (`North
+            America`, `European Union`, `Canada`, `USA`, and `Australia` by
+            default). Connectors created before this field existed omit it.
+          examples:
+            - North America
+        model:
+          type: string
+          description: |-
+            Business-model variant of the trading partner relationship, such as
+            `Dropship`, `Warehouse`, or `DVS`. Defaults to `none` at creation when
+            omitted, meaning the connector has no business-model variant; allowed
+            values are configured per deployment. Connectors created before this
+            field existed omit it.
+          examples:
+            - Dropship
+        baseName:
+          type: string
+          description: |-
+            Shared base name that groups related connector variants for the same
+            trading partner — for example, a partner's AS2 and FTP connectors.
+            Only present when set. Filter the list with the `baseName` query
+            parameter to retrieve one group.
+          examples:
+            - Acme Corp
+        supportedBy:
+          type: object
+          description: |-
+            Field configurations for each resource type involved in trading
+            partner onboarding.
+          x-celigo-ai-guidance:
+            - |-
+              Defines the field configurations for each resource type involved in trading partner onboarding.
+              Each section specifies conditions, pre-configured fields,
+              and fields the user must set.
+          properties:
+            ediProfile:
+              $ref: '#/components/schemas/SupportedBySection'
+            export:
+              $ref: '#/components/schemas/SupportedBySection'
+            import:
+              $ref: '#/components/schemas/SupportedBySection'
+            connection:
+              $ref: '#/components/schemas/ConnectionSupportedBySection'
+    ResourceResponse:
+      type: object
+      description: Response
+      x-celigo-ai-guidance:
+        - Core response fields shared by all Celigo resources
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Unique identifier for the resource. Format is a 24-character hexadecimal string.
+          x-celigo-ai-guidance:
+            - |-
+              The _id is used in:
+              - API endpoints that operate on a specific resource (e.g., GET, PUT, DELETE)
+              - References from other resources (e.g., flows that use this resource)
+              - Job history and error tracking
+          examples:
+            - 5f8d43a1b9e5a80011a35f2c
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was created. Set automatically and cannot be modified.
+          x-celigo-ai-guidance:
+            - Recorded in ISO 8601 with a UTC timezone (Z suffix).
+          examples:
+            - '2023-04-01T09:15:32Z'
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was last updated. Changes whenever any property is modified.
+          x-celigo-ai-guidance:
+            - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+          examples:
+            - '2023-04-15T14:30:15Z'
+        deletedAt:
+          type:
+            - string
+            - 'null'
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was soft-deleted. When null or absent, the resource is active.
+          x-celigo-ai-guidance:
+            - Non-null means the resource is soft-deleted (in the recycle bin) — recoverable within the retention period before permanent removal.
+          examples:
+            - '2023-05-20T11:45:32Z'
+      required:
+        - _id
+    TradingPartnerConnector:
+      type: object
+      required:
+        - _id
+        - _userId
+        - name
+        - createdAt
+        - lastModified
+      description: |-
+        Trading partner connector with metadata. The list endpoint returns a
+        summary shape (omits `published` and `supportedBy` but includes `type`,
+        `region`, `model`, and `baseName` when set); GET by ID returns the full
+        configuration.
+      allOf:
+        - $ref: '#/components/schemas/TradingPartnerConnectorBase'
+        - $ref: '#/components/schemas/ResourceResponse'
+        - type: object
+          properties:
+            _userId:
+              type: string
+              format: objectId
+              readOnly: true
+              x-celigo-refModel: users
+              description: User who owns or created this trading partner connector.
+              examples:
+                - 6316f2b1e37e79778a43391c
+    Error:
+      type: object
+      description: Standard error response envelope returned by integrator.io APIs.
+      properties:
+        errors:
+          type: array
+          description: List of errors that occurred while processing the request.
+          items:
+            type: object
+            properties:
+              code:
+                oneOf:
+                  - type: string
+                  - type: integer
+                description: |-
+                  Machine-readable error code. Usually a string like
+                  `invalid_ref`, `missing_required_field`, or `unauthorized`;
+                  may be an **integer** when the error mirrors an upstream HTTP
+                  status (e.g. `500`) — most commonly returned by connection-ping
+                  and adaptor-proxy responses.
+              message:
+                type: string
+                description: Human-readable description of the error.
+              field:
+                type: string
+                description: |-
+                  Optional pointer to the document field that caused the error.
+                  Used by structural validation errors (`missing_required_field`,
+                  `invalid_ref`) to indicate which field is at fault
+                  (e.g. `_id`, `type`, `http.baseURI`).
+              source:
+                type: string
+                description: |-
+                  Optional origin layer for the error — e.g. `application` when
+                  the error came from the remote system the adaptor called,
+                  `connector` when the adaptor itself rejected the request.
+            required:
+              - message
+      required:
+        - errors
+    Request:
+      type: object
+      description: |-
+        Request schema for creating or updating a trading partner connector.
+        Only `name` is required for creation. Connection
+        `preConfiguredFields` must include a `type` path (e.g. `ftp` or
+        `as2`) and export/import must include `file.type` set to
+        `filedefinition` -- these are validated when `published` is `true`.
+      x-celigo-ai-guidance:
+        - |-
+          Trading partner connectors define reusable templates for onboarding EDI trading partners.
+          They specify which fields are pre-configured and which fields the user must
+          provide for connections,
+          exports, imports, and EDI profiles.
+        - |-
+          When `published` is true, the connector's `supportedBy` sections are validated
+          to ensure all required fields are present. For example:
+          - Connection must have a pre-configured `type` field (either "ftp" or "as2")
+          - Export/import must have a pre-configured `file.type` set to "filedefinition"
+          - EDI profile must have the appropriate mandatory fields for x12 or edifact
+      required:
+        - name
+      allOf:
+        - $ref: '#/components/schemas/TradingPartnerConnectorBase'
+  responses:
+    401-unauthorized:
+      description: |-
+        Unauthorized. The request lacks a valid bearer token, or the provided token
+        failed to authenticate.
+
+        Note: the 401 response is produced by the auth middleware **before** the
+        request reaches the endpoint handler, so it does **not** follow the
+        standard `{errors: [...]}` envelope. Instead the body is a bare
+        `{message: string}` object with no `code`, no `errors` array. Callers
+        handling 401s should key off the HTTP status and the `message` string,
+        not try to destructure an `errors[]`.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                description: |-
+                  Human-readable description of the auth failure. Known values:
+                  - `"Unauthorized"` — no `Authorization` header on the request.
+                  - `"Bearer Authentication Failed"` — header present but token
+                    is invalid, revoked, or expired.
+            required:
+              - message
+          examples:
+            missing_token:
+              summary: No Authorization header sent
+              value:
+                message: Unauthorized
+            invalid_token:
+              summary: Bearer token invalid or revoked
+              value:
+                message: Bearer Authentication Failed
+    400-bad-request:
+      description: |
+        Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: invalid_request
+                    message: The request body failed validation.
+    422-unprocessable-entity:
+      description: |
+        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: unprocessable_entity
+                    message: The request could not be processed due to a semantic error.
+    404-not-found:
+      description: |
+        Not found. The requested resource does not exist or is not visible to the caller.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: not_found
+                    message: The requested resource was not found.
+x-enable-proxy: true
+x-internal: false