@celigo/api-specs 0.2.39 → 0.2.41

package/dist/connection.yml

@@ -156,6 +156,11 @@ paths:
         `404`, and `422` responses); failures during the post-save registration itself do not
         roll back the new connection and are reported in `__failedIntegrationRegistrations` on
         the `201` response.
+
+        Creates `standard` connections only: a body with `connectionRole: mcpChild` is rejected,
+        because MCP end-user child connections are written solely by the end-user setup page. To
+        make a connection the parent that an MCP server collects end-user credentials for, list the
+        per-user fields in `endUserProvidedFields`.
       operationId: createConnection
       tags:
         - Connections
@@ -193,6 +198,34 @@ paths:
                       type: custom
                   __integrationIds:
                     - 6a55be91d16ee8270022893e
+              httpMcpParent:
+                summary: HTTP connection that MCP end users supply their own API key for
+                value:
+                  name: Support Desk API
+                  type: http
+                  endUserProvidedFields:
+                    - http.encrypted.apiKey
+                  http:
+                    mediaType: json
+                    baseURI: https://api.example.com
+                    auth:
+                      type: custom
+                    headers:
+                      - name: X-API-Key
+                        value: '{{{connection.http.encrypted.apiKey}}}'
+                    encrypted:
+                      apiKey: <owner-api-key>
+              httpAwsIam:
+                summary: HTTP connection signing requests with an AWS IAM role (iClient)
+                value:
+                  name: SQS - orders account
+                  type: http
+                  http:
+                    mediaType: json
+                    baseURI: https://sqs.us-east-1.amazonaws.com
+                    _iClientId: 6ab1f51c7b3d01a908423f0a
+                    auth:
+                      type: awsiam
               netsuiteTokenAuto:
                 summary: NetSuite connection (automatic token-based auth — recommended)
                 value:
@@ -453,6 +486,7 @@ paths:
                     lastModified: '2026-06-08T00:45:50.951Z'
                     type: http
                     name: My HTTP API
+                    connectionRole: standard
                     enableMicroBatchForOneToMany: true
                     enableCsvObjectParsing: true
                     autoRecoverRateLimitErrors: true
@@ -559,7 +593,9 @@ paths:
           description: |-
             Unprocessable entity. The request was well-formed but was unable to be followed
             due to semantic errors — for example, a missing config object for the connection
-            `type`, or an invalid `__integrationIds` value. The connection is not created.
+            `type`, an invalid `__integrationIds` value, a decimal concurrency value, an
+            `http._iClientId` that does not satisfy the auth type's iClient rules, or an
+            `mcpChild` role. The connection is not created.
           content:
             application/json:
               schema:
@@ -589,16 +625,67 @@ paths:
                     errors:
                       - code: invalid_request
                         message: __integrationIds must not contain duplicate integration IDs.
+                mcpChildNotAllowed:
+                  summary: connectionRole is mcpChild
+                  value:
+                    errors:
+                      - code: mcp_child_generic_route_not_allowed
+                        message: An mcpChild connection cannot be created, updated or deleted through the connections API, including the recurse and recycle bin routes.
+                endUserProvidedFieldParentOwned:
+                  summary: endUserProvidedFields names a field the account owns
+                  value:
+                    errors:
+                      - field: endUserProvidedFields
+                        code: mcp_end_user_provided_field_not_allowed
+                        message: http._iClientId is managed by the account owner and cannot be requested from an end user.
+                concurrencyNotInteger:
+                  summary: Decimal concurrency value
+                  value:
+                    errors:
+                      - field: http.concurrencyLevel
+                        code: invalid_field_value
+                        message: The field "http.concurrencyLevel" must be a whole number (no decimals) between 1 and 50.
+                awsIamIClientMissing:
+                  summary: auth.type awsiam without http._iClientId
+                  value:
+                    errors:
+                      - field: http._iClientId
+                        code: missing_required_field
+                        message: 'Expected field: _iClientId to be present.'
+                awsIamIClientWrongProvider:
+                  summary: awsiam connection referencing a non-awsIam iClient
+                  value:
+                    errors:
+                      - field: http._iClientId
+                        code: invalid_field
+                        message: IClient provider must be awsIam for HTTP IAM Role authentication.
+                awsIamRoleArnPrefix:
+                  summary: awsIam iClient whose role name lacks the celigo-http-adaptor- prefix
+                  value:
+                    errors:
+                      - field: http._iClientId
+                        code: invalid_field_value
+                        message: HTTP IAM Role authentication requires awsIam.roleArn to reference a role name starting with celigo-http-adaptor-.
+                iClientOtherAccount:
+                  summary: iClient owned by another account
+                  value:
+                    errors:
+                      - field: http._iClientId
+                        code: invalid_ref
+                        message: The referenced IClient must belong to the same user.
+                adlsIClientWrongProvider:
+                  summary: Azure Data Lake Storage Gen2 connection referencing a non-service-principal iClient
+                  value:
+                    errors:
+                      - field: http._iClientId
+                        code: invalid_field
+                        message: IClient provider must be azureserviceprincipal for Azure Data Lake Storage Gen2 connections.
       x-celigo-ai-guidance:
         - |-
-          Performs a comprehensive test of the connection including authentication, permissions, 
-          and basic data operations to verify the connection is fully operational.
-
-          This is more thorough than a ping operation and may include:
-          - Sample data retrieval
-          - Permission verification for read/write operations
-          - Schema or metadata validation
-          - Rate limiting and quota checks
+          Send exactly one adaptor config object, the one named by `type`. Credentials are accepted
+          in clear on create and come back masked as "******"; the response also carries the
+          server-populated fields (`connectionRole: standard`, `concurrencyLevel`,
+          `targetConcurrencyLevel`, `microServices`).
   /v1/connections/{_id}:
     get:
       x-internal: false
