@celigo/api-specs 0.2.201 → 0.2.202

package/dist/alert.yml

@@ -513,6 +513,10 @@ paths:
 
         Requires permission to read the alert (`get:alert:model`). Returns `403`
         when `ENABLE_PROACTIVE_ALERTS` is off or the caller lacks access.
+
+        The history stays readable after the alert is deleted, even though the alert
+        itself then reads 404. The same entries also appear in the integration's audit
+        log (`GET /v1/integrations/{_id}/audit`).
       parameters:
         - name: _id
           in: path
@@ -604,6 +608,14 @@ paths:
                       description: Alert id.
                       examples:
                         - 674a1b2c3d4e5f6789012345
+                    resourceName:
+                      type: string
+                      description: |-
+                        Display name of the alert: `<type label> - <flow name>` for a flow-level
+                        alert, `<type label> - All flows (<integration name>)` for an
+                        integration-level alert.
+                      examples:
+                        - Long runtime - All flows (Shopify to NetSuite)
                     event:
                       type: string
                       description: Mutation event type.
@@ -664,26 +676,41 @@ paths:
                         properties:
                           fieldPath:
                             type: string
-                            description: Dot-notation path of the changed field.
+                            description: |-
+                              Dot-notation path of the changed field. A recipient change is reported
+                              as `recipients`, listing the recipients' email addresses instead of user
+                              ids.
                             examples:
-                              - longRuntime.thresholdMinutes
+                              - longRuntime
                           oldValue:
                             description: Previous value (absent on create).
                           newValue:
                             description: New value (absent on delete).
                     deletedInfo:
                       type: object
-                      description: Metadata about the deleted resource. Present on `delete` events.
+                      description: |-
+                        Metadata about the deleted alert. Once the alert is deleted, every entry in its
+                        history carries it, not only the `delete` entry.
                       properties:
                         name:
                           type: string
-                          description: Name of the resource at the time of deletion.
+                          description: Display name of the alert at the time of deletion.
+                          examples:
+                            - Long runtime - All flows (Shopify to NetSuite)
+                        _integrationId:
+                          type: string
+                          format: objectId
+                          x-celigo-refModel: integrations
+                          description: Integration the alert belonged to.
+                          examples:
+                            - 5e5eb06fdd83ed4f8206a4ea
               examples:
                 default:
                   value:
                     - _id: 69e38cb1a749d34a9732a270
                       resourceType: alert
                       _resourceId: 674a1b2c3d4e5f6789012345
+                      resourceName: Long runtime - All flows (Shopify to NetSuite)
                       source: api
                       event: update
                       time: '2026-04-18T13:52:49.729Z'
@@ -692,9 +719,11 @@ paths:
                         email: user@example.com
                         name: Jane Doe
                       fieldChanges:
-                        - fieldPath: longRuntime.thresholdMinutes
-                          oldValue: 30
-                          newValue: 45
+                        - fieldPath: longRuntime
+                          oldValue:
+                            thresholdMinutes: 30
+                          newValue:
+                            thresholdMinutes: 45
         '204':
           description: No audit entries exist for this alert.
         '400':

package/dist/audit.yml

@@ -104,7 +104,6 @@ paths:
               - import
               - integration
               - lookupcache
-              - mcpoauthprovider
               - mcpserver
               - networkpolicy
               - notification
@@ -142,10 +141,9 @@ paths:
               import: Import resource for writing data to a destination system.
               integration: Integration workspace resource.
               lookupcache: Lookup cache resource for in-memory key-value stores.
-              mcpoauthprovider: MCP OAuth provider resource.
               mcpserver: MCP server resource for AI agent tool hosting.
               networkpolicy: Network policy resource (IP allow/deny lists).
-              notification: Notification subscription resource.
+              notification: Notification subscription resource. Filtering on `alert` also returns these entries.
               revision: Revision snapshot resource for version control.
               role: End-user role resource.
               script: Script resource for custom JavaScript hooks.
@@ -547,7 +545,6 @@ paths:
               - import
               - integration
               - lookupcache
-              - mcpoauthprovider
               - mcpserver
               - notification
               - revision
