@celigo/api-specs 0.2.138 → 0.2.140

package/dist/mcp-server.yml

@@ -15,7 +15,7 @@ info:
       - Contains a collection of **tools** (referencing Tool resources), **APIs** (referencing builder-mode API resources), **prompts** (inline reusable templates), and **resources** (Celigo Storage files served to clients)
       - Can be enabled or disabled at both the server level and individual tool/API level
       - Supports MCP annotations on tools for hinting behavior (read-only, idempotent, destructive, etc.)
-      - Supports tool overrides for customizing connections, exports, imports, and routing per-server
+      - Binds the connections each tool's steps run on, per server (`tools[].overrides`); calls fail with "Missing connection overrides" until every lookup step's connection is bound
       - Exposes prompts via `prompts/list` and `prompts/get` with Handlebars-style argument substitution
       - Carries **permission sets** ("Capability Sets" in the UI) — named bundles of its tools, APIs, prompts, and resources granted to end users via `pset:<_id>` capability strings on end-user, group, and role resource grants
       - Carries optional **traffic limits** (`policies[]`) — a server-level rate limit, a per-user rate limit for OAuth end users, and a usage quota — enforced before a tool runs; a rejected call gets HTTP 429 with `Retry-After`
@@ -176,7 +176,7 @@ paths:
                   name: Customer Integration MCP
                   relativeURI: /customers
               with_tool:
-                summary: With a tool and Celigo OAuth
+                summary: With a tool (its lookup step bound) and Celigo OAuth
                 value:
                   name: Customer Integration MCP
                   relativeURI: /customers
@@ -188,6 +188,10 @@ paths:
                       disabled: false
                       annotations:
                         readOnlyHint: true
+                      overrides:
+                        exports:
+                          - _abstractId: 69d462d5b9c28ea0b7f82530
+                            _id: 69d462d5b9c28ea0b7f82530
                   oauth:
                     useCeligoOauth: true
       responses:
@@ -1564,12 +1568,27 @@ components:
     Overrides:
       type: object
       description: |
-        Per-server overrides for a tool's internal resources.
+        Per-server bindings for a tool's steps, applied on this server without changing the
+        Tool itself.
 
-        When a tool is added to an MCP server, its connections, exports, imports,
-        and routers can be customized for this specific server context without
-        modifying the underlying tool definition. This enables reusing the same
-        tool across multiple MCP servers with different configurations.
+        Each lookup (export) step's connection must be bound here, or each `tools/call` fails
+        with "Missing connection overrides. The following connection IDs must be overridden: …".
+        The export and router fields described below as not applied are stored but don't change
+        a call.
+      x-celigo-ai-guidance:
+        - |-
+          Bind each lookup step with an `exports[]` entry whose `_abstractId` and `_id` are both
+          the step's export id; add `_connectionId` to run that step on another connection. An
+          entry with `_connectionId` but no `_id` returns a 404, and binding only some of the
+          Tool's steps still fails the call with "Missing connection overrides".
+        - |-
+          A `connections[]` pair binds only when `_id` names a different connection than
+          `_abstractId`; it then re-maps the steps that use that connection. An identity pair
+          (`_abstractId` equal to `_id`) on a connection that doesn't require end-user
+          credentials leaves the steps unbound. When a step has both, its `exports[]` entry wins.
+        - |-
+          `connections[]` ids aren't validated on save, and the server caches its configuration,
+          so a saved change can take tens of seconds to reach `tools/call`.
       properties:
         connections:
           type: array
@@ -1619,9 +1638,9 @@ components:
         exports:
           type: array
           description: |
-            Export (lookup) overrides. Customize export resources used within the tool,
-            including connection bindings, scheduling, response mappings, and
-            adaptor-specific settings.
+            Export (lookup) step bindings. The binding (`_abstractId`, `_id`, and optionally
+            `_connectionId`) is applied to calls; the settings marked below as not applied are
+            stored but ignored.
           items:
             type: object
             properties:
@@ -1666,25 +1685,27 @@ components:
                   simple: Basic export that fetches all matching records on each run.
                   blob: Binary large object export for file-based data.
                   all: Export that retrieves all records without filtering.