@@ -649,6 +736,31 @@ paths:
                       disableHttp: false
                       disableNetSuiteDistributed: false
                       disableRdbms: false
+                httpMcpParent:
+                  summary: HTTP connection that MCP end users supply their own API key for
+                  value:
+                    _id: 6ab1f41f4db5688fd8ca71fb
+                    createdAt: '2026-09-21T20:21:03.924Z'
+                    lastModified: '2026-09-21T20:22:22.140Z'
+                    type: http
+                    name: Support Desk API
+                    connectionRole: standard
+                    endUserProvidedFields:
+                      - http.encrypted.apiKey
+                    enableMicroBatchForOneToMany: true
+                    enableCsvObjectParsing: true
+                    autoRecoverRateLimitErrors: true
+                    http:
+                      formType: http
+                      mediaType: json
+                      baseURI: https://api.example.com
+                      concurrencyLevel: 25
+                      targetConcurrencyLevel: 25
+                      encrypted: '******'
+                      isRest: false
+                      useNewAuthFailSchema: true
+                      auth:
+                        type: custom
                 mcp:
                   summary: MCP connection
                   value:
@@ -682,7 +794,15 @@ paths:
       summary: Update a connection
       description: |
         Updates an existing connection configuration. This is a full-replace operation —
-        send the complete connection document, not just the fields you want to change.
+        send the complete connection document, not just the fields you want to change; a field
+        omitted from the body is cleared, including credentials (re-send them, or the masked
+        `"******"` value clears them too).
+
+        Three settings are the exception and survive an omission: `endUserProvidedFields`
+        (send `null` to clear it — `[]` is treated like an omission), and on `ftp` connections
+        `ftp.concurrencyLevel` and `ftp.targetConcurrencyLevel` (the latter is unset whenever
+        `autoRecoverRateLimitErrors` is false). `connectionRole` is read-only here: a body carrying
+        `mcpChild` is rejected.
       operationId: updateConnection
       tags:
         - Connections
@@ -792,11 +912,47 @@ paths:
         '404':
           $ref: '#/components/responses/404-not-found'
         '422':
-          $ref: '#/components/responses/422-unprocessable-entity'
+          description: |-
+            Unprocessable entity. The body was well-formed but fails the connection's validation
+            rules — the same rules as on create (missing config object, decimal concurrency,
+            iClient rules, parent-owned `endUserProvidedFields` path, `mcpChild` role).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                default:
+                  summary: Semantic validation failure
+                  value:
+                    errors:
+                      - code: unprocessable_entity
+                        message: The request could not be processed due to a semantic error.
+                mcpChildNotAllowed:
+                  summary: connectionRole is mcpChild
+                  value:
+                    errors:
+                      - code: mcp_child_generic_route_not_allowed
+                        message: An mcpChild connection cannot be created, updated or deleted through the connections API, including the recurse and recycle bin routes.
+                endUserProvidedFieldParentOwned:
+                  summary: endUserProvidedFields names a field the account owns
+                  value:
+                    errors:
+                      - field: endUserProvidedFields
+                        code: mcp_end_user_provided_field_not_allowed
+                        message: type is managed by the account owner and cannot be requested from an end user.
+                concurrencyNotInteger:
+                  summary: Decimal concurrency value
+                  value:
+                    errors:
+                      - field: ftp.multiThreadCount
+                        code: invalid_field_value
+                        message: The field "ftp.multiThreadCount" must be a whole number (no decimals) between 1 and 50.
       x-celigo-ai-guidance:
         - |-
-          Updates an existing connection configuration. This operation supports partial updates
-          where only the provided fields will be modified.
+          PUT replaces the document: GET it first, change what you need, and send the whole body
+          back with the real credential values (masked "******" values clear the stored secret).
+          To change only name, debug window, or concurrency settings without touching credentials,
+          use PATCH instead.
     patch:
       x-internal: false
       summary: Patch a connection
@@ -817,16 +973,19 @@ paths:
         | `/<adaptor>/targetConcurrencyLevel` | Ceiling auto-recovery climbs back to. Persists only while `autoRecoverRateLimitErrors` is true; while false the save unsets it |
         | `/_borrowConcurrencyFromConnectionId` | Share another connection's concurrency budget. `remove` clears it |
         | `/autoRecoverRateLimitErrors` | Rate-limit auto-recovery toggle. Turning it on copies the current level into the target; turning it off unsets the target and leaves the level at its current value |
+        | `/endUserProvidedFields` | Dot-paths MCP end users must supply on their own child copy of this connection. `replace` with `[]` or `remove` clears the list, and `add` on `/endUserProvidedFields/-` appends one path; a path the account owns (`type`, `_agentId`, `wrapper._stackId`, any `<adaptor>._iClientId`) is rejected |
 
         `replace` and `add` both set the value (a currently unset field is fine);
         `remove` unsets it. A `null` value is rejected. Any other path — including
-        `/netsuite/concurrencyLevelRESTlet`, `/netsuite/concurrencyLevelWebServices`
-        and `rateLimit` fields — fails with `<path> is not a whitelisted property`.
-        Concurrency values must be whole numbers; out-of-range integers are clamped
-        into the account's licensed range rather than rejected. A whitelisted path
-        under an adaptor block the connection does not use is accepted but never
-        read. The borrowed-from connection must exist in the account, may not itself
-        borrow, and a connection that others borrow from cannot start borrowing.
+        `/connectionRole`, `/netsuite/concurrencyLevelRESTlet`,
+        `/netsuite/concurrencyLevelWebServices` and `rateLimit` fields — fails with
+        `<path> is not a whitelisted property`.
+        Concurrency values must be whole numbers (a decimal fails with 422
+        `invalid_field_value`); out-of-range integers are clamped into the account's
+        licensed range rather than rejected. A whitelisted path under an adaptor
+        block the connection does not use is accepted but never read. The
+        borrowed-from connection must exist in the account, may not itself borrow,
+        and a connection that others borrow from cannot start borrowing.
         Settings-only changes are recorded in the connection's audit log.
       operationId: patchConnection
       tags:
@@ -883,6 +1042,13 @@ paths:
                 value:
                   - op: remove
                     path: /_borrowConcurrencyFromConnectionId
+              set_end_user_provided_fields:
+                summary: Make MCP end users supply their own API key on this connection
+                value:
+                  - op: replace
+                    path: /endUserProvidedFields
+                    value:
+                      - http.encrypted.apiKey
       responses:
         '204':
           description: Connection patched successfully
@@ -891,7 +1057,33 @@ paths:
         '404':
           $ref: '#/components/responses/404-not-found'
         '422':
-          $ref: '#/components/responses/422-unprocessable-entity'
+          description: |-
+            Patch rejected — a path outside the whitelist, a `null` value, a decimal concurrency
+            value, or an `endUserProvidedFields` entry the account owns.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                nonWhitelisted:
+                  summary: Path is not patchable
+                  value:
+                    errors:
+                      - message: /connectionRole is not a whitelisted property
+                concurrencyNotInteger:
+                  summary: Decimal concurrency value
+                  value:
+                    errors:
+                      - field: http.targetConcurrencyLevel
+                        code: invalid_field_value
+                        message: The field "http.targetConcurrencyLevel" must be a whole number (no decimals) between 1 and 50.
+                endUserProvidedFieldParentOwned:
+                  summary: endUserProvidedFields names a field the account owns
+                  value:
+                    errors:
+                      - field: endUserProvidedFields
+                        code: mcp_end_user_provided_field_not_allowed
+                        message: _agentId is managed by the account owner and cannot be requested from an end user.
     delete:
       x-internal: false
       summary: Delete a connection
@@ -924,8 +1116,9 @@ paths:
           $ref: '#/components/responses/422-dependency-conflict'
       x-celigo-ai-guidance:
         - |-
-          Deletes a connection permanently. This operation cannot be undone.
-          The connection must not be in use by any active flows or integrations.
+          Soft-deletes the connection into the recycle bin (restorable for 30 days). Check
+          `GET /v1/connections/{_id}/dependencies` first — a connection still referenced by flows,
+          exports, or imports is rejected with 422.
   /v1/connections/{_id}/ping:
     get:
       x-internal: false
@@ -1410,6 +1603,96 @@ paths:
           $ref: '#/components/responses/401-unauthorized'
         '404':
           $ref: '#/components/responses/404-not-found'
+  /v1/connections/{_id}/debug/{typeId}:
+    get:
+      x-internal: false
+      operationId: getConnectionDebugLogsForResource
+      tags:
+        - Connections
+      summary: Fetch a connection's debug logs for one export or import
+      description: |-
+        Same buffered debug log stream as `GET /v1/connections/{_id}/debug`, narrowed to the
+        request/response pairs recorded for a single export or import (`typeId`) that uses the
+        connection. Use it instead of filtering the shared stream client-side when one flow step
+        is under investigation. Capture is still gated by the connection's `debugDate`, so the
+        stream is empty until debug logging is enabled.
+
+        `typeId` must be the id of an export or import in the account; an id that resolves to
+        neither answers 404, and a value that is not an ObjectId answers 400.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: The connection id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: connections
+        - name: typeId
+          in: path
+          required: true
+          description: Id of the export or import whose traffic through the connection to return.
+          schema:
+            type: string
+            format: objectId
+      responses:
+        '200':
+          description: Debug log stream (plain text) for the given export or import.
+          content:
+            text/plain:
+              schema:
+                type: string
+                description: |-
+                  Newline-separated debug log entries in the same format as
+                  `GET /v1/connections/{_id}/debug`: a header line
+                  (`timestamp traceKey resourceType resourceId`) followed by a JSON payload line,
+                  entries separated by blank lines. Every entry's `resourceId` equals `typeId`.
+              examples:
+                default:
+                  value: |
+                    2026-04-19T03:44:06.673Z b45a75a5b72e4522972e55edf26de1c8 import 69e44eb7a749d34a975a4747
+                    {"url":"https://httpbin.org/post","method":"POST","body":"{\"id\":\"_id\"}","headers":{"X-None":"********","content-type":"application/json"},"requestIndex":0}
+
+                    2026-04-19T03:44:06.774Z b45a75a5b72e4522972e55edf26de1c8 import 69e44eb7a749d34a975a4747
+                    {"headers":{"date":"Sun, 19 Apr 2026 03:44:06 GMT","content-type":"application/json"},"body":"{\"ok\":true}"}
+        '204':
+          description: |-
+            No debug logs for this export or import — debug capture is off (no future `debugDate`),
+            the step has not run through the connection since it was enabled, or the buffer was
+            cleared.
+        '400':
+          description: '`typeId` is not a valid ObjectId.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalidTypeId:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid typeId.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: The connection, or the export/import named by `typeId`, does not exist in the account.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                connectionNotFound:
+                  summary: Unknown connection id
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Connection not found.
+                resourceNotFound:
+                  summary: typeId is neither an export nor an import
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Export/Import not found.
   /v1/connections/{_id}/metadata:
     put:
       x-internal: false
@@ -1708,7 +1991,8 @@ paths:
         `authorizationUrl` response field serves both OAuth 2.0 and OAuth 1.0a connections (NetSuite
         returns an OAuth 1.0a URL with an `oauth_token` parameter).
 