@@ -582,9 +579,8 @@ paths:
               import: Import resource for writing data to a destination system.
               integration: Integration workspace resource.
               lookupcache: Lookup cache resource for in-memory key-value stores.
-              mcpoauthprovider: MCP OAuth provider resource.
               mcpserver: MCP server resource for AI agent tool hosting.
-              notification: Notification subscription resource.
+              notification: Notification subscription resource. Filtering on `alert` also returns these entries.
               revision: Revision snapshot resource for version control.
               role: End-user role resource.
               script: Script resource for custom JavaScript hooks.
@@ -822,7 +818,6 @@ paths:
               - imports
               - integrations
               - lookupcaches
-              - mcpoauthproviders
               - mcpservers
               - networkpolicies
               - revisions
@@ -850,9 +845,8 @@ paths:
               iclients: iClient shared credential resources.
               idpconfigs: End-user identity provider configuration resources.
               imports: Import resources.
-              integrations: Integration workspace resources.
+              integrations: Integration workspace resources. The history also includes the alerts set on the integration or its flows, deleted ones too.
               lookupcaches: Lookup cache resources.
-              mcpoauthproviders: MCP OAuth provider resources.
               mcpservers: MCP server resources.
               networkpolicies: Network policy resources.
               revisions: Revision snapshot resources.
@@ -1060,7 +1054,6 @@ paths:
               - imports
               - integrations
               - lookupcaches
-              - mcpoauthproviders
               - mcpservers
               - networkpolicies
               - revisions
@@ -1088,9 +1081,8 @@ paths:
               iclients: iClient shared credential resources.
               idpconfigs: End-user identity provider configuration resources.
               imports: Import resources.
-              integrations: Integration workspace resources.
+              integrations: Integration workspace resources. The history also includes the alerts set on the integration or its flows, deleted ones too.
               lookupcaches: Lookup cache resources.
-              mcpoauthproviders: MCP OAuth provider resources.
               mcpservers: MCP server resources.
               networkpolicies: Network policy resources.
               revisions: Revision snapshot resources.
@@ -1286,7 +1278,6 @@ paths:
               - imports
               - integrations
               - lookupcaches
-              - mcpoauthproviders
               - mcpservers
               - networkpolicies
               - revisions
@@ -1312,9 +1303,8 @@ paths:
               iclients: iClient shared credential resources.
               idpconfigs: End-user identity provider configuration resources.
               imports: Import resources.
-              integrations: Integration workspace resources.
+              integrations: Integration workspace resources. The export also includes the alerts set on the integration or its flows, deleted ones too.
               lookupcaches: Lookup cache resources.
-              mcpoauthproviders: MCP OAuth provider resources.
               mcpservers: MCP server resources.
               networkpolicies: Network policy resources.
               revisions: Revision snapshot resources.
@@ -1377,7 +1367,10 @@ components:
       properties:
         fieldPath:
           type: string
-          description: Dot-path to the changed field (e.g., `settings.foo.bar`).
+          description: |-
+            Dot-path to the changed field (e.g., `settings.foo.bar`). On `alert` entries a recipient
+            change is reported as `recipients`, with `oldValue` and `newValue` listing the recipients'
+            email addresses instead of user ids.
           examples:
             - http.auth.token.token
         oldValue:
@@ -1397,7 +1390,7 @@ components:
           type: string
           format: objectId
           x-celigo-refModel: integrations
-          description: Integration id context (for flow/sync-related events).
+          description: Integration id context (for flow/sync-related and alert events).
           examples:
             - 60a2c4e6f321d800129a1a3c
         _abstractFlowId:
@@ -1459,8 +1452,11 @@ components:
           type: string
           readOnly: true
           description: |-
-            Resource type that the audit entry applies to. `fileserver` appears only in
-            returned entries and cannot be used as a `resourceType` filter.
+            Resource type that the audit entry applies to. `fileserver` and
+            `mcpoauthprovider` appear only in returned entries and cannot be used as a
+            `resourceType` filter. MCP OAuth providers have no per-resource audit route
+            either, so their entries are read from `GET /v1/audit` without a
+            `resourceType` filter.
           enum:
             - accesstoken
             - agent
