@celigo/api-specs 0.2.201 → 0.2.203

package/dist/processor.yml

@@ -1174,8 +1174,10 @@ paths:
 
         `data` is the template's root context: `{{name}}` reads `data.name`. A template written for a
         step reads the record as `{{record.<field>}}`, so send the record under `record`
-        (`"data": {"record": {...}}`). Double braces HTML-escape the value (`&` renders as `&amp;`);
-        triple braces insert it unchanged. A `timestamp` with no time zone renders in UTC.
+        (`"data": {"record": {...}}`). Double braces HTML-escape the value (`&` renders as `&amp;`),
+        or URI-encode it when `options` carries an `http` connection and `fieldPath`
+        `http.relativeURI`; triple braces insert it unchanged. A `timestamp` with no time zone
+        renders in UTC.
 
         A null value, or a field under an object that is null, renders empty here. An HTTP import
         escapes values its own way, at run time and in the import preview: in its JSON body a
@@ -1189,6 +1191,11 @@ paths:
         entry's `helperFunctions`, but that list is not complete: `eq` and `truncateWords`, for
         example, render although it omits them, so render a doubtful helper once here before relying
         on it.
+
+        By default `lookup` doesn't resolve here: each call renders a placeholder such as
+        `{$ASYNCID$0$0$}`, Handlebars' own `{{lookup object key}}` form included, and the placeholder
+        is truthy, so `{{#if (lookup …)}}` always takes its first branch. `options` resolves an HTTP
+        import's static lookups instead (see `options`).
       requestBody:
         required: true
         content:
@@ -1214,6 +1221,63 @@ paths:
                       description: Form of the result; `text` returns the rendered string.
                       examples:
                         - text
