@celigo/api-specs 0.2.172 → 0.2.174

package/dist/import.yml

@@ -12617,7 +12617,9 @@ components:
               x-celigo-refModel: scripts
               description: |
                 Reference to the Script resource that contains the filtering logic. This must be a valid
-                ObjectId of a Script resource that exists in the system.
+                ObjectId of a Script resource in this account: any other id fails the save with 422
+                ("Only a script owned by the user or a script shared by the Integration App can be used
+                at filter.script._scriptId.").
 
                 The referenced script must contain the function specified in the `function` field
                 and must be written to handle filtering specifically. The script receives
@@ -12676,7 +12678,11 @@ components:
           type: string
           format: objectId
           x-celigo-refModel: scripts
-          description: Script containing the hook function named in `function`. Send this or `_stackId`, not both.
+          description: |-
+            Script containing the hook function named in `function`. Send this or `_stackId`, not both.
+            Must be a script in this account: any other id fails the save with 422, naming the hook,
+            such as "Only a script owned by the user or a script shared by the Integration App can
+            be used at hooks.preMap._scriptId." on an import's `preMap`.
         _stackId:
           type: string
           format: objectId
@@ -15249,7 +15255,9 @@ components:
                 Reference to a predefined script resource containing the transformation logic.
 
                 The referenced script should contain the function specified in the
-                'function' property.
+                'function' property. It must be a script in this account: any other id fails the save
+                with 422 ("Only a script owned by the user or a script shared by the Integration App can
+                be used at transform.script._scriptId.").
               format: objectid
               x-celigo-refModel: scripts
               examples:
@@ -16872,6 +16880,15 @@ components:
                 plus whatever this step's response mapping merges back. A value later steps need
                 belongs in the source export's `preSavePage`, in this step's `postResponseMap` hook on
                 the flow, or in the later import's own `preMap`.
+
+                The function returns one element per record in `options.data`, in order:
+                `{ data: <record> }` sends the record and `{ errors: [{ code, message }] }` fails it.
+                An element without `data` — `{}`, or the record itself returned unwrapped — skips that
+                record with no error: nothing is sent and the record is reported `ignored: true` at
+                stage `preMapHook`. A return with more or fewer elements fails every record on the page
+                with `invalid_extension_response` ("Extension result doesn't contain the same number
+                of elements as the request object. Expected 2, got 1. Extension returned statusCode
+                200"), source `pre_map_hook`.
               x-celigo-ai-guidance:
                 - |-
                   Pre-map JavaScript hook — runs once per page BEFORE the
@@ -16883,7 +16900,18 @@ components:
                   renames — mappings handle those.
 
                   Runtime contract: ``options.data[]`` (the page of upstream
-                  records) → array of the same length.
+                  records) → array of the same length, each element
+                  ``{data: record}`` or ``{errors: [...]}``.  A bare record in
+                  the returned array is skipped without an error, so
+                  ``options.data.map(r => { r.total = t; return r })`` sends
+                  nothing.
+                - |-
+                  Verified live 2026-10-22 by invoking an HTTP import with a
+                  Mapper 2.0 number mapping: one ``{data: record}`` per record
+                  sent both records; the bare records sent nothing and both
+                  came back ``ignored: true``, ``stage: preMapHook``, with no
+                  error; one element for two records failed both with 422
+                  ``invalid_extension_response``.
               allOf:
                 - $ref: '#/components/schemas/Hook'
             postMap:
@@ -17745,6 +17773,18 @@ components:
           example:
             5f7c579b6411271af4e7cefa: 64a1234567890abcdef12345
             5f7c579b6411271af4e7cefb: 64a1234567890abcdef12346
+        _stackId:
+          type: string
+          format: objectId
+          x-celigo-refModel: stacks
+          description: |-
+            Stack that every stack reference in the cloned resources (hooks and wrapper
+            connections running on a stack) points at. Required when the clone preview reports
+            `stackRequired: true`: without it the clone fails with 400 `stack_not_found`. The
+            stack must belong to the target environment or be shared with it (404
+            `stack_not_found` for an unknown id, 400 `invalid_stack` otherwise).
+          examples:
+            - 5f8d43a1b9e5a80011a35f2c
       additionalProperties: true
     CloneResponse:
       description: Response body for a clone operation. Some clone endpoints return the cloned resource, while others may return a list of related created resources.
@@ -17795,12 +17835,18 @@ components:
                 additionalProperties: true
         stackRequired:
           type: boolean
-          description: Whether the clone requires a stack (connector-level) environment to proceed.
+          description: |-
+            `true` when the resource or one of its dependencies references a stack (a hook or
+            wrapper connection that runs on a stack). Send `_stackId` in the clone request: without
+            it the clone fails with 400 `stack_not_found`.
         _stackId:
           type:
             - string
             - 'null'
-          description: The stack id associated with the resource, or null if no stack is involved.
+          description: |-
+            The first stack the resource or a dependency references, or null. Pass it, or another
+            stack in the target environment, as `_stackId` in the clone request; the clone points
+            every stack reference at that one stack.
           examples:
             - 5f8d43a1b9e5a80011a35f2c
     ImportRecordResult:

package/dist/integration.yml

@@ -4609,6 +4609,18 @@ components:
           example:
             5f7c579b6411271af4e7cefa: 64a1234567890abcdef12345
             5f7c579b6411271af4e7cefb: 64a1234567890abcdef12346
+        _stackId:
+          type: string
+          format: objectId
+          x-celigo-refModel: stacks
+          description: |-
+            Stack that every stack reference in the cloned resources (hooks and wrapper
+            connections running on a stack) points at. Required when the clone preview reports
+            `stackRequired: true`: without it the clone fails with 400 `stack_not_found`. The
+            stack must belong to the target environment or be shared with it (404
+            `stack_not_found` for an unknown id, 400 `invalid_stack` otherwise).
+          examples:
+            - 5f8d43a1b9e5a80011a35f2c
       additionalProperties: true
     CloneResponse:
       description: Response body for a clone operation. Some clone endpoints return the cloned resource, while others may return a list of related created resources.
@@ -4669,12 +4681,18 @@ components:
                 additionalProperties: true
         stackRequired:
           type: boolean
-          description: Whether the clone requires a stack (connector-level) environment to proceed.
+          description: |-
+            `true` when the resource or one of its dependencies references a stack (a hook or
+            wrapper connection that runs on a stack). Send `_stackId` in the clone request: without
+            it the clone fails with 400 `stack_not_found`.
         _stackId:
           type:
             - string
             - 'null'
-          description: The stack id associated with the resource, or null if no stack is involved.
+          description: |-
+            The first stack the resource or a dependency references, or null. Pass it, or another
+            stack in the target environment, as `_stackId` in the clone request; the clone points
+            every stack reference at that one stack.
           examples:
             - 5f8d43a1b9e5a80011a35f2c
     Revision:

package/dist/lookupcache.yml

@@ -452,12 +452,14 @@ paths:
         strings, or objects — arrays at the top level are rejected (wrap them in an
         object). One invalid entry fails the entire batch and nothing in it is written:
         a bad value returns `400 invalid_value`, an empty, missing, or over-length
-        key returns `400 cache_dynamodb_invalid_key`, and a key that appears twice in
-        the batch returns 400 "Duplicate keys found in the request".
+        key, or one holding a tab, newline, carriage return or NUL, returns
+        `400 cache_dynamodb_invalid_key`, and a key that appears twice in the batch
+        returns 400 "Duplicate keys found in the request".
 
-        The service rejects batches larger than ~1000 entries or ~5 MB of JSON.
-        Callers uploading more than that should split their payload; the Celigo CLI
-        auto-batches at 1000 entries / 5 MB and concatenates the per-key results.
+        One request takes at most 1000 entries, each entry at most 64 KB, and at most 5 MB of
+        JSON in all (413, "request entity too large!"). Callers uploading more than that should
+        split their payload; the Celigo CLI auto-batches at 1000 entries / 5 MB and concatenates
+        the per-key results.
         Each cache is capped at 50 MB and the per-environment aggregate is 1 GB.
       parameters:
         - name: _id
@@ -511,6 +513,17 @@ paths:
           $ref: '#/components/responses/401-unauthorized'
         '404':
           $ref: '#/components/responses/404-not-found'
+        '413':
+          description: The request body is over 5 MB of JSON. Split the batch.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                too_large:
+                  value:
+                    errors:
+                      - message: request entity too large!
     delete:
       x-internal: false
       operationId: deleteLookupCacheDataKeys
@@ -1009,12 +1022,18 @@ components:
                 additionalProperties: true
         stackRequired:
           type: boolean
-          description: Whether the clone requires a stack (connector-level) environment to proceed.
+          description: |-
+            `true` when the resource or one of its dependencies references a stack (a hook or
+            wrapper connection that runs on a stack). Send `_stackId` in the clone request: without
+            it the clone fails with 400 `stack_not_found`.
         _stackId:
           type:
             - string
             - 'null'
-          description: The stack id associated with the resource, or null if no stack is involved.
+          description: |-
+            The first stack the resource or a dependency references, or null. Pass it, or another
+            stack in the target environment, as `_stackId` in the clone request; the clone points
+            every stack reference at that one stack.
           examples:
             - 5f8d43a1b9e5a80011a35f2c
     LookupCacheDataEntry:
@@ -1034,7 +1053,8 @@ components:
           description: |-
             Lookup key. Treated as an opaque string by the cache — case-sensitive, no
             normalization. The same cache can hold multiple entries that differ only in
-            case (e.g. `CA` and `ca`).
+            case (e.g. `CA` and `ca`). An upsert also refuses a key that holds a tab, a newline,
+            a carriage return or a NUL character, with the same `cache_dynamodb_invalid_key`.
           examples:
             - CA
             - ext-customer-12345
@@ -1071,9 +1091,9 @@ components:
         Request body for upserting key-value entries into a lookup cache. `data` must be
         a non-empty array. Keys already present are overwritten; new keys are created.
 
-        The service rejects batches larger than ~1000 entries or ~5 MB — callers inserting
-        more than that should split into multiple requests (the Celigo CLI auto-batches
-        at 1000 entries / 5 MB).
+        One request takes at most 1000 entries, each entry at most 64 KB, and at most 5 MB of
+        JSON in all (413) — callers inserting more than that should split into multiple
+        requests (the Celigo CLI auto-batches at 1000 entries / 5 MB).
       properties:
         data:
           type: array

package/dist/marketplace.yml

@@ -154,9 +154,17 @@ paths:
         `type` tells you which install route to use afterwards:
         `POST /v1/integrations/template/{_id}` for `integration`,
         `POST /v1/mcpservers/template/{_templateId}` for `mcpserver`.
-        `stackRequired` is `true` when the template includes NetSuite-distributed
-        resources that need a dedicated stack — the installer prompts for one
-        before the install proceeds.
+        `stackRequired` is `true` when the template has hooks or wrapper
+        connections that run on a stack: the marketplace installer prompts for
+        one; `POST /v1/integrations/template/{_id}`, for a template it accepts
+        (no `template_zip` install step), needs it as `_stackId`; and an
+        MCP-server template's install adds a stack step to the integration it
+        creates.
+
+        Previewing an MCP-server template needs the same install permission as
+        installing it (403 for a monitor or integration-level user whose access
+        doesn't allow creating integrations); an integration template's preview
+        needs none.
 
         The ID must belong to a Template, not a Connector (Integration App).
         Connector IDs from `/v1/published` return 404 here -- pull template
@@ -234,6 +242,14 @@ paths:
                             concurrencyLevel: 1
         '401':
           $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: |-
+            An MCP-server template previewed by a user who may not install templates (a monitor
+            or integration-level user whose access doesn't allow creating integrations).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
         '404':
           description: |-
             No template matched the id. Most commonly: the id belongs to a
@@ -887,10 +903,15 @@ components:
         stackRequired:
           type: boolean
           description: |-
-            `true` when the template includes NetSuite-distributed resources
-            that need a dedicated stack — the installer prompts for one before
-            the install proceeds. `false` for Shopify / HTTP / file-only
-            templates.
+            `true` when the template has an export or import hook, or a wrapper
+            connection, that runs on a stack (a function with no script). The
+            marketplace installer asks for the stack. Through the API, an
+            integration template that `POST /v1/integrations/template/{_id}`
+            accepts (no `template_zip` install step) needs `_stackId` in the body,
+            or the install fails with 400 `stack_not_found`; so does a zip
+            installed with `POST /v1/integrations/template`. An MCP-server
+            template's install takes no body: the integration it creates for a
+            tool-bearing template gets a stack install step instead.
   responses:
     401-unauthorized:
       description: |-

package/dist/mcp-oauth-provider.yml

@@ -329,15 +329,22 @@ components:
             - https://mcp.example.com
         scopes:
           type: array
-          description: Required OAuth scopes. Incoming tokens must carry every listed scope.
+          description: |-
+            The MCP operations OAuth callers may use on every server that references this
+            provider, and the scopes those servers advertise as `scopes_supported`. Calling a
+            tool (`tools/call`) needs `mcp:write`; listing tools, prompts and resources, and
+            reading prompts and resources, accept either scope. Listing only `mcp:read` refuses
+            every tool call with 403 `insufficient_scope`, whatever the token carries; an empty
+            list allows both. Each request also needs its scope in the caller's token, so a
+            token issued with only `mcp:read` can list and read but can't call a tool.
           items:
             type: string
             enum:
               - mcp:read
               - mcp:write
             x-enumDescriptions:
-              mcp:read: Grants read-only access to MCP server resources.
-              mcp:write: Grants write access to MCP server resources.
+              mcp:read: Lists tools, prompts and resources and reads prompts and resources; can't call a tool.
+              mcp:write: Calls tools (`tools/call`); also lists and reads.
           examples:
             - - mcp:read
               - mcp:write

package/dist/mcp-server.yml

@@ -3082,7 +3082,15 @@ components:
         scopes:
           type: array
           description: |-
-            Required OAuth scopes. Incoming tokens must carry every listed scope.
+            For an external provider or inline OAuth: the MCP operations OAuth callers may use on
+            this server, and the scopes its OAuth metadata advertises as `scopes_supported`.
+            Calling a tool (`tools/call`) needs `mcp:write`; listing tools, prompts and resources,
+            and reading prompts and resources, accept either scope. A server that lists only
+            `mcp:read` refuses every tool call with 403 `insufficient_scope`, whatever the token
+            carries; an empty list allows both. Under Celigo OAuth (`useCeligoOauth`) this list
+            isn't used: the server allows both scopes. Either way each request also needs its
+            scope in the caller's token, so a token issued with only `mcp:read` can list and read
+            but can't call a tool. API-token callers aren't scope-checked.
 
             Rejected values return `enum` / `invalid_field_value` on
             `oauth.scopes.<index>`.
@@ -3092,8 +3100,8 @@ components:
               - mcp:read
               - mcp:write
             x-enumDescriptions:
-              mcp:read: Grants read-only access to MCP server resources.
-              mcp:write: Grants write access to MCP server resources.
+              mcp:read: Lists tools, prompts and resources and reads prompts and resources; can't call a tool.
+              mcp:write: Calls tools (`tools/call`); also lists and reads.
           examples:
             - - mcp:read
               - mcp:write
@@ -4190,11 +4198,13 @@ components:
                 after which the flag switches itself off), and concurrency climbs back toward
                 `targetConcurrencyLevel`. While true, `targetConcurrencyLevel` is the throughput lever: a
                 `concurrencyLevel` sent in a PUT is ignored, and one sent in a PATCH is stored but the
-                recovery machinery moves it back toward the target.
+                recovery machinery moves it back toward the target. Recovery never runs on `ftp`
+                connections: FTP errors aren't treated as rate limits.
               x-celigo-ai-guidance:
                 - To change throughput while this is true, write `targetConcurrencyLevel`; a `concurrencyLevel` sent in a PUT returns 200 and changes nothing.
                 - Turning it on copies `concurrencyLevel` into `targetConcurrencyLevel`; turning it off unsets the target and leaves `concurrencyLevel` at its current value, which may be below the old target if a recovery was in progress. A `targetConcurrencyLevel` written while this is false is unset by the save.
                 - These four settings (`concurrencyLevel`, `targetConcurrencyLevel`, `_borrowConcurrencyFromConnectionId`, this flag) accept a credential-free `PATCH /v1/connections/{_id}`. A PUT replaces the whole document, so send each secret back as its masked `******` value (that keeps it) or as a new value, and never drop one to keep it — an omitted password or `http.encrypted` is cleared, and a static token left out (with no `refreshMethod`) fails the PUT with 422.
+                - On an `ftp` connection recovery never runs, and transfer threads are `ftp.multiThreadCount`; while this is true a create sets `ftp.concurrencyLevel` to `ftp.targetConcurrencyLevel`, or to 1 without one.
             enableMicroBatchForOneToMany:
               type: boolean
               default: true
@@ -4812,6 +4822,10 @@ components:
             FTP servers often have low connection limits — keep this value conservative.
             Send no more than the account's licensed maximum, the license's `concurrency` (25 standard,
             50 with an Environments license).
+            While `autoRecoverRateLimitErrors` is true, which a create gets unless it sends `false`, a create
+            ignores the value sent here and sets this field to `targetConcurrencyLevel`, or to 1 when no
+            target is sent. To start higher, send `targetConcurrencyLevel` too, or create with
+            `autoRecoverRateLimitErrors: false`.
             Unlike the rest of the `ftp` object, a `PUT` that omits this field keeps the stored value instead of clearing it.
           minimum: 1
           maximum: 50
@@ -4821,8 +4835,9 @@ components:
         targetConcurrencyLevel:
           type: integer
           description: |
-            Target concurrency level for auto-scaling. The system adjusts concurrency
-            between 1 and this value based on server response feedback.
+            While `autoRecoverRateLimitErrors` is true, a create sets `concurrencyLevel` to this value, and a
+            create that omits it gets 1 for both. Auto-recovery never runs on FTP connections (FTP errors
+            aren't treated as rate limits), so nothing climbs back to it.
             Kept on a `PUT` that omits it, like `concurrencyLevel`; unset by the save while
             `autoRecoverRateLimitErrors` is false.
           minimum: 1
@@ -4853,9 +4868,9 @@ components:
           type: integer
           readOnly: true
           description: |-
-            Server-maintained mirror of `multiThreadCount` used by concurrency
-            auto-scaling. Present only when rate-limit auto-recovery applies;
-            recomputed on save.
+            Server-maintained mirror of `multiThreadCount`, present while
+            `autoRecoverRateLimitErrors` is true and `targetConcurrencyLevel` is
+            set; recomputed on save.
       if:
         properties:
           type:

package/dist/stack.yml

@@ -106,7 +106,7 @@ paths:
         after creation via `GET /v1/stacks/{_id}/systemToken`.
       x-celigo-ai-guidance:
         - |-
-          - For `type=server`, provide `server.hostURI` (and optional `server.ipRanges`).
+          - For `type=server`, provide `server.hostURI`. Don't send `server.ipRanges`: it's deprecated and nothing enforces it.
           - For `type=lambda`, provide AWS credentials and function details under `lambda`.
       operationId: createStack
       tags:

package/dist/template.yml

@@ -22,8 +22,13 @@ tags:
 
       The template lifecycle is: create → upload zip (via `GET /v1/s3SignedURL`) → publish.
 
-      All endpoints require a **Partner account** — non-partner callers
-      receive 403 `access_restricted`.
+      Creating, updating, uploading and publishing templates requires a
+      **Partner account** — non-partner callers receive 403
+      `access_restricted`. Installing a template (`/v1/integrations/template`
+      routes) needs install permission instead: the account owner,
+      administrators and manage users have it, and monitor or
+      integration-level users only when their access allows creating
+      integrations.
 
       ## Template schema
 
@@ -377,6 +382,18 @@ paths:
                   example:
                     61f92026dd053843b5d72350: 64a1234567890abcdef12345
                     61f92026dd053843b5d72351: 64a1234567890abcdef12346
+                _stackId:
+                  type: string
+                  format: objectId
+                  x-celigo-refModel: stacks
+                  description: |-
+                    Stack for the template's hooks and wrapper connections that run on a stack.
+                    Required when the template preview reports `stackRequired: true`: without
+                    it the install fails with 400 `stack_not_found`. The stack must belong to
+                    the environment or be shared with it (404 `stack_not_found` for an unknown
+                    id, 400 `invalid_stack` otherwise).
+                  examples:
+                    - 5f8d43a1b9e5a80011a35f2c
               required:
                 - connectionMap
             examples:
@@ -419,9 +436,12 @@ paths:
                       _id: 6405b9d83496e05ff253d594
         '400':
           description: |-
-            Missing or empty `connectionMap`, or the template is an MCP server
+            Missing or empty `connectionMap`; the template is an MCP server
             template that must be installed through
-            `POST /v1/mcpservers/template/{_templateId}`.
+            `POST /v1/mcpservers/template/{_templateId}`; the template needs a
+            stack and the body has no `_stackId` (`stack_not_found`); or the
+            `_stackId` names a stack that neither belongs to this environment nor
+            is shared with it (`invalid_stack`).
           content:
             application/json:
               schema:
@@ -438,12 +458,18 @@ paths:
                     errors:
                       - code: invalid_template
                         message: MCP server templates cannot be installed through the Integration template path.
+                missingStack:
+                  summary: The preview reported stackRequired and no _stackId was sent
+                  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-forbidden'
+          $ref: '#/components/responses/403-cannot-install'
         '404':
-          description: Template not found.
+          description: Template not found, or no stack has the `_stackId` sent (`stack_not_found`).
           content:
             application/json:
               schema:
@@ -539,7 +565,7 @@ paths:
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '403':
-          $ref: '#/components/responses/403-forbidden'
+          $ref: '#/components/responses/403-cannot-install'
         '404':
           description: The `runKey` does not match any uploaded zip.
           content:
@@ -583,6 +609,16 @@ paths:
                     the template zip file.
                   examples:
                     - abc123def456
+                _stackId:
+                  type: string
+                  format: objectId
+                  x-celigo-refModel: stacks
+                  description: |-
+                    Stack for the template's hooks and wrapper connections that run on a stack.
+                    Required when the preview reports `stackRequired: true` (400
+                    `stack_not_found` without it).
+                  examples:
+                    - 5f8d43a1b9e5a80011a35f2c
               required:
                 - runKey
             examples:
@@ -618,7 +654,7 @@ paths:
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '403':
-          $ref: '#/components/responses/403-forbidden'
+          $ref: '#/components/responses/403-cannot-install'
         '404':
           description: The `runKey` does not match any uploaded zip.
           content:
@@ -978,5 +1014,27 @@ components:
                 errors:
                   - code: invalid_request
                     message: The request body failed validation.
+    403-cannot-install:
+      description: |-
+        The caller may not install templates. The account owner, administrators and manage users
+        can; a monitor user or a user with access to specific integrations only can install a
+        template only when their access allows creating integrations
+        (`allowIntegrationWorkspaceCreation`).
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            cannotInstall:
+              value:
+                errors:
+                  - code: access_restricted
+                    message: Users with monitor or tile level manage permissions cannot install templates. Ask an account owner or administrator to increase your permissions, or contact another user with at least account level manage permissions to install the template.
+            otherRole:
+              summary: Any other role without install permission
+              value:
+                errors:
+                  - code: access_restricted
+                    message: The role which you are associated with doesn't have the required permissions to perform the action.
 x-enable-proxy: true
 x-internal: false