@@ -1542,6 +1538,15 @@ components:
           description: Resource id the audit entry applies to.
           examples:
             - 69497ca1b40d3e24522a7f3c
+        resourceName:
+          type: string
+          readOnly: true
+          description: |-
+            Display name of the alert, present on `alert` entries only: `<type label> - <flow name>`
+            for a flow-level alert, `<type label> - All flows (<integration name>)` for an
+            integration-level alert.
+          examples:
+            - Long runtime - All flows (Shopify to NetSuite)
         source:
           type: string
           readOnly: true
@@ -1692,7 +1697,6 @@ components:
               - import
               - integration
               - lookupcache
-              - mcpoauthprovider
               - mcpserver
               - networkpolicy
               - notification
@@ -1728,10 +1732,9 @@ components:
               import: Import resource for writing data to a destination system.
               integration: Integration workspace resource.
               lookupcache: Lookup cache resource for in-memory key-value stores.
-              mcpoauthprovider: MCP OAuth provider resource.
               mcpserver: MCP server resource for AI agent tool hosting.
               networkpolicy: Network policy resource (IP allow/deny lists).
-              notification: Notification subscription resource.
+              notification: Notification subscription resource. Filtering on `alert` also returns these entries.
               revision: Revision snapshot resource for version control.
               role: End-user role resource.
               script: Script resource for custom JavaScript hooks.
@@ -1915,7 +1918,6 @@ components:
             - import
             - integration
             - lookupcache
-            - mcpoauthprovider
             - mcpserver
             - networkpolicy
             - notification
@@ -1951,10 +1953,9 @@ components:
             import: Import resource for writing data to a destination system.
             integration: Integration workspace resource.
             lookupcache: Lookup cache resource for in-memory key-value stores.
-            mcpoauthprovider: MCP OAuth provider resource.
             mcpserver: MCP server resource for AI agent tool hosting.
             networkpolicy: Network policy resource (IP allow/deny lists).
-            notification: Notification subscription resource.
+            notification: Notification subscription resource. Filtering on `alert` also returns these entries.
             revision: Revision snapshot resource for version control.
             role: End-user role resource.
             script: Script resource for custom JavaScript hooks.

package/dist/filedefinition.yml

@@ -13,8 +13,9 @@ info:
       They define how rows, columns, segments, and elements are parsed or generated,
       including delimiters, padding, and hierarchical rule structures.
 
-      EDI file definitions (X12 and EDIFACT formats) require a valid `globalId` that
-      maps to a known standard document definition, and may require an EDI license.
+      EDI file definitions (X12 and EDIFACT formats) carry a `globalId` that maps to a
+      known standard document definition; on an EDI-licensed account the server assigns
+      one when a create omits it.
 servers:
   - url: https://api.integrator.io
     description: Production (US / default region)
@@ -36,7 +37,7 @@ tags:
 
       Four formats are supported: `delimited` (CSV/TSV), `delimited/x12` (EDI X12),
       `delimited/edifact` (EDI EDIFACT), and `fixed` (fixed-width). EDI formats
-      require a `globalId` linking to a standard document definition.
+      carry a `globalId` linking to a standard document definition.
 
       ## File definition schema
 
@@ -204,9 +205,10 @@ paths:
           $ref: '#/components/responses/422-unprocessable-entity'
       x-celigo-ai-guidance:
         - |-
-          For EDI formats (`delimited/x12` or `delimited/edifact`), a valid `globalId`
-          is required when the account has an EDI license enabled. The `globalId` must
-          reference a known standard document definition.
+          For EDI formats (`delimited/x12` or `delimited/edifact`) on an EDI-licensed
+          account, the server assigns a `globalId` when the body omits one; a supplied
+          `globalId` must reference a known standard document definition, or the create
+          fails with 422 `invalid_global_id`.
         - |-
           For `format: fixed`, send `version`, `fixed.rowDelimiter` and `fixed.paddingChar`;
           without them the create fails with 422 and nothing is saved. Columns are read in