-        Note the resource segment is singular — `/v1/connection/{_id}/oauth2`, not plural. The URL's
+        The resource segment is singular — `/v1/connection/{_id}/oauth2`; the plural form
+        `/v1/connections/{_id}/oauth2` is an alias that answers identically. The URL's
         `state` token is one-time and expires quickly, so request a fresh one if the flow is
         interrupted, then poll `GET /v1/connections/{_id}` until `needsAuthorization` is `false`.
       parameters:
@@ -1839,7 +2123,8 @@ paths:
         few seconds. Only connections of type `netsuite` are accepted.
 
         Use this instead of the connection's `netsuite.suiteAppInstalled`, which reflects only the
-        SuiteApp as detected the last time the connection authenticated.
+        SuiteApp as detected the last time the connection authenticated. For a single combined
+        reachability result, or for a Salesforce connection, use `GET /v1/connections/{_id}/distributed`.
       operationId: getConnectionDistributedApps
       tags:
         - Connections
@@ -1879,6 +2164,19 @@ paths:
                       success: true
                     suiteapp:
                       success: true
+                neither_installed:
+                  summary: Neither component installed (NetSuite reports the RESTlets missing)
+                  value:
+                    bundle:
+                      success: false
+                      statusCode: 404
+                      resBody: That Suitelet is invalid, disabled, or no longer exists.
+                      URL: https://tstdrv1234567.app.netsuite.com/app/bundler/bundledetails.nl?sourcecompanyid=TSTDRV916910&domain=PRODUCTION&config=F&id=20038
+                    suiteapp:
+                      success: false
+                      statusCode: 404
+                      resBody: That Suitelet is invalid, disabled, or no longer exists.
+                      URL: https://tstdrv1234567.app.netsuite.com/suiteapp/ui/marketplace.nl?whence=#/app?id=com.celigo.integratorio
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '404':
@@ -1913,6 +2211,87 @@ paths:
         - |-
           A non-NetSuite connection answers 422 with the message "invalid connection type: <type>"
           and no `code`; an unknown `_id` answers 404 `invalid_ref`.
+  /v1/connections/{_id}/distributed:
+    get:
+      x-internal: false
+      summary: Ping the distributed adaptor behind a connection
+      description: |-
+        Pings, live, the Celigo distributed adaptor installed in the account behind a `netsuite`
+        or `salesforce` connection — the integrator.io bundle or SuiteApp RESTlet in NetSuite, the
+        Celigo managed package in Salesforce — and reports one combined result. Round-trips to the
+        remote system, so expect a few seconds. The distributed adaptor is what NetSuite real-time
+        exports and `netsuite_da` imports, and Salesforce real-time exports, run through, so this
+        is the check to run before building them.
+
+        Use `GET /v1/connections/{_id}/distributedApps` instead when you need the NetSuite bundle
+        and SuiteApp reported separately; this endpoint is the only one of the two that also covers
+        Salesforce. Any other connection type is rejected with 422.
+      operationId: pingConnectionDistributedAdaptor
+      tags:
+        - Connections
+      parameters:
+        - in: path
+          name: _id
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: connections
+          description: NetSuite or Salesforce connection to check.
+      responses:
+        '200':
+          description: 'Ping result. `success: false` is still HTTP 200 — inspect the body.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DistributedAdaptorStatus'
+              examples:
+                installed:
+                  summary: Distributed adaptor reachable
+                  value:
+                    success: true
+                netsuiteMissing:
+                  summary: NetSuite account without the Celigo bundle or SuiteApp
+                  value:
+                    success: false
+                    statusCode: 404
+                    resBody: That Suitelet is invalid, disabled, or no longer exists.
+                    bundleURL: https://tstdrv1234567.app.netsuite.com/app/bundler/bundledetails.nl?sourcecompanyid=TSTDRV916910&domain=PRODUCTION&config=F&id=20038
+                salesforceOffline:
+                  summary: Salesforce connection that is offline
+                  value:
+                    success: false
+                    resBody: 'Connection is taken offline: expired access/refresh token'
+                    bundleURL: https://mycompany.my.salesforce.com/packaging/installPackage.apexp?p0=04t3m000000Q89d
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: No connection found for the given `_id`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_ref:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Connection not found for the given id.
+        '422':
+          description: The connection exists but is neither a NetSuite nor a Salesforce connection.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_connection_type:
+                  value:
+                    errors:
+                      - message: 'invalid connection type: http'
+      x-celigo-ai-guidance:
+        - |-
+          A non-NetSuite, non-Salesforce connection answers 422 with the message "invalid
+          connection type: <type>" and no `code`; an unknown `_id` answers 404 `invalid_ref`.
   /v1/salesforce/metadata/connections/{_id}/sObjectTypes:
     get:
       x-internal: false
@@ -2823,11 +3202,75 @@ components:
               readOnly: true
               examples:
                 - 5f29dbc69e8a0f0e29a491b7