-                description: Override the export type
+                description: Export type override. Not applied on an MCP server; stored, but calls ignore it.
               pageSize:
                 type: number
-                description: Override the page size for pagination
+                description: Page size override. Not applied on an MCP server; stored, but calls ignore it.
                 examples:
                   - 100
               skipRetries:
                 type: boolean
-                description: When true, skips retries on failure.
-                x-celigo-ai-guidance:
-                  - Whether to skip retries on failure
+                description: |-
+                  When true, skips retries on failure. Not applied on an MCP server; stored, but
+                  calls ignore it.
               proceedOnFailure:
                 type: boolean
-                description: When true, continues processing subsequent records after a failure.
-                x-celigo-ai-guidance:
-                  - Whether to continue processing on failure
+                description: |-
+                  When true, continues processing subsequent records after a failure. Not applied
+                  on an MCP server; stored, but calls ignore it.
               responseMapping:
                 type: object
-                description: Override the response field mappings
+                description: |-
+                  Response field mappings override. Not applied on an MCP server; stored, but calls
+                  ignore it.
                 properties:
                   fields:
                     type: array
@@ -1847,8 +1868,8 @@ components:
         routers:
           type: array
           description: |
-            Router overrides. Customize routing behavior for specific branches
-            within the tool, including branch filters and routing strategies.
+            Router overrides. On an MCP server `name`, `routeRecordsTo` and branch
+            `inputFilter` are stored but not applied to calls.
           items:
             type: object
             properties:
@@ -1859,7 +1880,7 @@ components:
                   - router_001
               name:
                 type: string
-                description: Override the router name
+                description: Router name override. Not applied on an MCP server; stored, but calls ignore it.
                 examples:
                   - route_by_region
               routeRecordsTo:
@@ -1870,7 +1891,7 @@ components:
                 x-enumDescriptions:
                   first_matching_branch: Routes each record to only the first branch whose criteria match.
                   all_matching_branches: Routes each record to every branch whose criteria match, creating copies.
-                description: Override the routing strategy
+                description: Routing strategy override. Not applied on an MCP server; stored, but calls ignore it.
               routeRecordsUsing:
                 type: string
                 enum:
@@ -1917,7 +1938,9 @@ components:
                         - Records routed to the North America region
                     inputFilter:
                       type: object
-                      description: Override the branch filter criteria
+                      description: |-
+                        Branch filter override. Not applied on an MCP server; stored, but calls
+                        ignore it.
                       properties:
                         version:
                           type: string

package/dist/processor.yml

@@ -23,7 +23,8 @@ tags:
 
       These are one-shot transformation calls — they do not create or modify
       any resources. Use them to test parsing rules, preview file definitions,
-      or transform data outside of a flow.
+      or transform data outside of a flow. The filter and Handlebars processors
+      test a step's filter rules or templates the same way.
 
       ## Processor descriptor schema
 
@@ -1047,6 +1048,212 @@ paths:
                           type: string
                   path:
                     type: string