@@ -274,7 +276,8 @@ paths:
         Replaces the file definition with the provided configuration. This
         is a full replace -- include all fields you want to keep. `format`
         cannot be changed between `fixed` and `delimited` families after
-        creation, and `globalId` is immutable for EDI formats.
+        creation, and `globalId` is immutable for EDI formats: a PUT that sends a
+        different value, or omits it, keeps the stored id.
       operationId: updateFileDefinition
       tags:
         - File Definitions
@@ -1025,8 +1028,8 @@ components:
             - fixed
           x-enumDescriptions:
             delimited: Standard delimited files (CSV, TSV, etc.).
-            delimited/x12: EDI X12 format. Requires `globalId` when EDI license is enabled.
-            delimited/edifact: EDI EDIFACT format. Requires `globalId` when EDI license is enabled.
+            delimited/x12: EDI X12 format. Carries a `globalId`, assigned by the server when a create on an EDI-licensed account omits it.
+            delimited/edifact: EDI EDIFACT format. Carries a `globalId`, assigned by the server when a create on an EDI-licensed account omits it.
             fixed: Fixed-width positional format.
         documentType:
           type: string
@@ -1039,15 +1042,21 @@ components:
           description: EDI document type for acknowledgement documents.
         globalId:
           type: string
-          description: |-
-            Entry in the platform's registry of standard EDI document definitions that this
-            definition is built from. On an EDI-licensed account an X12 or EDIFACT create without
-            it fails with 422 `global_id_not_provided`, and one naming an id the registry doesn't
-            have fails with 422 `invalid_global_id`. No public route lists the registry, so copy the
-            `globalId` of an existing definition for the same standard document. Immutable after
-            creation.
+          description: |
+            Global identifier mapping to a known EDI standard document definition.
+
+            For EDI formats (`delimited/x12` or `delimited/edifact`) on an account
+            with an EDI license, a create that omits it gets one assigned from the
+            EDI catalog, and a supplied value must be a catalog entry (an unknown one
+            fails the create with 422 `invalid_global_id`). Immutable after creation:
+            a PUT that sends a different value, or none, keeps the stored id.
           examples:
-            - Generic-4010-850-PurchaseOrder
+            - 3c7a8f2e-1234-5678-9abc-def012345678
+          x-celigo-ai-guidance:
+            - |-
+              Send the catalog globalId of the document when you know it. When it is omitted the
+              server picks the id, and a description naming another document type did not change
+              the pick — an X12 create described as an 856 got the same id as a bare X12 create.
         rules:
           type: array
           x-celigo-agent:

package/dist/filestorage.yml

@@ -34,7 +34,9 @@ paths:
         `partUrls`, and `completeUrl` for larger files. Upload the bytes directly
         to those URLs — a single PUT must carry the
         `x-amz-server-side-encryption: AES256` header — then the item flips to
-        active once S3 confirms it; no further API call is needed. Each URL's
+        active once S3 confirms it; no further API call is needed. If the
+        uploaded object is empty (0 bytes), the file is not activated: it is
+        deleted permanently, without passing through the recycle bin. Each URL's
         lifetime is in its `X-Amz-Expires` parameter; once every part already
         issued has been uploaded, a multipart upload fetches further part URLs by
         posting again with the item's `_id`, `uploadId`, and `issuedPartsCount`,
@@ -222,7 +224,12 @@ paths:
                   downloadUrl:
                     type: string
                     format: uri
-                    description: Presigned S3 URL to GET the file's bytes from.
+                    description: |-
+                      Presigned S3 URL to GET the file's bytes from. The bytes are
+                      served as an attachment named after the item: the
+                      `Content-Disposition` header carries an ASCII `filename` in
+                      which non-ASCII characters are replaced with `_`, plus
+                      `filename*=UTF-8''` with the full name percent-encoded.
                     examples:
                       - https://integrator-file-storage.s3.us-west-2.amazonaws.com/file-storage/...
                   expiresIn:
@@ -611,6 +618,17 @@ paths:
                           description: Folder name.
                           examples:
                             - My Files