+            connectionRole:
+              type: string
+              enum:
+                - standard
+                - mcpChild
+              x-enumDescriptions:
+                standard: An ordinary account-owned connection, created and edited through this API
+                mcpChild: An MCP end user's private credential copy of a parent connection, created by the end-user setup page
+              readOnly: true
+              description: |-
+                Distinguishes account-owned connections from the per-end-user credential copies
+                MCP servers collect. Absent on connections last saved before the field existed,
+                which behave as `standard`. Sending `mcpChild` on `POST` or `PUT /v1/connections`
+                fails with 422 `mcp_child_generic_route_not_allowed`, and `/connectionRole` is not a
+                patchable path; child connections are written only by the MCP end-user setup page,
+                never through `/v1`.
+              examples:
+                - standard
+            endUserProvidedFields:
+              type: array
+              items:
+                type: string
+              description: |-
+                Dot-paths of this connection's fields (for example `http.encrypted.apiKey` or
+                `rdbms.user`) that each MCP end user must supply on their own `mcpChild` copy instead
+                of inheriting the parent's value. Only returned on a `standard` connection that has
+                paths set; never returned on a child. Writable through `POST`, `PUT`, and `PATCH`.
+              examples:
+                - - http.encrypted.apiKey
+                  - http.unencrypted.accountId
+            _parentConnectionId:
+              type: string
+              format: objectId
+              x-celigo-refModel: connections
+              readOnly: true
+              description: |-
+                Parent connection this child copies its non-credential configuration from. Present
+                only when `connectionRole` is `mcpChild`; set by the end-user setup page and ignored
+                when sent on a standard connection.
+              examples:
+                - 615dfa0742763671275b70ab
+            _mcpOwnerId:
+              type: string
+              format: objectId
+              x-celigo-refModel: users
+              readOnly: true
+              description: |-
+                Account owner whose parent connection and MCP servers this child belongs to. Present
+                only when `connectionRole` is `mcpChild`; on a child, `_userId` is the end user and
+                this field is the account.
+              examples:
+                - 5d2e1f0a9b8c7d6e5f4a3b2c
+            _parentSyncedAt:
+              type: string
+              format: date-time
+              readOnly: true
+              description: |-
+                Timestamp when the child's non-credential fields were last synced from the parent
+                connection. Present only when `connectionRole` is `mcpChild`.
+              examples:
+                - '2026-09-15T18:42:10.331Z'
             _userId:
               type: string
               format: objectId
               x-celigo-refModel: users
-              description: User who owns this connection.
+              description: |-
+                End user who owns this `mcpChild` connection's credentials. Present only when
+                `connectionRole` is `mcpChild`; a standard connection belongs to the account and
+                omits this field.
               readOnly: true
               examples:
                 - 5d2e1f0a9b8c7d6e5f4a3b2c
@@ -3101,7 +3544,7 @@ components:
             NetSuite application ID from the integration record.
             Required for some authentication configurations to identify the calling application.
         concurrencyLevel:
-          type: number
+          type: integer
           description: |
             General concurrency level for this connection. Controls the overall
             maximum concurrent requests across all operation types.
@@ -3110,7 +3553,7 @@ components:
           maximum: 50
           default: 5
         targetConcurrencyLevel:
-          type: number
+          type: integer
           description: |
             Target concurrency level for auto-scaling. The system adjusts concurrency
             between 1 and this value based on rate limit and governance feedback.
@@ -3254,7 +3697,7 @@ components:
             - 'Never set or repair this field to fix an authentication failure: an empty or absent list is the normal stored state, and UI saves reset API-written values.'
             - For a custom Connected App (`salesforce._iClientId` set), requested scopes are configured on the iClient's `oauth2.scope` and constrained by the Connected App inside Salesforce — not on the connection.
         concurrencyLevel:
-          type: number
+          type: integer
           description: |-
             Maximum number of concurrent API requests to Salesforce. Salesforce enforces per-org API
             request limits, so setting this high consumes the org's API call allocation faster. Values
@@ -3264,7 +3707,7 @@ components:
           maximum: 50
           default: 5
         targetConcurrencyLevel:
-          type: number
+          type: integer
           description: |-
             Upper bound for auto-scaling concurrency. When automatic rate-limit recovery is enabled, the
             system adjusts concurrency between 1 and this value based on rate-limit feedback from
@@ -3427,19 +3870,24 @@ components:
           examples:
             - 66a1b2c3d4e5f60718293a4b
         concurrencyLevel:
-          type: number
+          type: integer
           description: |
             Maximum number of concurrent file transfer operations.
             FTP servers often have low connection limits — keep this value conservative.
             Values above the account's licensed maximum (25 standard, 50 with an Environments license) are silently clamped down.
+            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
           default: 1
+          examples:
+            - 3
         targetConcurrencyLevel:
-          type: number
+          type: integer
           description: |
             Target concurrency level for auto-scaling. The system adjusts concurrency
             between 1 and this value based on server response feedback.
+            Kept on a `PUT` that omits it, like `concurrencyLevel`; unset by the save while
+            `autoRecoverRateLimitErrors` is false.
           minimum: 1
           maximum: 50
           examples:
@@ -3454,7 +3902,8 @@ components:
             save the value is mirrored into `userConcurrencyLevel` (and into
             `userTargetConcurrencyLevel` when auto-recovery of rate-limit errors
             is active with `targetConcurrencyLevel` set); clearing it clears the
-            mirrors.
+            mirrors. Not preserved across a `PUT` — re-send it with the rest of
+            the `ftp` object or it is cleared.
           examples:
             - 2
         userConcurrencyLevel:
@@ -3544,7 +3993,7 @@ components:
           examples:
             - my-data-lake
         concurrencyLevel:
-          type: number
+          type: integer
           description: |-
             Maximum number of concurrent S3 operations. Applies when `autoRecoverRateLimitErrors` is
             false; when auto-recover is on (the default) concurrency auto-scales up to
@@ -3554,7 +4003,7 @@ components:
           maximum: 50
           default: 5
         targetConcurrencyLevel:
-          type: number
+          type: integer
           description: |-
             Upper bound for auto-scaled concurrency when `autoRecoverRateLimitErrors` is true (the
             default). The system raises and lowers concurrency between 1 and this value based on
@@ -4042,7 +4491,7 @@ components:
           "Amazon-Hybrid", populate unencrypted.marketplaceId ("ATVPDKIKX0DER") and
           unencrypted.sellingRegion ("northAmerica"), and let the user finish the connection in the
           Celigo UI. Omitting either field fails the POST with 422 "Expected field: marketplaceId to be present".