+                options:
+                  type: object
+                  description: |-
+                    Step context for a template that calls `{{lookup '<name>' <key>}}`. Send the saved
+                    `import`, its `connection` with `type` `http`, and `fieldPath` to resolve the
+                    import's static lookups (those with a `map`) instead of rendering placeholders. A
+                    template that also calls a dynamic lookup still renders every lookup as a
+                    placeholder, as does an `import` sent without `connection` or a connection of type
+                    `rdbms`, `rest`, `ftp`, `netsuite` or `salesforce`.
+                  properties:
+                    fieldPath:
+                      type: string
+                      description: |-
+                        Field the template belongs to, such as `http.body` or `http.relativeURI`. Required
+                        whenever `connection.type` is `http`, and with that connection `http.relativeURI`
+                        URI-encodes double-brace values instead of HTML-escaping them.
+                      examples:
+                        - http.body
+                      x-celigo-ai-guidance:
+                        - |-
+                          A 422 with an empty `{}` body from this route means `options.connection.type` is
+                          `http` and `options.fieldPath` is missing: every template fails that way until
+                          `fieldPath` names the step field the template belongs to, such as `http.body`.
+                    connection:
+                      type: object
+                      additionalProperties: true
+                      description: The import's connection; `type` `http` turns static lookup resolution on.
+                      properties:
+                        type:
+                          type: string
+                          description: Connection type of the import; static lookups resolve with `http`.
+                          examples:
+                            - http
+                    import:
+                      type: object
+                      additionalProperties: true
+                      description: |-
+                        The saved import whose `http.lookups` the template calls by name. A key found in
+                        a lookup's `map` renders the mapped value, and any other key renders the lookup's
+                        `default`, or empty when it has none. Failures answer 422 with an `errors` array:
+                        `cannot_evaluate_static_lookup` for a key not in the map when the lookup sets
+                        `allowFailures: false`, `lookup_not_found` for a name the import doesn't define
+                        (Handlebars' own `{{lookup object key}}` form included), and
+                        `lookup_data_not_defined` for a key that is missing, empty or the number `0`.
+                  if:
+                    properties:
+                      connection:
+                        properties:
+                          type:
+                            const: http
+                        required:
+                          - type
+                    required:
+                      - connection
+                  then:
+                    required:
+                      - fieldPath
                 data:
                   type: object
                   additionalProperties: true
@@ -1228,6 +1292,27 @@ paths:
                   data:
                     record:
                       name: Smith & Sons
+              static_lookup:
+                summary: Resolve an HTTP import's static lookup
+                value:
+                  rules:
+                    template: '{{lookup ''statusMap'' record.status}}'
+                    resultMode: text
+                  data:
+                    record:
+                      status: '1'
+                  options:
+                    fieldPath: http.body
+                    connection:
+                      type: http
+                    import:
+                      http:
+                        lookups:
+                          - name: statusMap
+                            map:
+                              '1': active
+                              '2': inactive
+                            default: unknown
       responses:
         '200':
           description: The rendered template.
@@ -1256,6 +1341,12 @@ paths:
                     mediaType: text
                     data: Smith &amp; Sons | Smith & Sons
                     duration: 0
+                static_lookup:
+                  summary: Result of the static lookup request example
+                  value:
+                    mediaType: text
+                    data: active
+                    duration: 1
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '422':

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/dist/tool.yml

@@ -1241,8 +1241,8 @@ paths:
         '422':
           description: |-
             A step failed, or the Tool was refused before any step ran: a connection binding is
-            missing (`connection_not_overridden`) or has no `_id`, its branches don't all merge
-            back (`tool_dangling_branch`), or the input fails `input.schema` (a missing `required`
+            missing (`connection_not_overridden`), its branches don't all merge back
+            (`tool_dangling_branch`), or the input fails `input.schema` (a missing `required`
             property answers `tool_input_schema_validation_failed`). The output stage answers 422 too when the stored
             `output.schema` holds `additionalProperties: false` and the output mappings write a field
             it doesn't list ("Tool output validation failed: must NOT have additional properties").
@@ -1250,6 +1250,14 @@ paths:
             `proceedOnFailure: true`: the later steps still run, but the response carries the error,
             not the output. Either way the response includes `invocationId` when logging is active,
             so the run can be opened in the run history.
+
+            Once the Tool is found and has steps, a malformed `overrides` block is refused with
+            `invalid_override` ("Invalid override at <path>. <reason>") before any step runs:
+            `overrides` is not an object, a `connections`/`exports`/`imports`/`routers` value is not
+            an array or holds a non-object entry, a connection binding has no `_abstractId`, names
+            none of `_id`, `_borrowConcurrencyFromConnectionId`, or `requiresEndUserCredentials`, or
+            sets both `_id` and `_borrowConcurrencyFromConnectionId`. These refusals carry only `code`
+            and `message`, and no `invocationId` even with `x-log-mode: debug`.
           content:
             application/json:
               schema:
@@ -1259,7 +1267,7 @@ paths:
                 properties:
                   errors:
                     type: array
-                    description: Execution errors, each with a `code`, `message`, `source`, and epoch-millisecond `time`.
+                    description: Execution errors, each with a `code`, `message`, `source`, and epoch-millisecond `time`. An `invalid_override` refusal has only `code` and `message`.
                     items:
                       type: object
                       additionalProperties: true
@@ -1280,10 +1288,23 @@ paths:
                         message: 'Missing connection overrides. The following connection IDs must be overridden: 6ab1f5657b3d01a9084253a5.'
                     invocationId: 6ab1f5877cd5cdd66da1cc8b
                 binding_without_id:
-                  summary: A connection binding without `_id`
+                  summary: A connection binding with only `_abstractId`
+                  value:
+                    errors:
+                      - code: invalid_override
+                        message: 'Invalid override at overrides.connections[0]. Connection override must include at least one of: _id, _borrowConcurrencyFromConnectionId, requiresEndUserCredentials.'
+                binding_without_abstract_id:
+                  summary: A connection binding without `_abstractId`
+                  value:
+                    errors:
+                      - code: invalid_override
+                        message: Invalid override at overrides.connections[0]._abstractId. Missing required _abstractId.
+                overrides_not_object:
+                  summary: '`overrides` sent as an array'
                   value:
                     errors:
-                      - message: 'Invalid override at overrides.connections[0]. Connection override must include at least one of: _id, _borrowConcurrencyFromConnectionId, requiresEndUserCredentials.'
+                      - code: invalid_override
+                        message: Invalid override at overrides. Expected overrides to be an object.
   /v1/tools/{_id}/invocations:
     get:
       x-internal: false
@@ -1895,12 +1916,14 @@ paths:
         not landed yet; re-query before concluding nothing was stored.
 
         For nested Tools, set `stage` to `tool` with the nested ToolImport id to fetch the
-        composed input/output payload.
+        composed input/output payload; `groupId` is not needed for that stage and is ignored.
+        Until the nested Tool's payloads land, that entry carries only `_expOrImpId` and `stage`.
 
         When the invocation is missing or not visible under the caller's integration ACL,
         the endpoint returns `204 No Content`. `404` applies only to an unknown or inaccessible
-        Tool `_id`. A malformed `executionId` returns `422`, and a body missing any of the four
-        selector keys returns `400`. Sandbox Tools return `403`.
+        Tool `_id`. A malformed `executionId` returns `422`, and a body missing a required
+        selector key (`groupId` is required for every stage except `tool`) returns `400`.
+        Sandbox Tools return `403`.
       parameters:
         - name: _id
           in: path
@@ -1947,7 +1970,6 @@ paths:
                 value:
                   _expOrImpId: 67ee026136f4d1eeb529ad63
                   stage: tool
-                  groupId: g-12345
                   recordId: r-67890
       responses:
         '200':
@@ -2012,6 +2034,21 @@ paths:
                               content-type: application/json; charset=utf-8
                             body: '[{"_id":"6a50f177a8d85436a4a890db","name":"SO-1043"}]'
                     errors: []
+                nestedToolStage:
+                  summary: Nested Tool composed payload — the record it received and the record it returned
+                  value:
+                    logs:
+                      - log:
+                          _expOrImpId: 67ee026136f4d1eeb529ad63
+                          stage: tool
+                          input:
+                            record:
+                              orderId: SO-1043
+                          output:
+                            record:
+                              orderId: SO-1043
+                              title: Sample Slide Show
+                    errors: []
                 noMatch:
                   summary: Selector matched no stored payload
                   value:
@@ -31247,7 +31284,8 @@ components:
               description: |-
                 Provider-native ID of the storage root (e.g. a Google Drive shared-drive ID) the relative
                 path resolves against; set when pathMode is relativePath. The provider's own ID, not a Celigo ID.
-                For Google Cloud Storage it is the bucket name.
+                For Google Cloud Storage it is the bucket name, and a bucket that doesn't exist fails the
+                export preview with 422 `gcs_bucket_not_found`.
               examples:
                 - 1qU1hvFarBFMb4-twqKm1rR5o_6j9vs9g
                 - erp-exports
@@ -39498,8 +39536,15 @@ components:
       required:
         - _expOrImpId
         - stage
-        - groupId
         - recordId
+      if:
+        properties:
+          stage:
+            not:
+              const: tool
+      then:
+        required:
+          - groupId
       properties:
         _expOrImpId:
           type: string
@@ -39526,7 +39571,7 @@ components:
             - tool
         groupId:
           type: string
-          description: Group identifier of the step record.
+          description: Group identifier of the step record. Ignored when `stage` is `tool`.
           examples:
             - YYFuqOqC
         recordId:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.201",
+  "version": "0.2.203",
   "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": "d2f3a96e",
 		"generatedAt": "2026-10-28"
 	},
 	"roots": {