+                        _integrationId:
+                          type: string
+                          format: objectId
+                          x-celigo-refModel: integrations
+                          description: |-
+                            Integration whose system folder tree contains the listed
+                            folder. Present only on the last entry (the listed folder
+                            itself), and only when that folder is the integration's
+                            root folder or inside it.
+                          examples:
+                            - 6ab1e7ab38d7733b4594d0d2
               examples:
                 listMode:
                   summary: List a folder's children
@@ -839,7 +857,10 @@ paths:
 
         Only files are looked up: a folder's id is treated as unknown, so it
         fails the request or comes back as a `notFound` entry. Read folder
-        metadata from `GET /v1/storage/items`.
+        metadata from `GET /v1/storage/items`. A pending file is returned, as
+        active, once its bytes have landed in storage, even if the upload has not
+        finalized yet; a pending file whose bytes have not been uploaded is
+        treated as unknown.
       operationId: batchGetStorageItems
       tags:
         - File Storage
@@ -1293,9 +1314,12 @@ paths:
         Updates an item's `name` and/or `description`. Renaming keeps the item's
         `_id` stable, so references from flows, exports, imports, and tokens
         survive; a name already held by another live item in the same folder is
-        rejected with 409 `STORAGE_ITEM_ALREADY_EXISTS`. To move an item to a
-        different folder, use `PATCH /v1/storage/items/{_id}/move`; to replace a
-        file's content, use `PATCH /v1/storage/items/{_id}/replace`.
+        rejected with 409 `STORAGE_ITEM_ALREADY_EXISTS`. An integration's root
+        folder (`isSystem`) can be renamed and described too; renaming the
+        integration updates only the folder's `integrationName`, never its
+        `name`. To move an item to a different folder, use
+        `PATCH /v1/storage/items/{_id}/move`; to replace a file's content, use
+        `PATCH /v1/storage/items/{_id}/replace`.
       operationId: updateStorageItem
       tags:
         - File Storage
@@ -1450,7 +1474,9 @@ paths:
         placement are preserved, so every reference to the file stays intact — use
         this instead of delete-and-recreate when a file is referenced by flows or
         exports. The previous content remains downloadable until the replacement
-        finalizes. Rename with `PUT /v1/storage/items/{_id}` instead; this
+        finalizes. Uploading empty (0-byte) content does not replace it: the file
+        itself is deleted permanently, without passing through the recycle bin.
+        Rename with `PUT /v1/storage/items/{_id}` instead; this
         endpoint does not accept a name.
       operationId: replaceStorageFileContent
       tags:
@@ -1565,7 +1591,13 @@ paths:
         file: the destination file keeps its `_id` and takes the source file's
         content, its previous content is discarded, and the source file's `_id`
         is removed — neither goes to the recycle bin, so references to the
-        source file break. A soft-deleted source folder may be
+        source file break. A sub-folder whose name the destination also holds as
+        a folder is merged into it the same way. When the names match but the
+        types differ (a file against a folder), both are kept: the destination
+        item is unchanged, and the source item moves in with its `_id` under the
+        first free `<name> (k)` — the suffix follows the full name, so
+        `report.pdf` lands as `report.pdf (1)`, or `report.pdf (2)` when
+        `report.pdf (1)` is taken. A soft-deleted source folder may be
         merged, which restores its contents into the destination. Folders only —
         move individual files with the move endpoint. Requires delete access on
         the source folder and write access on the destination.
@@ -2425,7 +2457,7 @@ components:
         size:
           type: integer
           format: int64