-      x-celigo-ui-override: The auth.type conditional below encodes the connection form's credential requireds. Most are also API-enforced; the form-only additions (the API creates the connection without them, or accepts a weaker rule) are auth.basic.password (the API accepts a username alone), auth.token.location, auth.token.headerName (wsse), auth.cookie.method, auth.cookie.body, and _iClientId (oauth) — each flagged on its own field.
+      x-celigo-ui-override: The auth.type conditional below encodes the connection form's credential requireds. Most are also API-enforced; the form-only additions (the API creates the connection without them, or accepts a weaker rule) are auth.basic.password (the API accepts a username alone), auth.token.location, auth.token.headerName (wsse), auth.cookie.method, auth.cookie.body, and _iClientId (oauth) — each flagged on its own field. _iClientId for awsiam is both form- and API-required.
       required:
         - baseURI
         - mediaType
@@ -4129,19 +4578,23 @@ components:
             NEVER disable in production — it removes protection against man-in-the-middle attacks.
           default: false
         concurrencyLevel:
-          type: number
+          type: integer
           description: |
             Maximum number of concurrent HTTP requests this connection can make simultaneously.
 
             Higher values increase throughput but may trigger API rate limits.
             Set this based on the target API's rate limit documentation.
-            Values above the account's licensed maximum (25 standard, 50 with an Environments license) are silently clamped down.
+            Values above the account's licensed maximum (25 standard, 50 with an Environments license) are silently clamped down,
+            but a decimal is rejected with 422 `invalid_field_value` on every write (the same rule applies to every
+            adaptor's `concurrencyLevel` and `targetConcurrencyLevel`, and to `ftp.multiThreadCount`).
             Platform-managed while `autoRecoverRateLimitErrors` is true — a PUT ignores the value and the recovery machinery moves it toward the target; set `targetConcurrencyLevel` instead.
           minimum: 1
           maximum: 50
           default: 25
+          examples:
+            - 10
         targetConcurrencyLevel:
-          type: number
+          type: integer
           description: |
             Ceiling the platform climbs back to after rate-limit recovery, in steps of 25% of this value.
             Writing it also sets `concurrencyLevel` to the same value and stops any recovery in progress.
@@ -4360,10 +4813,12 @@ components:
               x-lowercase: true
               x-celigo-ai-guidance:
                 - |-
-                  When type is "awsiam", the connection must also carry
-                  http._iClientId pointing at an AWS-IAM iClient — the save is
-                  rejected without it. The signing credentials live on the
-                  iClient, not on the connection.
+                  When type is "awsiam", the connection must also carry http._iClientId pointing at
+                  an iClient with provider "awsIam" that belongs to the same account and has
+                  awsIam.roleArn whose role name starts with "celigo-http-adaptor-"; the save fails
+                  with 422 (missing_required_field, invalid_field, invalid_field_value, or invalid_ref
+                  respectively) when any of these is off. The signing credentials live on the iClient,
+                  not on the connection.
               examples:
                 - token
             failStatusCode:
@@ -5009,28 +5464,64 @@ components:
           type: string
           format: objectId
           x-celigo-refModel: iclients
-          description: ID of the iClient used for OAuth authentication.
+          description: |-
+            iClient that holds the credentials this connection signs with: the OAuth 2.0 client for
+            `auth.type` `oauth` (including the `azureserviceprincipal` service principal an Azure
+            Data Lake Storage Gen2 connection authenticates with and the `googleserviceaccount` key
+            a Google Cloud Storage connection uses), or the `awsIam` role for `auth.type` `awsiam`.
+            Must belong to the same account as the connection. Omit for every other auth type.
           examples:
             - 6203a7e4f321d800129a1b8e
-          x-celigo-ui-override: Required by the connection form for oauth (OAuth 2.0) auth; the API creates the connection without it (the OAuth authorization is completed afterward).
+          x-celigo-ui-override: 'Required by the connection form for oauth (subForms/httpOAuth.js: required true, iClient filter provider custom_oauth2, or googleserviceaccount / azureserviceprincipal for the GCS and ADLS Gen2 variants) and for awsIam (subForms/httpAwsIam.js: required true, filter provider awsIam). For oauth the API creates the connection without it and the authorization is completed afterward; for awsiam the API also rejects its absence (see the if/then rule on this schema).'
+          x-celigo-ai-guidance:
+            - |-
+              For auth.type "awsiam" the referenced iClient must have provider "awsIam" (any other
+              provider → 422 invalid_field "IClient provider must be awsIam for HTTP IAM Role
+              authentication."), must carry awsIam.roleArn (missing → 422 missing_required_field
+              "Expected field: awsIam.roleArn to be present."), and its role name must start with
+              "celigo-http-adaptor-" (otherwise → 422 invalid_field_value). Omitting _iClientId
+              altogether → 422 missing_required_field "Expected field: _iClientId to be present."
+            - |-
+              An Azure Data Lake Storage Gen2 connection (assistant "azuredatalakestoragegen2", or any
+              http.baseURI containing "dfs.core.windows.net") must reference an iClient with provider
+              "azureserviceprincipal"; any other provider fails the save with 422 invalid_field
+              "IClient provider must be azureserviceprincipal for Azure Data Lake Storage Gen2
+              connections."
+            - |-
+              The iClient must belong to the same account as the connection — an iClient id from
+              another account fails with 422 invalid_ref "The referenced IClient must belong to the
+              same user."
         _httpConnectorId:
           type: string
           format: objectId
           x-celigo-refModel: httpconnectors
-          description: ID of the HTTP connector template this connection is based on.
+          description: |-
+            HTTP connector (pre-built application template) this connection is linked to. Linking
+            lets exports and imports on the connection pick endpoints from the connector's catalog and
+            drives the `assistant` form in the UI. An id that does not resolve to an accessible
+            connector is dropped from the saved document rather than rejected — read the response back
+            to confirm the link took.
           examples:
             - 5d8f6a2b9c1e4f00112a3b4c
         _httpConnectorApiId:
           type: string
           format: objectId
           x-celigo-refModel: httpconnectorapis
-          description: ID of the HTTP connector API definition (an API within the referenced HTTP connector).
+          description: |-
+            API within the linked HTTP connector that this connection targets, for connectors that
+            publish more than one API. Only meaningful together with `_httpConnectorId`; an id that is
+            not one of that connector's APIs is dropped on save, not rejected.
           examples:
             - 5d8f6a2b9c1e4f00112a3b4d
         _httpConnectorVersionId:
           type: string
           format: objectId
-          description: ID of the HTTP connector version (a version within the referenced HTTP connector).
+          description: |-
+            Version entry of the linked HTTP connector (an item of the connector's `versions` array)
+            whose endpoint definitions this connection uses. Only meaningful together with
+            `_httpConnectorId`; an id that is not one of that connector's published versions is
+            replaced by a published version of the connector on create and dropped on update, never
+            rejected.
           examples:
             - 5d8f6a2b9c1e4f00112a3b4e
         isRest:
@@ -5056,6 +5547,20 @@ components:
             required:
               - marketplaceId
               - sellingRegion
+      else:
+        if:
+          properties:
+            auth:
+              properties:
+                type:
+                  const: awsiam
+              required:
+                - type
+          required:
+            - auth
+        then:
+          required:
+            - _iClientId
     RDBMS:
       type: object
       description: |-
@@ -5258,7 +5763,7 @@ components:
           examples:
             - dedicated
         concurrencyLevel:
-          type: number
+          type: integer
           description: |
             Maximum number of concurrent database connections.
             Set based on the database server's connection limit and available resources.
@@ -5267,7 +5772,7 @@ components:
           maximum: 50
           default: 5
         targetConcurrencyLevel:
-          type: number
+          type: integer
           description: |
             Target concurrency level for auto-scaling. The system adjusts the number of
             concurrent connections between 1 and this value based on performance feedback.
@@ -5800,7 +6305,7 @@ components:
           examples:
             - admin
         concurrencyLevel:
-          type: number
+          type: integer
           description: |
             Maximum number of concurrent MongoDB operations.
             Values above the account's licensed maximum (25 standard, 50 with an Environments license) are silently clamped down.
@@ -5808,7 +6313,7 @@ components:
           maximum: 50
           default: 5
         targetConcurrencyLevel:
-          type: number
+          type: integer
           description: |
             Target concurrency level for auto-scaling. The system adjusts concurrency
             between 1 and this value based on rate limit feedback.
@@ -6361,7 +6866,7 @@ components:
               Required when signing or encryption is enabled (not NONE).
               Auto-generated self-signed certificates will be injected if not provided.
         concurrencyLevel:
-          type: number
+          type: integer
           description: |-
             Maximum number of messages processed concurrently for this connection. The default of 5
             is safe for most partners. Values above the account's licensed maximum (25 standard, 50
@@ -6370,7 +6875,7 @@ components:
           maximum: 50
           default: 5
         targetConcurrencyLevel:
-          type: number
+          type: integer
           description: |-
             Concurrency ceiling integrator.io scales up to when auto-recovering from rate-limit
             errors. Only applies when autoRecoverRateLimitErrors is true on the connection.
@@ -6410,7 +6915,7 @@ components:
                   The system verifies the directory exists and is accessible.
                   Example: "/data/integrations/incoming" or "C:\\Data\\Integrations".
         concurrencyLevel:
-          type: number
+          type: integer
           description: |-
             Maximum number of files processed concurrently. Cannot exceed `targetConcurrencyLevel`; a higher
             value is silently clamped down to it. Values above the account's licensed maximum (25 standard,
@@ -6419,7 +6924,7 @@ components:
           maximum: 50
           default: 1
         targetConcurrencyLevel:
-          type: number
+          type: integer
           description: |-
             Upper bound for auto-scaling. The agent scales concurrency between 1 and this value based on
             throughput, so it also caps `concurrencyLevel`. Values above the account's licensed maximum
@@ -6863,7 +7368,7 @@ components:
               examples:
                 - wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
         concurrencyLevel:
-          type: number
+          type: integer
           description: |-
             Maximum number of DynamoDB requests this connection runs at once.
 
@@ -6877,7 +7382,7 @@ components:
               Maximum number of concurrent DynamoDB operations.
               DynamoDB throughput is governed by table-level read/write capacity units.
         targetConcurrencyLevel:
-          type: number
+          type: integer
           description: |-
             Concurrency ceiling for auto-scaling. The system adjusts the active concurrency between 1
             and this value based on rate-limit feedback. Only applied when `autoRecoverRateLimitErrors`
@@ -7037,7 +7542,7 @@ components:
               - name: ServerDataSource
                 value: NetSuite2.com
         concurrencyLevel:
-          type: number
+          type: integer
           description: |
             Maximum number of concurrent database connections.
             JDBC connections often run through a single Agent, so keep this value
@@ -7049,7 +7554,7 @@ components:
           examples:
             - 5
         targetConcurrencyLevel:
-          type: number
+          type: integer
           description: |
             Target concurrency level for auto-scaling. The system adjusts the number of
             concurrent connections between 1 and this value based on performance feedback.
@@ -7345,7 +7850,7 @@ components:
           examples:
             - 566686c4d0b969657e7850ba
         concurrencyLevel:
-          type: number
+          type: integer
           description: |
             Maximum number of concurrent operations through this wrapper connection.
             Values above the account's licensed maximum (25 standard, 50 with an Environments license) are silently clamped down.
@@ -7353,7 +7858,7 @@ components:
           maximum: 50
           default: 5
         targetConcurrencyLevel:
-          type: number
+          type: integer
           description: |
             Target concurrency level for auto-scaling. The system adjusts concurrency
             between 1 and this value based on performance feedback.
@@ -7770,6 +8275,31 @@ components:
               __failedIntegrationRegistrations with code not_allowed.
           examples:
             - - 6a55be91d16ee8270022893e
+        endUserProvidedFields:
+          type:
+            - array
+            - 'null'
+          items:
+            type: string
+          description: |-
+            Dot-paths of this connection's fields (for example `http.encrypted.apiKey` or
+            `rdbms.user`) that each MCP end user must supply on their own `mcpChild` copy instead of
+            inheriting the parent's value. Set it on the parent connection an MCP server collects
+            end-user credentials for; omit it everywhere else. Omitting it (or sending `[]`) on
+            `PUT` keeps the stored paths; send `null` to clear them.
+          x-celigo-ai-guidance:
+            - |-
+              List only the credential and tenant fields that differ per end user, never a path the
+              account owns: `type`, `_agentId`, `wrapper._stackId`, or any `<adaptor>._iClientId`
+              (e.g. `http._iClientId`) fails the save with 422
+              `mcp_end_user_provided_field_not_allowed`.
+            - |-
+              This is the only MCP end-user field writable through `/v1/connections`; the child
+              connections themselves are created by the end-user setup page, and `connectionRole:
+              mcpChild` in a `POST` or `PUT` body fails with 422 `mcp_child_generic_route_not_allowed`.
+          examples:
+            - - http.encrypted.apiKey
+              - http.unencrypted.accountId
         debugDate:
           type: string
           format: date-time
@@ -8490,6 +9020,13 @@ components:
           description: Display name of the dependent resource.
           examples:
             - Import Orders to NetSuite
+        type:
+          type: string
+          description: |-
+            Sub-type of the dependent resource when its collection distinguishes one, such as
+            `stream` for a listener export. Only present for resource types that carry a `type`.
+          examples:
+            - stream
         paths:
           type: array
           description: |-
@@ -8559,12 +9096,63 @@ components:
       properties:
         success:
           type: boolean
-          description: When true, the component is installed in the connected NetSuite account.
+          description: When true, the component is installed in the connected NetSuite account. The remaining fields are present only when false.
+          examples:
+            - true
+        statusCode:
+          type: integer
+          description: HTTP status NetSuite returned for the failed check — 404 when the component's RESTlet is not installed.
+          examples:
+            - 404
+        resBody:
+          type: string
+          description: NetSuite's error text for the failed check.
+          examples:
+            - That Suitelet is invalid, disabled, or no longer exists.
         URL:
           type: string
+          format: uri
           description: |-
             Install link for the component. Absent when `success` is true; the integrator.io UI
             reads it to render its install prompt when the component is missing.
+          examples:
+            - https://tstdrv1234567.app.netsuite.com/suiteapp/ui/marketplace.nl?whence=#/app?id=com.celigo.integratorio
+    DistributedAdaptorStatus:
+      type: object
+      required:
+        - success
+      description: Result of pinging the Celigo distributed adaptor installed in the connected account.
+      properties:
+        success:
+          type: boolean
+          description: |-
+            When true, the Celigo distributed adaptor (the integrator.io bundle or SuiteApp in
+            NetSuite, the Celigo managed package in Salesforce) answered the ping and the
+            connection can run distributed exports and imports. The remaining fields are present
+            only when false.
+          examples:
+            - true
+        statusCode:
+          type: integer
+          description: |-
+            HTTP status the remote system returned for the failed ping — for example 404 when
+            NetSuite reports the Celigo RESTlet is not installed. Absent when the failure did not
+            reach the remote system (for example, a connection that is offline).
+          examples:
+            - 404
+        resBody:
+          type: string
+          description: Remote system's error text, or the platform's reason when the ping was not attempted.
+          examples:
+            - That Suitelet is invalid, disabled, or no longer exists.
+        bundleURL:
+          type: string
+          format: uri
+          description: |-
+            Install link for the missing component in the connected account — the NetSuite bundle
+            details page, or the Salesforce package installer — for the UI's install prompt.
+          examples:
+            - https://tstdrv1234567.app.netsuite.com/app/bundler/bundledetails.nl?sourcecompanyid=TSTDRV916910&domain=PRODUCTION&config=F&id=20038
     SObjectType:
       type: object
       description: |
@@ -9082,9 +9670,10 @@ components:
                 errors:
                   - code: invalid_request
                     message: The request body failed validation.
-    422-unprocessable-entity:
-      description: |
-        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
+    422-dependency-conflict:
+      description: |-
+        The resource has dependents that must be deleted first. Each entry
+        in the `errors` array names one blocking resource.
       content:
         application/json:
           schema:
@@ -9093,12 +9682,11 @@ components:
             default:
               value:
                 errors:
-                  - code: unprocessable_entity
-                    message: The request could not be processed due to a semantic error.
-    422-dependency-conflict:
-      description: |-
-        The resource has dependents that must be deleted first. Each entry
-        in the `errors` array names one blocking resource.
+                  - code: dependencies_not_deleted
+                    message: export 6902d88c10b42b2eaac9b2a1 must be deleted before you can delete connection 6398ddf316be761fb16a6523
+    422-unprocessable-entity:
+      description: |
+        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
       content:
         application/json:
           schema:
@@ -9107,7 +9695,7 @@ components:
             default:
               value:
                 errors:
-                  - code: dependencies_not_deleted
-                    message: export 6902d88c10b42b2eaac9b2a1 must be deleted before you can delete connection 6398ddf316be761fb16a6523
+                  - code: unprocessable_entity
+                    message: The request could not be processed due to a semantic error.
 x-enable-proxy: true
 x-internal: false