+  /v1/processors/filter:
+    post:
+      x-internal: false
+      operationId: evaluateFilterRules
+      tags:
+        - Parsers & Generators
+      summary: Test filter rules against records
+      description: |-
+        Evaluates export and import filter rules (`Filter.expression`) against the records in `data` and
+        returns the records that pass. Nothing is saved and no flow runs, so it checks a rule before the
+        rule is saved on a step. Rules are validated as they are when a filter is saved: an unknown
+        operator or a bare `extract` is refused with 422.
+
+        Send each record bare, the way it reaches a step's filter. A record wrapped as
+        `{"record": {...}}` is evaluated as that wrapper, so field rules don't match it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - rules
+                - data
+              properties:
+                rules:
+                  type: object
+                  description: The filter expression to evaluate, in the shape of a step's `filter.expression`.
+                  required:
+                    - version
+                    - rules
+                  properties:
+                    version:
+                      type: string
+                      enum:
+                        - '1'
+                      x-enumDescriptions:
+                        '1': Version 1 of the Celigo expression-based filter format.
+                      description: Version of the filter format used by `rules`.
+                    rules:
+                      type: array
+                      description: Prefix-notation rule in the grammar of `Filter.expression.rules`.
+                      x-celigo-agent:
+                        - filter
+                      items: {}
+                data:
+                  type: array
+                  description: Records to evaluate, each a bare record object.
+                  items:
+                    type: object
+                    additionalProperties: true
+            examples:
+              default:
+                summary: Keep the records whose email has a value
+                value:
+                  rules:
+                    version: '1'
+                    rules:
+                      - notempty
+                      - - string
+                        - - extract
+                          - email
+                  data:
+                    - email: a@example.com
+                    - email: ''
+                    - {}
+      responses:
+        '200':
+          description: The records that pass the rules.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  mediaType:
+                    type: string
+                    description: Always `json` for the filter processor.
+                    enum:
+                      - json
+                    x-enumDescriptions:
+                      json: Response data is formatted as JSON.
+                  data:
+                    type: array
+                    description: The input records that pass the rules, unchanged and in input order.
+                    items:
+                      type: object
+                      additionalProperties: true
+                  duration:
+                    type: integer
+                    description: Processing time in milliseconds.
+              examples:
+                default:
+                  value:
+                    mediaType: json
+                    data:
+                      - email: a@example.com
+                    duration: 0
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          description: |-
+            The rules are invalid, for example an unknown operator ("Invalid operation: isnotempty.") or
+            an `extract` that is not wrapped in a type conversion ("Field operation extract must be called
+            by a Type Conversion Operation but was called by notempty.").
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /v1/processors/handlebars:
+    post:
+      x-internal: false
+      operationId: renderHandlebarsTemplate
+      tags:
+        - Parsers & Generators
+      summary: Render a Handlebars template
+      description: |-
+        Renders a Handlebars template against the object in `data` and returns the result. Nothing is
+        saved and no flow runs, so it tests a template or a helper before the template is saved on a
+        step.
+
+        `data` is the template's root context: `{{name}}` reads `data.name`. A template written for a
+        step reads the record as `{{record.<field>}}`, so send the record under `record`
+        (`"data": {"record": {...}}`). Double braces HTML-escape the value (`&` renders as `&amp;`);
+        triple braces insert it unchanged. A `timestamp` with no time zone renders in UTC.
+
+        An unknown helper is refused with 422. `GET /v1/processors` lists helpers under the handlebars
+        entry's `helperFunctions`, but that list is not complete: `eq` and `truncateWords`, for
+        example, render although it omits them, so render a doubtful helper once here before relying
+        on it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - rules
+                - data
+              properties:
+                rules:
+                  type: object
+                  required:
+                    - template
+                  properties:
+                    template:
+                      type: string
+                      description: The Handlebars template to render.
+                      x-celigo-agent:
+                        - handlebars
+                    resultMode:
+                      type: string
+                      description: Form of the result; `text` returns the rendered string.
+                      examples:
+                        - text
+                data:
+                  type: object
+                  additionalProperties: true
+                  description: Root context the template renders against.
+            examples:
+              step_template:
+                summary: Render a step template against a record
+                value:
+                  rules:
+                    template: '{{record.name}} | {{{record.name}}}'
+                    resultMode: text
+                  data:
+                    record:
+                      name: Smith & Sons
+      responses:
+        '200':
+          description: The rendered template.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  mediaType:
+                    type: string
+                    description: Always `text` for the handlebars processor.
+                    enum:
+                      - text
+                    x-enumDescriptions:
+                      text: Response data is the rendered text.
+                  data:
+                    description: |-
+                      The rendered result, normally a string. A template that renders only a helper's
+                      numeric result can come back as a JSON number.
+                  duration:
+                    type: integer
+                    description: Processing time in milliseconds.
+              examples:
+                default:
+                  value:
+                    mediaType: text
+                    data: Smith &amp; Sons | Smith & Sons
+                    duration: 0
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          description: |-
+            The template could not be rendered, for example because it calls a helper that does not
+            exist ('Missing helper: "first"').
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
 components:
   securitySchemes:
     bearerAuth:
@@ -1219,6 +1426,46 @@ components:
         traceKeysDuplicate:
           type: boolean
           description: When true, duplicate trace keys were detected in the output records.
+    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
   responses:
     401-unauthorized:
       description: |-