-          minimum: 0
+          minimum: 1
           description: |-
             Declared size in bytes. Used to reserve quota up front. When omitted,
             the backend reserves a worst-case estimate (1 GB for single,
@@ -2765,6 +2797,18 @@ components:
             integration purges them.
           examples:
             - 6ab1e7ab38d7733b4594d0d2
+        _fileServerAccountId:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: fileserveraccounts
+          description: |-
+            File Server account that uploaded the file over SFTP, or that most
+            recently replaced its content over SFTP. Absent for folders and for
+            files uploaded through this API; replacing the content through this
+            API keeps the current value.
+          examples:
+            - 6ac0f3e1b2d4a5001c7e9f10
         integrationName:
           type: string
           readOnly: true
@@ -2772,6 +2816,9 @@ components:
             Name of the integration an integration root folder belongs to. Present
             only on that root folder (the `isSystem` folder at the account root);
             items inside the tree carry `_integrationId` but not this field.
+            Follows the integration's name when the integration is renamed, while
+            the folder's own `name` keeps the value it was created with or last
+            renamed to, so the two can differ.
           examples:
             - Order to cash
         __ancestorIds:
@@ -2802,10 +2849,15 @@ components:
           maxLength: 256
           readOnly: true
           description: |-
-            Media type recorded at upload time, used to set the download
-            Content-Type. Present when type is file; absent for folders and for
-            files uploaded without a declared type. Matched case-sensitively by
-            the `mimeType` and `mimeType_nin` list filters.
+            Media type used to set the download Content-Type. Present when type is
+            file; absent for folders and for files uploaded through this API
+            without a declared type. A file uploaded over the SFTP file server gets
+            the type its name's extension maps to, ignoring a trailing `.filepart`,
+            `.part`, or `.tmp`, or `application/octet-stream` when the extension is
+            unknown. An SFTP rename replaces an absent or `application/octet-stream`
+            value when the new extension maps to a known type; renames made with an
+            API token leave the value unchanged. Matched case-sensitively by the
+            `mimeType` and `mimeType_nin` list filters.
           examples:
             - image/png
         description:
@@ -2831,11 +2883,13 @@ components:
           type: boolean
           readOnly: true
           description: |-
-            When true, the platform created the item (for example a system or
-            integration folder) and protects it — rename, move, content replace,
-            copy, delete, and purge are rejected with 403
-            `STORAGE_SYSTEM_ITEM_PROTECTED` ("System items cannot be modified or
-            deleted").
+            When true, the platform created the item (for example an
+            integration's root folder) and protects it: moving it, merging it
+            into another folder, deleting it, and restoring or purging it from
+            the recycle bin are rejected with 403 `STORAGE_SYSTEM_ITEM_PROTECTED`
+            ("System items cannot be modified or deleted"; a per-item error in a
+            bulk move). Renaming it and editing its description with
+            `PUT /v1/storage/items/{_id}` are allowed.
         deletedAt:
           type: string
           format: date-time
@@ -3049,7 +3103,7 @@ components:
         size:
           type: integer
           format: int64
-          minimum: 0
+          minimum: 1
           description: |-
             Declared size in bytes of the replacement content, used to reserve
             quota. Reconciled to the real size when the upload finalizes.

package/dist/integration.yml

@@ -1597,11 +1597,13 @@ paths:
       operationId: registerConnectionToIntegrationByBody
       tags:
         - Integrations
-      summary: Register a connection to an integration (by body)
+      summary: Register connections to an integration (by body)
       description: |-
-        Registers a single connection to the integration by passing the connection id in the request
-        body. Alternatively, use `PUT /v1/integrations/{_id}/connections/{_connectionId}/register` to
-        register by path parameter.
+        Registers one or more connections to the integration, adding them to its
+        `_registeredConnectionIds` list. The request body is a bare JSON array of
+        connection ids; duplicates and ids that are already registered are ignored.
+        Alternatively, use `PUT /v1/integrations/{_id}/connections/{_connectionId}/register`
+        to register a single connection by path parameter.
       parameters:
         - name: _id
           in: path
@@ -1618,24 +1620,40 @@ paths:
         content:
           application/json:
             schema:
-              type: object
-              required:
-                - _connectionId
-              properties:
-                _connectionId:
-                  type: string
-                  format: objectId
-                  x-celigo-refModel: connections
-                  examples:
-                    - 626168f90b6ef816b50c82d7
-                  description: The id of the connection to register.
+              type: array
+              description: Connection ids to register.
+              items:
+                type: string
+                format: objectId
+                x-celigo-refModel: connections
             examples:
               default:
                 value:
-                  _connectionId: 69680d7111d1437fbcbce534
+                  - 626168f90b6ef816b50c82d7
+                  - 6553ebdeda62bb22e7fa81ff
       responses:
         '204':
-          description: Connection registered successfully. No body returned.
+          description: Connections registered successfully. No body returned.
+        '400':
+          description: |-
+            The body is not a JSON array (`invalid_request`), or an entry in the
+            array is not a valid ObjectId (`invalid_ref`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                notAnArray:
+                  summary: 'An object body such as {"_connectionId": "..."}'
+                  value:
+                    errors:
+                      - code: invalid_request
+                        message: Request body should be a JSON array of _connectionId values.
+                invalidId:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _connectionId.
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '404':
@@ -1934,11 +1952,25 @@ paths:
         '204':
           description: Lookup caches registered successfully. No body returned.
         '400':
-          description: An entry in the array is not a valid ObjectId.
+          description: |-
+            The body is not a JSON array (`invalid_request`), or an entry in the
+            array is not a valid ObjectId (`invalid_ref`).
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+              examples:
+                notAnArray:
+                  summary: 'An object body such as {"_lookupCacheId": "..."}'
+                  value:
+                    errors:
+                      - code: invalid_request
+                        message: Request body should be a JSON array of _lookupCacheId values.
+                invalidId:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _lookupCacheId.
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '404':

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.

package/dist/template.yml

@@ -511,6 +511,12 @@ paths:
         Previews the resources that would be created by installing a template
         from an uploaded zip file. The `runKey` query parameter ties this request
         to a previously uploaded zip (obtained from `GET /v1/s3SignedURL`).
+
+        The zip must be at most 1 MB, and its entries at most 64 MB once
+        uncompressed; the preview applies the same checks as
+        `POST /v1/integrations/template`. An MCP server template (a zip with a
+        root `mcpserver.json`) is refused here: preview it with
+        `GET /v1/mcpservers/template/preview`.
       parameters:
         - name: runKey
           in: query
@@ -535,6 +541,7 @@ paths:
                 preview:
                   summary: Template that creates an integration and one connection
                   value:
+                    type: integration
                     stackRequired: false
                     objects:
                       - model: Integration
@@ -551,7 +558,10 @@ paths:
                             wsdlVersion: '2020.2'
                             concurrencyLevel: 1
         '400':
-          description: Missing required `runKey` query parameter.
+          description: |-
+            Missing required `runKey` query parameter, the uploaded zip is larger
+            than 1 MB (`invalid_zip`), or the zip is an MCP server template
+            (`invalid_template`).
           content:
             application/json:
               schema:
@@ -562,6 +572,17 @@ paths:
                     errors:
                       - code: missing_required_field
                         message: runKey is required.
+                zipTooLarge:
+                  value:
+                    errors:
+                      - code: invalid_zip
+                        message: Template can't be imported as the maximum allowed zip file size is 1 MB. Please re-import a new zip file.
+                mcpServerTemplate:
+                  summary: A zip with a root mcpserver.json
+                  value:
+                    errors:
+                      - code: invalid_template
+                        message: MCP server templates cannot be installed through the Integration template path. Use Upload MCP.
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '403':
@@ -577,7 +598,26 @@ paths:
                   value:
                     errors:
                       - code: invalid_key
-                        message: The specified runKey was not found.
+                        message: We couldn't find any integration template zip file.
+        '422':
+          description: |-
+            The zip's entries exceed 64 MB uncompressed (`invalid_zip`), or an entry
+            is corrupted (`corrupted_file`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                uncompressedTooLarge:
+                  value:
+                    errors:
+                      - code: invalid_zip
+                        message: Template can't be imported as the uncompressed zip contents exceed the maximum allowed size. Please re-import a smaller zip file.
+                corrupted:
+                  value:
+                    errors:
+                      - code: corrupted_file
+                        message: Looks like the uploaded zip is corrupted. Please contact Celigo support if the issue persists.
   /v1/integrations/template:
     post:
       x-internal: false
@@ -594,6 +634,12 @@ paths:
         installed integration receives new connection `_id`s. Configure each
         connection in the new integration before running its flows; connection
         `_id`s that existed only in the zip are not preserved.
+
+        The zip must be at most 1 MB, and its entries at most 64 MB once
+        uncompressed. A zip that breaks either limit, or holds a corrupted entry,
+        is refused before anything is created. So is an MCP server template (a
+        zip with a root `mcpserver.json`): install it with
+        `POST /v1/mcpservers/template`.
       requestBody:
         required: true
         content:
@@ -626,21 +672,43 @@ paths:
                 value:
                   runKey: abc123def456
       responses:
-        '200':
-          description: Template installed from uploaded zip.
+        '201':
+          description: |-
+            Template installed. Each entry names a document the install created;
+            the `Integration` entry is the new integration.
           content:
             application/json:
               schema:
-                type: object
-                description: The created integration and related resources.
-                additionalProperties: true
+                type: array
+                items:
+                  type: object
+                  required:
+                    - model
+                    - _id
+                  properties:
+                    model:
+                      type: string
+                      description: Model of the created document.
+                      examples:
+                        - Integration
+                    _id:
+                      type: string
+                      format: objectId
+                      description: Id of the created document.
+                      examples:
+                        - 6405b9d73496e05ff253d587
               examples:
                 installed:
                   summary: Integration created from the uploaded zip
                   value:
-                    _integrationId: 6405b9d73496e05ff253d587
+                    - model: Integration
+                      _id: 6405b9d73496e05ff253d587
         '400':
-          description: Missing required `runKey` in request body.
+          description: |-
+            Missing required `runKey` in request body, the uploaded zip is larger
+            than 1 MB (`invalid_zip`), the zip is an MCP server template
+            (`invalid_template`), or the preview reports `stackRequired: true` and
+            the body has no `_stackId` (`stack_not_found`).
           content:
             application/json:
               schema:
@@ -651,12 +719,31 @@ paths:
                     errors:
                       - code: missing_required_field
                         message: runKey is required.
+                zipTooLarge:
+                  value:
+                    errors:
+                      - code: invalid_zip
+                        message: Template can't be imported as the maximum allowed zip file size is 1 MB. Please re-import a new zip file.
+                mcpServerTemplate:
+                  summary: A zip with a root mcpserver.json
+                  value:
+                    errors:
+                      - code: invalid_template
+                        message: MCP server templates cannot be installed through the Integration template path. Use Upload MCP.
+                stackMissing:
+                  summary: The zip has a stack hook and the body has no _stackId
+                  value:
+                    errors:
+                      - code: stack_not_found
+                        message: The integration template has stack reference but _stackId not found in the request body.
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '403':
           $ref: '#/components/responses/403-cannot-install'
         '404':
-          description: The `runKey` does not match any uploaded zip.
+          description: |-
+            The `runKey` does not match any uploaded zip (`invalid_key`), or
+            `_stackId` matches no stack (`stack_not_found`).
           content:
             application/json:
               schema:
@@ -666,7 +753,31 @@ paths:
                   value:
                     errors:
                       - code: invalid_key
-                        message: The specified runKey was not found.
+                        message: We couldn't find any integration template zip file.
+                unknownStack:
+                  value:
+                    errors:
+                      - code: stack_not_found
+                        message: 'Failed to create the integration using the integration template provided as no stack found with _id: ''000000000000000000000000''.'
+        '422':
+          description: |-
+            The zip's entries exceed 64 MB uncompressed (`invalid_zip`), or an entry
+            is corrupted (`corrupted_file`). Nothing is installed.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                uncompressedTooLarge:
+                  value:
+                    errors:
+                      - code: invalid_zip
+                        message: Template can't be imported as the uncompressed zip contents exceed the maximum allowed size. Please re-import a smaller zip file.
+                corrupted:
+                  value:
+                    errors:
+                      - code: corrupted_file
+                        message: Looks like the uploaded zip is corrupted. Please contact Celigo support if the issue persists.
 components:
   securitySchemes:
     bearerAuth:

package/package.json

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

package/schemas.json

@@ -1,7 +1,7 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "2a2728aa",
+		"iasCommit": "4a026a0b",
 		"generatedAt": "2026-10-28"
 	},
 	"roots": {