@celigo/api-specs 0.2.201 → 0.2.203

package/dist/job.yml

@@ -48,9 +48,10 @@ paths:
           Exception: for a caller with integration-only access, `_flowId` scopes
           a `type=flow` or `type=retry` query only together with
           `_integrationId` (below).
-        - **Child jobs** (`type=export` or `type=import`) — requires
-          `_flowJobId` or a resource ID filter (`_exportId` / `_importId`).
-          Returns the export/import sub-jobs within a parent flow job.
+        - **Child jobs** (`type=export`, `type=import`, or `type=tool`) — requires
+          `_flowJobId` or a resource ID filter (`_exportId` / `_importId`; for
+          `tool` jobs, `_importId` is the `ToolImport`'s id). Returns the step
+          jobs within a parent flow job.
 
         Job reads are authorized per integration. For a caller with
         integration-only access (an account share that populates
@@ -71,6 +72,11 @@ paths:
         forward, take the `createdAt` of the last record, subtract 1 ms, and
         pass it as `createdAt_lte`.
 
+        The query is validated strictly: a parameter the endpoint does not support
+        fails with `422 invalid_query_params` naming it, and a malformed value — an
+        unrecognized `type` or `status`, a non-numeric count filter, an unparseable
+        date, or a plain string where an array is expected — fails with `400`.
+
         A `queued` or `running` job created outside `createdAt_gte` /
         `createdAt_lte` is left out of a date-filtered list.
       parameters:
@@ -126,27 +132,27 @@ paths:
               - 69f54d6f47185f8c7a500597
           description: |-
             Filter by parent flow-job ID. Satisfies the required-param check.
-            Required when querying child jobs (`type=export` or `type=import`).
-        - name: _flowId_in
+            Required when querying child jobs (`type=export`, `type=import`, or
+            `type=tool`).
+        - name: _flowId_in[]
           in: query
+          style: form
+          explode: true
           schema:
-            type: string
-            examples:
-              - 69f54d6b7009ea11abad707a,69e83e7a75f7f8c14a12916e
-          description: |-
-            Comma-separated list of flow IDs to match. Works as an additional
-            filter but does **not** satisfy the required-param check alone.
-            `flowId_in` (without underscore) is accepted as an alias.
-        - name: status_in
-          in: query
-          schema:
-            type: string
+            type: array
+            items:
+              type: string
+              format: objectId
+              x-celigo-refModel: flows
             examples:
-              - completed,failed
+              - - 69f54d6b7009ea11abad707a
+                - 69e83e7a75f7f8c14a12916e
           description: |-
-            Comma-separated list of status values to match (e.g.
-            `completed,failed`). Works as an additional filter but does
-            **not** satisfy the required-param check alone.
+            Flow IDs to match, sent as one `_flowId_in[]=<id>` pair per ID (indexed
+            `_flowId_in[0]=<id>` also works). A plain `_flowId_in=<id>` value —
+            including a comma-separated list — fails with `400 invalid_query_param`.
+            Works as an additional filter but does **not** satisfy the
+            required-param check alone.
         - name: createdAt_lte
           in: query
           schema:
@@ -245,17 +251,19 @@ paths:
               - import
               - retry
               - bulk_retry
+              - tool
             x-enumDescriptions:
               flow: A parent flow-run job that orchestrates the full pipeline.
               export: A child job for an export step within a flow run.
               import: A child job for an import step within a flow run.
               retry: A retry of a single failed record from a previous job.
               bulk_retry: A bulk retry of multiple failed records from a previous job.
+              tool: A child job for a Tool step (a `ToolImport`) within a flow run.
           description: |-
             Filter by job type. `flow`, `retry`, and `bulk_retry` are
-            parent-level jobs; `export` and `import` are child jobs (require
-            `_flowJobId` or a resource-ID filter). Unrecognized values silently
-            return an empty response.
+            parent-level jobs; `export`, `import`, and `tool` are child jobs
+            (require `_flowJobId` or a resource-ID filter). An unrecognized value
+            fails with `400 invalid_url` ("type is not valid.").
       responses:
         '200':
           description: Array of job records matching the filters.
@@ -319,7 +327,13 @@ paths:
         '204':
           description: No jobs match the given filters.
         '400':
-          description: Required query parameters are missing or invalid.
+          description: |-
+            Required query parameters are missing (`invalid_query`), or a value is
+            malformed: an unrecognized `status` or a non-numeric `numSuccess_*` /
+            `numIgnore_*` filter (`invalid_query_param`), an array parameter sent as
+            a plain string (`invalid_query_param`), an unrecognized `type` or a
+            non-numeric `numError_*` filter (`invalid_url`), or an unparseable date
+            (`invalid_field`).
           content:
             application/json:
               schema:
@@ -349,6 +363,24 @@ paths:
                     errors:
                       - code: invalid_query_param
                         message: The query parameter "status" has invalid value.
+                array_as_string:
+                  summary: Array parameter sent as a plain value
+                  value:
+                    errors:
+                      - code: invalid_query_param
+                        message: The query parameter _flowId_in must be an array. Repeat the parameter for each value, e.g. _flowId_in[0]=value1&_flowId_in[1]=value2.
+                invalid_type:
+                  summary: Unrecognized type value
+                  value:
+                    errors:
+                      - code: invalid_url
+                        message: type is not valid.
+                invalid_date:
+                  summary: Unparseable date filter
+                  value:
+                    errors:
+                      - code: invalid_field
+                        message: 'The value provided for the field: ''createdAt_gte'' is invalid.'
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '422':
@@ -1323,9 +1355,9 @@ components:
         A job represents one execution of a flow/export/import (or a retry) in integrator.io.
         Jobs are read-only records created by the platform when executions occur.
 
-        Parent jobs (`type: flow`) carry aggregate counters; child jobs (`type: export` or `import`)
-        carry per-step counters -- do not sum both to avoid double-counting. `_exportId` on a parent
-        flow job references the page-generator export, not all exports in the flow.
+        Parent jobs (`type: flow`) carry aggregate counters; child jobs (`type: export`, `import`, or
+        `tool`) carry per-step counters -- do not sum both to avoid double-counting. `_exportId` on a
+        parent flow job references the page-generator export, not all exports in the flow.
       allOf:
         - $ref: '#/components/schemas/ResourceResponse'
         - type: object
@@ -1340,6 +1372,7 @@ components:
                 - flow
                 - retry
                 - bulk_retry
+                - tool
               x-enumDescriptions:
                 export: |-
                   A child job for an export step within a flow run: the flow's source export, or a
@@ -1349,10 +1382,14 @@ components:
                 flow: A parent flow-run job that orchestrates the full pipeline.
                 retry: A retry of a single failed record from a previous job.
                 bulk_retry: A bulk retry of multiple failed records from a previous job.
+                tool: |-
+                  A child job for a Tool step (a `ToolImport`) within a flow run. A lookup step inside
+                  the Tool gets its own `export` child job under the same flow job.
               x-celigo-ai-guidance:
                 - |-
                   - `flow`: a flow run (parent job)
                   - `export` / `import`: child jobs for an export/import step
+                  - `tool`: child job for a Tool step (`ToolImport`); a lookup step inside the Tool is listed as its own `export` child job of the same flow job
                   - `retry` / `bulk_retry`: error management retries
             status:
               type: string
@@ -1414,8 +1451,9 @@ components:
               readOnly: true
               description: |-
                 The export or import resource ID for this child job. Present on child
-                jobs (`type: export` or `type: import`) — check `type` to determine
-                whether this references an export or import resource.
+                jobs (`type: export`, `import`, or `tool`) — check `type`: an `export` job
+                references an export, an `import` job an import, and a `tool` job the
+                `ToolImport` that ran the Tool.
               examples:
                 - 69f54d6c1e7f3a22cc7848b2
             _retryOfJobId:
@@ -1507,8 +1545,8 @@ components:
                 chained into this one; absent on event-driven runs (webhook, real-time listener, and
                 stream page generators), which the inbound event starts. On a `retry` job: `auto`
                 for the platform's automatic intermittent-error retry, otherwise the `_id` of the
-                user who submitted the retry. Absent on `export` and `import` child jobs — the
-                parent flow job carries it.
+                user who submitted the retry. Absent on `export`, `import`, and `tool` child jobs —
+                the parent flow job carries it.
               examples:
                 - system
             canceledBy:
@@ -1565,7 +1603,8 @@ components:
               description: |-
                 Number of records processed successfully. On a parent flow job (`type: flow`) this is the
                 sum across every step in the run, so one record that passes through an export and an import
-                counts twice. On a child job (`type: export` or `import`) it is that step's count alone.
+                counts twice. On a child job (`type: export`, `import`, or `tool`) it is that step's count
+                alone.
                 For per-step counts, read the run with `GET /v1/jobs/{_id}/family` or list its children with
                 `GET /v1/jobs?_flowJobId={_id}&type=import`.
               examples:

package/dist/mcp-server.yml

@@ -780,6 +780,390 @@ paths:
           $ref: '#/components/responses/401-unauthorized'
         '404':
           $ref: '#/components/responses/404-not-found'
+  /v1/mcpservers/template/preview:
+    get:
+      x-internal: false
+      operationId: previewMcpServerTemplateUpload
+      tags:
+        - MCP Servers
+      summary: Preview an uploaded MCP server template
+      description: |-
+        Reads an MCP-server template ZIP you uploaded and returns the resource
+        docs installing it would create. Nothing is created. Get an upload URL
+        from `GET /v1/s3SignedURL?file_type=application/zip`, PUT the ZIP to its
+        `signedURL` with the header `x-amz-server-side-encryption: AES256`, then
+        pass that call's `runKey` here and to `POST /v1/mcpservers/template`.
+
+        The install runs the same ZIP checks with the same errors. Integration
+        template ZIPs use `GET /v1/integrations/template/preview`, which rejects
+        an MCP-server ZIP with a 400 `invalid_template` error.
+      parameters:
+        - name: runKey
+          in: query
+          required: true
+          description: |-
+            The `runKey` returned by `GET /v1/s3SignedURL` for the uploaded
+            template ZIP.
+          schema:
+            type: string
+            examples:
+              - 78f30205bdda4c4bb2a75eb121172250
+      responses:
+        '200':
+          description: Preview of the resources the install would create.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/McpServerTemplatePreview'
+              examples:
+                promptOnly:
+                  summary: Template with one inline prompt
+                  value:
+                    type: mcpserver
+                    objects:
+                      - model: McpServer
+                        doc:
+                          name: Support assistant
+                          description: ''
+                          relativeURI: /support-assistant
+                          disabled: true
+                          tools: []
+                          prompts:
+                            - name: summarize-ticket
+                              description: Summarize a support ticket.
+                              disabled: false
+                              arguments:
+                                - name: ticket
+                                  description: Ticket text.
+                                  required: true
+                              messagesTemplate:
+                                - role: user
+                                  contentType: text
+                                  template: Summarize {{ticket}}.
+                      - model: Prompt
+                        doc:
+                          name: summarize-ticket
+                          description: Summarize a support ticket.
+                          disabled: false
+                          arguments:
+                            - name: ticket
+                              description: Ticket text.
+                              required: true
+                          messagesTemplate:
+                            - role: user
+                              contentType: text
+                              template: Summarize {{ticket}}.
+                    stackRequired: false
+                connectionAndFile:
+                  summary: Template with a connection and a Celigo Storage file
+                  value:
+                    type: mcpserver
+                    objects:
+                      - model: McpServer
+                        doc:
+                          name: Support assistant
+                          description: ''
+                          relativeURI: /support-assistant
+                          disabled: true
+                          tools: []
+                          connections:
+                            - _connectionId: 6ab130000000000000000c01
+                              requiresEndUserCredentials: false
+                          resources:
+                            - fileKey: 6ab130000000000000000f01
+                              title: Support handbook
+                              disabled: false
+                              name: handbook.txt
+                              mimeType: text/plain
+                      - model: Connection
+                        doc:
+                          _id: 6ab130000000000000000c01
+                          type: http
+                          name: Support Desk API
+                          http:
+                            mediaType: json
+                            baseURI: https://api.example.com
+                            auth:
+                              type: custom
+                      - model: McpResource
+                        doc:
+                          fileKey: 6ab130000000000000000f01
+                          title: Support handbook
+                          disabled: false
+                          name: handbook.txt
+                          mimeType: text/plain
+                          size: 2048
+                    stackRequired: false
+        '400':
+          description: |-
+            The request or the ZIP is malformed: `runKey` is missing
+            (`missing_required_field`); the file is not a readable ZIP, including
+            one with two entries of the same name (`MCP_TEMPLATE_INVALID_ZIP`); or
+            an entry is invalid (`MCP_TEMPLATE_INVALID_ENTRY` — for example an
+            entry path containing `..`, a resource file the manifest declares but
+            the ZIP lacks, or a null tool row).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                missingRunKey:
+                  value:
+                    errors:
+                      - code: missing_required_field
+                        message: runKey is required.
+                invalidZip:
+                  value:
+                    errors:
+                      - code: MCP_TEMPLATE_INVALID_ZIP
+                        message: The MCP template zip is damaged or is not a zip file.
+                invalidEntry:
+                  value:
+                    errors:
+                      - code: MCP_TEMPLATE_INVALID_ENTRY
+                        message: The MCP template contains an invalid entry.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: The `runKey` does not match an uploaded file.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalidKey:
+                  value:
+                    errors:
+                      - code: invalid_key
+                        message: We couldn't find any integration template zip file.
+        '413':
+          description: |-
+            The ZIP exceeds an MCP template limit: more than 32 MiB uncompressed in
+            total, more than 500 entries, or a JSON entry over 1 MiB.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                tooLarge:
+                  value:
+                    errors:
+                      - code: MCP_TEMPLATE_ZIP_TOO_LARGE
+                        message: The MCP template zip exceeds the allowed size.
+        '422':
+          description: |-
+            The ZIP opened but is not an installable MCP-server template:
+            `mcpserver.json` is missing (`invalid_ref`, or `invalid_template` when
+            `integration.json` is missing too), a tool the server attaches is not
+            packed (`invalid_template`), an attached API or connection document is
+            not packed (`MCP_TEMPLATE_DEPENDENCY_MISSING`), or a resource file is
+            over 3 MiB or the manifest declares more than 100 of them
+            (`MCP_TEMPLATE_RESOURCE_TOO_LARGE`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                noManifest:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: mcpserver.json not found.
+                noManifests:
+                  value:
+                    errors:
+                      - code: invalid_template
+                        message: integration.json file is missing.
+                toolNotPacked:
+                  value:
+                    errors:
+                      - code: invalid_template
+                        message: MCP server references tool 6ab130000000000000000a01, which is missing from the template zip.
+                dependencyMissing:
+                  value:
+                    errors:
+                      - code: MCP_TEMPLATE_DEPENDENCY_MISSING
+                        message: The MCP template is missing connection 6ab130000000000000000c01.
+                resourceTooLarge:
+                  value:
+                    errors:
+                      - code: MCP_TEMPLATE_RESOURCE_TOO_LARGE
+                        message: Resource file 6ab130000000000000000f02 exceeds the allowed size.
+  /v1/mcpservers/template:
+    post:
+      x-internal: false
+      operationId: installMcpServerTemplateFromUpload
+      tags:
+        - MCP Servers
+      summary: Install an uploaded MCP server template
+      description: |-
+        Installs an MCP-server template from a ZIP you uploaded with the URL
+        from `GET /v1/s3SignedURL`. The body carries only that call's `runKey`;
+        the server's name and `relativeURI` come from the template. Check the
+        ZIP first with `GET /v1/mcpservers/template/preview`, which runs the
+        same ZIP checks with the same errors and creates nothing.
+
+        The response's `destination` envelope names what was created. A
+        template with only inline prompts creates the MCP server immediately,
+        disabled (`destination.resourceType` is `mcpservers`); when its
+        `relativeURI` is taken, the server gets a `-2`, `-3`, … suffix. A
+        template that also packs dependencies, such as a connection, creates an
+        Integration in install mode instead (`destination.resourceType` is
+        `integrations`), with an install step per packed connection and a last
+        step that copies the template's resources; no MCP server exists yet
+        when the request returns.
+
+        Every request starts a new install, so retrying after a timeout or an
+        ambiguous failure creates a duplicate server or install-mode
+        Integration.
+      x-celigo-ai-guidance:
+        - Never retry this POST after a timeout or an ambiguous failure — each request installs again; a prompt-only template yields a second server with a -2 suffix on its relativeURI, and a template with dependencies a second install-mode Integration.
+        - Branch the follow-up on destination.resourceType — "mcpservers" means the disabled MCP server already exists; "integrations" means the install continues in that Integration's install steps and the server does not exist yet.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - runKey
+              properties:
+                runKey:
+                  type: string
+                  description: |-
+                    The `runKey` returned by `GET /v1/s3SignedURL` for the uploaded
+                    template ZIP.
+                  examples:
+                    - 78f30205bdda4c4bb2a75eb121172250
+            examples:
+              default:
+                value:
+                  runKey: 78f30205bdda4c4bb2a75eb121172250
+      responses:
+        '201':
+          description: Installation started.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - destination
+                properties:
+                  destination:
+                    type: object
+                    description: The resource the install created first.
+                    required:
+                      - resourceType
+                      - resourceId
+                    properties:
+                      resourceType:
+                        type: string
+                        enum:
+                          - mcpservers
+                          - integrations
+                        x-enumDescriptions:
+                          mcpservers: The disabled MCP server, created immediately from a template with only inline prompts
+                          integrations: The install-mode Integration created for a template that packs dependencies, such as a connection
+                        description: |-
+                          Which resource type the install created — determines
+                          where the caller continues the setup.
+                      resourceId:
+                        type: string
+                        format: objectId
+                        description: |-
+                          The created resource's ID, in the collection named by
+                          `resourceType`.
+              examples:
+                promptOnly:
+                  summary: Prompt-only template — disabled MCP server
+                  value:
+                    destination:
+                      resourceType: mcpservers
+                      resourceId: 6ab130000000000000000d02
+                withConnection:
+                  summary: Template with a connection — Integration in install mode
+                  value:
+                    destination:
+                      resourceType: integrations
+                      resourceId: 6ab130000000000000000d01
+        '400':
+          description: |-
+            The request or the ZIP is malformed: `runKey` is missing
+            (`missing_required_field`); the file is not a readable ZIP, including
+            one with two entries of the same name (`MCP_TEMPLATE_INVALID_ZIP`); or
+            an entry is invalid (`MCP_TEMPLATE_INVALID_ENTRY` — for example an
+            entry path containing `..`, a resource file the manifest declares but
+            the ZIP lacks, or a null tool row).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                missingRunKey:
+                  value:
+                    errors:
+                      - code: missing_required_field
+                        message: runKey is required.
+                invalidZip:
+                  value:
+                    errors:
+                      - code: MCP_TEMPLATE_INVALID_ZIP
+                        message: The MCP template zip is damaged or is not a zip file.
+                invalidEntry:
+                  value:
+                    errors:
+                      - code: MCP_TEMPLATE_INVALID_ENTRY
+                        message: The MCP template contains an invalid entry.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: The `runKey` does not match an uploaded file.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalidKey:
+                  value:
+                    errors:
+                      - code: invalid_key
+                        message: We couldn't find any integration template zip file.
+        '413':
+          description: |-
+            The ZIP exceeds an MCP template limit: more than 32 MiB uncompressed in
+            total, more than 500 entries, or a JSON entry over 1 MiB.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                tooLarge:
+                  value:
+                    errors:
+                      - code: MCP_TEMPLATE_ZIP_TOO_LARGE
+                        message: The MCP template zip exceeds the allowed size.
+        '422':
+          description: |-
+            The ZIP is not an installable MCP-server template, so nothing was
+            created: the same checks and codes as the preview (`invalid_ref`,
+            `invalid_template`, `MCP_TEMPLATE_DEPENDENCY_MISSING`,
+            `MCP_TEMPLATE_RESOURCE_TOO_LARGE`). Retrying with the same ZIP fails
+            the same way.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                noManifest:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: mcpserver.json not found.
+                dependencyMissing:
+                  value:
+                    errors:
+                      - code: MCP_TEMPLATE_DEPENDENCY_MISSING
+                        message: The MCP template is missing connection 6ab130000000000000000c01.
   /v1/mcpservers/template/{_templateId}:
     post:
       x-internal: false
@@ -4159,6 +4543,64 @@ components:
       minItems: 1
       items:
         $ref: '#/components/schemas/JsonPatchOperation'
+    McpServerTemplatePreview:
+      type: object
+      description: |-
+        What installing an uploaded MCP-server template ZIP would create.
+        `objects[]` lists each resource doc tagged by `model`. Packed docs keep
+        the template's placeholder ids; the install assigns new ones.
+      required:
+        - type
+        - objects
+        - stackRequired
+      properties:
+        type:
+          type: string
+          enum:
+            - mcpserver
+          x-enumDescriptions:
+            mcpserver: The ZIP is an MCP-server template; install it with `POST /v1/mcpservers/template`
+          description: |-
+            Kind of template the uploaded ZIP holds. Always `mcpserver` on this
+            route — a ZIP without `mcpserver.json`, such as an integration
+            template, is rejected before a preview is built.
+          examples:
+            - mcpserver
+        objects:
+          type: array
+          description: |-
+            Resource docs the install would create, in order: the `McpServer`
+            doc, then each document packed in the ZIP (a `Connection`, for
+            example), then one `Prompt` entry per inline prompt and one
+            `McpResource` entry per Celigo Storage file the server serves. The
+            ZIP's `integration.json` is never listed.
+          items:
+            type: object
+            description: One resource doc tagged with its model type.
+            required:
+              - model
+              - doc
+            properties:
+              model:
+                type: string
+                description: |-
+                  Resource class this doc describes: `McpServer`, `Prompt`, or
+                  `McpResource` for the server and what it serves, otherwise the
+                  model of the packed document, such as `Connection`.
+                examples:
+                  - Connection
+              doc:
+                type: object
+                description: |-
+                  The resource document as packed in the template. The `McpServer`
+                  doc has no `_id`; an `McpResource` doc also carries the file's
+                  `size` in bytes.
+                additionalProperties: true
+        stackRequired:
+          type: boolean
+          description: |-
+            When true, the template packs something that runs on a stack, such
+            as a wrapper connection.
     DependencyEntry:
       type: object
       description: A single resource that depends on the queried resource.