@celigo/api-specs 0.2.152 → 0.2.154

package/dist/ai-agent.yml

@@ -2410,6 +2410,12 @@ components:
             - Examples: '$.customer.firstName', '$.items[0].price', '$.addresses[*].street',
               '$[*].Tax' (every row of a grouped record)
             - Wildcards like [*] extract multiple values/objects
+            - A key that contains a dot needs bracket notation: `$['P.O. Number']` (or
+              `$["P.O. Number"]`, `$.[P.O. Number]`). `$.P.O. Number` is read as a nested
+              path: it maps nothing and the record still succeeds. Spaces, hyphens and `#`
+              need no brackets (`$.Ship To Name`, `$.Tracking #`)
+            - Filter expressions such as `$.items[?(@.active)]` fail the record with
+              "Eval [?(expr)] prevented in JSONPath expression."
 
             ```json
             "extract": "$.customer.addresses[*]"  // Extracts all addresses
@@ -2598,6 +2604,12 @@ components:
             **Usage**
 
             The lookupName refers to a named lookup defined in the lookups array of the same resource.
+            On an HTTP import that is `http.lookups`: a `lookups` array sent only at the top level
+            is dropped on save. On an import, a name that matches no lookup fails every record
+            with "Unable to find lookup in mapping configs - <name>", and a key the lookup
+            doesn't hold follows the lookup's `allowFailures`: false fails the record; true, or
+            the field left out, lets the record succeed with the lookup's `default`, or without
+            the mapped field when there is none.
 
             ```json
             {
@@ -2935,6 +2947,11 @@ components:
                   The system creates special composite objects during processing to maintain
                   hierarchical relationships, allowing easy access to both the current array item
                   and its parent contexts.
+
+                  An iterating entry keeps the `[*]`: `$.line_items` without it yields one empty
+                  element per item, with no error. Child extracts drop the `[*]` but keep the
+                  array's path (`$.line_items.sku`); `$.line_items[*].sku` maps nothing, and an
+                  element-relative `$.sku` reads the record root instead of the element.
                 examples:
                   - $.items[*]
                   - $.order.lineItems[*]
@@ -3146,14 +3163,17 @@ components:
           type: string
           description: |
             **Purpose**
-            Required on every mapping entry. Controls whether the mapping is applied.
+            Controls whether the mapping is applied. Send it on every mapping entry.
 
             **Guidance**
             Only `Active` rows run. `Draft` and `Inactive` rows keep their
             configuration, are saved with minimal validation, and are skipped at
             runtime and in preview; a non-Active parent skips its whole subtree
-            whatever its children say. The API rejects a mapping missing this field
-            (validation error: "Mapping object must have status field present.").
+            whatever its children say. Imports (on save and in the mapper processor)
+            and API response mappings reject a row missing this field (validation
+            error: "Mapping object must have status field present."); a Tool's
+            output mapping saves and runs one, which is why `required` doesn't
+            list it.
           x-celigo-ai-guidance:
             - |-
               Emit `"Active"` for mappings that should run; `"Draft"` is also
@@ -3476,6 +3496,12 @@ components:
               - Examples: '$.customer.firstName', '$.items[0].price', '$.addresses[*].street',
                 '$[*].Tax' (every row of a grouped record)
               - Wildcards like [*] extract multiple values/objects
+              - A key that contains a dot needs bracket notation: `$['P.O. Number']` (or
+                `$["P.O. Number"]`, `$.[P.O. Number]`). `$.P.O. Number` is read as a nested
+                path: it maps nothing and the record still succeeds. Spaces, hyphens and `#`
+                need no brackets (`$.Ship To Name`, `$.Tracking #`)
+              - Filter expressions such as `$.items[?(@.active)]` fail the record with
+                "Eval [?(expr)] prevented in JSONPath expression."
 
               ```json
               "extract": "$.customer.addresses[*]"  // Extracts all addresses
@@ -3664,6 +3690,12 @@ components:
               **Usage**
 
               The lookupName refers to a named lookup defined in the lookups array of the same resource.
+              On an HTTP import that is `http.lookups`: a `lookups` array sent only at the top level
+              is dropped on save. On an import, a name that matches no lookup fails every record
+              with "Unable to find lookup in mapping configs - <name>", and a key the lookup
+              doesn't hold follows the lookup's `allowFailures`: false fails the record; true, or
+              the field left out, lets the record succeed with the lookup's `default`, or without
+              the mapped field when there is none.
 
               ```json
               {
@@ -4001,6 +4033,11 @@ components:
                     The system creates special composite objects during processing to maintain
                     hierarchical relationships, allowing easy access to both the current array item
                     and its parent contexts.
+
+                    An iterating entry keeps the `[*]`: `$.line_items` without it yields one empty
+                    element per item, with no error. Child extracts drop the `[*]` but keep the
+                    array's path (`$.line_items.sku`); `$.line_items[*].sku` maps nothing, and an
+                    element-relative `$.sku` reads the record root instead of the element.
                   examples:
                     - $.items[*]
                     - $.order.lineItems[*]
@@ -4212,14 +4249,17 @@ components:
             type: string
             description: |
               **Purpose**
-              Required on every mapping entry. Controls whether the mapping is applied.
+              Controls whether the mapping is applied. Send it on every mapping entry.
 
               **Guidance**
               Only `Active` rows run. `Draft` and `Inactive` rows keep their
               configuration, are saved with minimal validation, and are skipped at
               runtime and in preview; a non-Active parent skips its whole subtree
-              whatever its children say. The API rejects a mapping missing this field
-              (validation error: "Mapping object must have status field present.").
+              whatever its children say. Imports (on save and in the mapper processor)
+              and API response mappings reject a row missing this field (validation
+              error: "Mapping object must have status field present."); a Tool's
+              output mapping saves and runs one, which is why `required` doesn't
+              list it.
             x-celigo-ai-guidance:
               - |-
                 Emit `"Active"` for mappings that should run; `"Draft"` is also
@@ -5213,8 +5253,8 @@ components:
               - Original value indicators: "{Original Value}", "No mapping found"
               - Neutral values: "Other", "N/A", "Miscellaneous"
 
-              If allowFailures is false and no default is specified, the flow will fail
-              when encountering unmapped values.
+              If allowFailures is false, a record whose value is unmapped fails and the default
+              is ignored.
             examples:
               - Unknown
               - Other
@@ -5235,7 +5275,11 @@ components:
               This field determines how the system handles source values that don't exist in the map:
 
               - true: Use the default value for missing mappings and continue processing
-              - false: Treat missing mappings as errors, failing the record
+              - false: Treat missing mappings as errors, failing the record (`lookup_error` for a
+                static map, `lookupcache_evaluation_failed` for a lookup cache)
+              - omitted or null: the record doesn't fail either. On an import a static lookup writes
+                its default if it has one, and a static or cache lookup without one leaves the
+                mapped field out of the output, with no error
 
               **Recommendation**
 
@@ -5249,11 +5293,14 @@ components:
               - All possible source values are known and controlled
               - Missing mappings indicate serious data problems that should be addressed
 
-              The best practice is typically to set allowFailures to true with a meaningful
-              default value, so flows remain operational while alerting you to missing mappings.
+              A default raises no error: records that miss go out with the default value and
+              nothing reports them. Use true only when that fallback is acceptable at the
+              destination, and set false explicitly when a missing value must stop the record.
             examples:
               - true
               - false
+            x-celigo-ai-guidance:
+              - 'Never leave this field out to mean "fail on a miss": on an import, an omitted or null value lets a missing key through without an error (with the default, or without the mapped field when there is none). Only an explicit false fails the record.'
     Transform:
       type: object
       description: |

package/dist/api.yml

@@ -5258,7 +5258,7 @@ components:
                 connection's traffic counts against the referenced connection's limit instead of its own,
                 and its own concurrency and auto-recovery settings have no effect. One level only: the
                 referenced connection may not itself borrow, and a connection that others borrow from
-                cannot start borrowing.
+                cannot start borrowing. A connection cannot reference itself (422).
               examples:
                 - 615dfa0742763671275b70ab
               x-celigo-ai-guidance:
@@ -5295,16 +5295,21 @@ components:
               type: boolean
               description: |-
                 When true, the connection has been taken offline and is skipped during flow execution.
-                The platform tests the connection after a create or `PUT` and updates this shortly
-                afterwards (the audit log records a `system` change; `lastModified` doesn't move), so
-                read it again a few seconds after the write.
+                It is set by the connection test a create or `PUT` runs: the result arrives in the
+                write's response or, when the target is slow to answer, shortly afterwards (the audit
+                log records a `system` change; `lastModified` doesn't move), so read it again a few
+                seconds after the write. On an `http` connection the write runs the test only when
+                `http.ping` is configured, and an `http` connection that was never tested has no
+                `offline` key.
               readOnly: true
             needsAuthorization:
               type: boolean
               readOnly: true
               description: |-
                 OAuth handshake state. Celigo's OAuth callback sets it to `false` once the user consents
-                and the tokens are stored (see `GET /v1/connection/{_id}/oauth2`).
+                and the tokens are stored (see `GET /v1/connection/{_id}/oauth2`). A connection that
+                was never authorized usually has no `needsAuthorization` key, so its absence does not
+                mean the connection is authorized.
             _sourceId:
               type: string
               format: objectId
@@ -6279,15 +6284,18 @@ components:
         clientId:
           type: string
           description: |
-            OAuth client ID (application ID) registered with the API provider.
-            Required for all OAuth 2.0 grant types.
+            OAuth client ID (application ID) registered with the API provider. An `http`
+            connection takes the app from a `custom_oauth2` iClient referenced by `http._iClientId`
+            (an `mcp` connection from `mcp.http._iClientId`) and doesn't store this field: a create
+            that sends `clientId` and `clientSecret` here answers 201 without either (and stores
+            `useIClientFields: true` unless `false` is sent).
           examples:
             - 0oa1b2c3d4EXAMPLE5
         clientSecret:
           type: string
           description: |
-            OAuth client secret (encrypted at rest).
-            Required for "authorizecode" and "clientcredentials" grant types.
+            OAuth client secret (encrypted at rest). Not stored on an `http` connection: the secret
+            belongs on the iClient (see `clientId`).
           writeOnly: true
           examples:
             - cs_abc123EXAMPLE456secret
@@ -6503,9 +6511,11 @@ components:
           - "authorizecode" — Authorization Code flow (browser-based user consent).
             Requires authURI, tokenURI, and user authorization via browser.
           - "clientcredentials" — Client Credentials flow (server-to-server, no user).
-            Requires tokenURI, clientId, clientSecret.
+            Requires tokenURI.
           - "password" — Resource Owner Password flow (username/password exchange).
-            Requires tokenURI, username, password, clientId, clientSecret.
+            Requires tokenURI, username, password.
+          - On an `http` connection the client ID and secret are never stored here: a
+            `custom_oauth2` iClient referenced by `http._iClientId` supplies them.
     JWT:
       type: object
       description: |-

package/dist/asynchelper.yml

@@ -619,6 +619,12 @@ components:
             - Examples: '$.customer.firstName', '$.items[0].price', '$.addresses[*].street',
               '$[*].Tax' (every row of a grouped record)
             - Wildcards like [*] extract multiple values/objects
+            - A key that contains a dot needs bracket notation: `$['P.O. Number']` (or
+              `$["P.O. Number"]`, `$.[P.O. Number]`). `$.P.O. Number` is read as a nested
+              path: it maps nothing and the record still succeeds. Spaces, hyphens and `#`
+              need no brackets (`$.Ship To Name`, `$.Tracking #`)
+            - Filter expressions such as `$.items[?(@.active)]` fail the record with
+              "Eval [?(expr)] prevented in JSONPath expression."
 
             ```json
             "extract": "$.customer.addresses[*]"  // Extracts all addresses
@@ -807,6 +813,12 @@ components:
             **Usage**
 
             The lookupName refers to a named lookup defined in the lookups array of the same resource.
+            On an HTTP import that is `http.lookups`: a `lookups` array sent only at the top level
+            is dropped on save. On an import, a name that matches no lookup fails every record
+            with "Unable to find lookup in mapping configs - <name>", and a key the lookup
+            doesn't hold follows the lookup's `allowFailures`: false fails the record; true, or
+            the field left out, lets the record succeed with the lookup's `default`, or without
+            the mapped field when there is none.
 
             ```json
             {
@@ -1144,6 +1156,11 @@ components:
                   The system creates special composite objects during processing to maintain
                   hierarchical relationships, allowing easy access to both the current array item
                   and its parent contexts.
+
+                  An iterating entry keeps the `[*]`: `$.line_items` without it yields one empty
+                  element per item, with no error. Child extracts drop the `[*]` but keep the
+                  array's path (`$.line_items.sku`); `$.line_items[*].sku` maps nothing, and an
+                  element-relative `$.sku` reads the record root instead of the element.
                 examples:
                   - $.items[*]
                   - $.order.lineItems[*]
@@ -1355,14 +1372,17 @@ components:
           type: string
           description: |
             **Purpose**
-            Required on every mapping entry. Controls whether the mapping is applied.
+            Controls whether the mapping is applied. Send it on every mapping entry.
 
             **Guidance**
             Only `Active` rows run. `Draft` and `Inactive` rows keep their
             configuration, are saved with minimal validation, and are skipped at
             runtime and in preview; a non-Active parent skips its whole subtree
-            whatever its children say. The API rejects a mapping missing this field
-            (validation error: "Mapping object must have status field present.").
+            whatever its children say. Imports (on save and in the mapper processor)
+            and API response mappings reject a row missing this field (validation
+            error: "Mapping object must have status field present."); a Tool's
+            output mapping saves and runs one, which is why `required` doesn't
+            list it.
           x-celigo-ai-guidance:
             - |-
               Emit `"Active"` for mappings that should run; `"Draft"` is also
@@ -1685,6 +1705,12 @@ components:
               - Examples: '$.customer.firstName', '$.items[0].price', '$.addresses[*].street',
                 '$[*].Tax' (every row of a grouped record)
               - Wildcards like [*] extract multiple values/objects
+              - A key that contains a dot needs bracket notation: `$['P.O. Number']` (or
+                `$["P.O. Number"]`, `$.[P.O. Number]`). `$.P.O. Number` is read as a nested
+                path: it maps nothing and the record still succeeds. Spaces, hyphens and `#`
+                need no brackets (`$.Ship To Name`, `$.Tracking #`)
+              - Filter expressions such as `$.items[?(@.active)]` fail the record with
+                "Eval [?(expr)] prevented in JSONPath expression."
 
               ```json
               "extract": "$.customer.addresses[*]"  // Extracts all addresses
@@ -1873,6 +1899,12 @@ components:
               **Usage**
 
               The lookupName refers to a named lookup defined in the lookups array of the same resource.
+              On an HTTP import that is `http.lookups`: a `lookups` array sent only at the top level
+              is dropped on save. On an import, a name that matches no lookup fails every record
+              with "Unable to find lookup in mapping configs - <name>", and a key the lookup
+              doesn't hold follows the lookup's `allowFailures`: false fails the record; true, or
+              the field left out, lets the record succeed with the lookup's `default`, or without
+              the mapped field when there is none.
 
               ```json
               {
@@ -2210,6 +2242,11 @@ components:
                     The system creates special composite objects during processing to maintain
                     hierarchical relationships, allowing easy access to both the current array item
                     and its parent contexts.
+
+                    An iterating entry keeps the `[*]`: `$.line_items` without it yields one empty
+                    element per item, with no error. Child extracts drop the `[*]` but keep the
+                    array's path (`$.line_items.sku`); `$.line_items[*].sku` maps nothing, and an
+                    element-relative `$.sku` reads the record root instead of the element.
                   examples:
                     - $.items[*]
                     - $.order.lineItems[*]
@@ -2421,14 +2458,17 @@ components:
             type: string
             description: |
               **Purpose**
-              Required on every mapping entry. Controls whether the mapping is applied.
+              Controls whether the mapping is applied. Send it on every mapping entry.
 
               **Guidance**
               Only `Active` rows run. `Draft` and `Inactive` rows keep their
               configuration, are saved with minimal validation, and are skipped at
               runtime and in preview; a non-Active parent skips its whole subtree
-              whatever its children say. The API rejects a mapping missing this field
-              (validation error: "Mapping object must have status field present.").
+              whatever its children say. Imports (on save and in the mapper processor)
+              and API response mappings reject a row missing this field (validation
+              error: "Mapping object must have status field present."); a Tool's
+              output mapping saves and runs one, which is why `required` doesn't
+              list it.
             x-celigo-ai-guidance:
               - |-
                 Emit `"Active"` for mappings that should run; `"Draft"` is also
@@ -2799,8 +2839,8 @@ components:
               - Original value indicators: "{Original Value}", "No mapping found"
               - Neutral values: "Other", "N/A", "Miscellaneous"
 
-              If allowFailures is false and no default is specified, the flow will fail
-              when encountering unmapped values.
+              If allowFailures is false, a record whose value is unmapped fails and the default
+              is ignored.
             examples:
               - Unknown
               - Other
@@ -2821,7 +2861,11 @@ components:
               This field determines how the system handles source values that don't exist in the map:
 
               - true: Use the default value for missing mappings and continue processing
-              - false: Treat missing mappings as errors, failing the record
+              - false: Treat missing mappings as errors, failing the record (`lookup_error` for a
+                static map, `lookupcache_evaluation_failed` for a lookup cache)
+              - omitted or null: the record doesn't fail either. On an import a static lookup writes
+                its default if it has one, and a static or cache lookup without one leaves the
+                mapped field out of the output, with no error
 
               **Recommendation**
 
@@ -2835,11 +2879,14 @@ components:
               - All possible source values are known and controlled
               - Missing mappings indicate serious data problems that should be addressed
 
-              The best practice is typically to set allowFailures to true with a meaningful
-              default value, so flows remain operational while alerting you to missing mappings.
+              A default raises no error: records that miss go out with the default value and
+              nothing reports them. Use true only when that fallback is acceptable at the
+              destination, and set false explicitly when a missing value must stop the record.
             examples:
               - true
               - false
+            x-celigo-ai-guidance:
+              - 'Never leave this field out to mean "fail on a miss": on an import, an omitted or null value lets a missing key through without an error (with the default, or without the mapped field when there is none). Only an explicit false fails the record.'
     Transform:
       type: object
       description: |

package/dist/connection.yml

@@ -841,6 +841,11 @@ paths:
         `ftp.concurrencyLevel` and `ftp.targetConcurrencyLevel` (the latter is unset whenever
         `autoRecoverRateLimitErrors` is false). `connectionRole` is read-only here: a body carrying
         `mcpChild` is rejected.
+
+        An OAuth connection's `http.auth.oauth.authURI` and `tokenURI` can't change: a body that
+        changes either is rejected with 422 "Updating the value in tokenURI is not allowed for oauth
+        connections due to security reasons. Please contact celigo support." (and the same for
+        `authURI`), and nothing is saved. To move to new OAuth URLs, create a new connection.
       operationId: updateConnection
       tags:
         - Connections
@@ -1028,7 +1033,8 @@ paths:
         borrowed-from connection must exist in the account and may not itself borrow
         (422 `connection_borrows_from_another`), and a connection that others borrow
         from cannot start borrowing (422 `connection_borrowed_by_another`). A
-        connection naming itself is accepted, so check the id before sending it.
+        connection can't borrow from itself: naming its own id is rejected with 422 ("… a
+        connection cannot borrow concurrency from itself."), here and on `PUT`.
         Settings-only changes are recorded in the connection's audit log.
       operationId: patchConnection
       tags:
@@ -1134,6 +1140,15 @@ paths:
         Deletes a connection. The connection is soft-deleted and retained in the
         recycle bin for 30 days before permanent removal. Use
         `POST /v1/recycleBinTTL/connections/{_id}` to restore it during that window.
+
+        Rejected with 422 while anything still uses the connection; the message names each
+        blocker — every export or import on it, the flows they are steps of, and any connection
+        whose `_borrowConcurrencyFromConnectionId` points at it (clearing that field is enough).
+        Registration on an integration does not block the delete, and neither do exports, imports
+        or flows already in the recycle bin; but purging the connection early
+        (`DELETE /v1/recycleBinTTL/connections/{_id}`) is rejected with 422 "this document is
+        referenced by Export : …" while a binned export or import still points at it, so purge the
+        flows, then the exports and imports, then the connection.
       operationId: deleteConnection
       tags:
         - Connections
@@ -1161,7 +1176,7 @@ paths:
         - |-
           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.
+          exports, imports, or a borrowing connection is rejected with 422.
   /v1/connections/{_id}/ping:
     get:
       x-internal: false
@@ -1170,7 +1185,8 @@ paths:
         GET variant of the saved-connection ping — identical behavior to
         `POST /v1/connections/{_id}/ping`, with no request body to send. Runs the adaptor's ping
         routine against the connection identified by `_id` to verify its credentials and network
-        configuration still work; no data is read, written, or modified.
+        configuration still work; no data is read, written, or modified. An `http` connection with
+        no `http.ping` answers `{code: 200}` without sending any request.
 
         Inspect the response body, not the HTTP status, to determine the outcome: success and
         adaptor-level failures both return HTTP 200 — success is `{code: 200}`, failures are
@@ -1243,16 +1259,20 @@ paths:
           Behaves identically to POST /v1/connections/{_id}/ping and takes no request body — use
           whichever verb the client supports. Both verbs return HTTP 200 with {code: 200} on
           success and HTTP 200 with {errors: [...]} on adaptor-level failure, so inspect the body,
-          not the status code.
+          not the status code. On an `http` connection, {code: 200} shows reachability only once
+          `http.ping` is set: with no ping configured, nothing is sent and the answer is always
+          {code: 200}.
     post:
       x-internal: false
       summary: Ping an existing connection
       description: |-
         Runs the adaptor's ping routine against a saved connection to verify its credentials and
         network configuration still work; no data is read, written, or modified. The check is
-        adaptor-specific (HTTP runs the ping relativeURI or baseURI, RDBMS/JDBC open a driver
-        session, MCP issues a tools/list, NetSuite/Salesforce do a token or session validation).
-        The request body is optional and ignored.
+        adaptor-specific (HTTP sends the `http.ping` request, RDBMS/JDBC open a driver session,
+        MCP issues a tools/list, NetSuite/Salesforce do a token or session validation). An `http`
+        connection with no `http.ping` passes with `{code: 200}` without sending any request, so
+        the ping proves nothing about it until a ping is configured. The request body is optional
+        and ignored.
 
         Inspect the response body, not the HTTP status, to determine the outcome: success and
         adaptor-level failures both return HTTP 200 — success is `{code: 200}`, failures are
@@ -1362,6 +1382,10 @@ paths:
           - Test network connectivity
           - Verify permissions for basic operations
           - Return connection status and any error details
+
+          Exception: an `http` connection with no `http.ping` answers {code: 200} without sending
+          any request, so it proves nothing until a ping (ideally one that needs the connection's
+          credentials) is configured.
   /v1/connections/{_id}/proxy:
     post:
       x-internal: false
@@ -2452,6 +2476,9 @@ paths:
         The response is a plain-text stream (not JSON): each entry is a header line
         (`timestamp traceKey resourceType resourceId`) followed by a single-line JSON payload,
         entries separated by blank lines; paired request/response entries share a `traceKey`.
+        A response payload carries only `headers` and `body` — no HTTP status code, so judge a
+        failure by the body and by headers such as `Retry-After`. Connection tests are logged too:
+        resource type `ping` with an empty `resourceId`, and `isPing: true` in the request payload.
         Logs are shared across every flow using the connection (filter by `resourceId` client-side),
         and sensitive header values are redacted (`"Authorization": "********"`). For execution logs
         tied to a specific run, use `GET /v1/flows/{_id}/jobs/{_jobId}/logs` instead.
@@ -2916,6 +2943,13 @@ paths:
         `/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`.
+
+        The URL's `redirect_uri` is the account's Celigo callback
+        (`https://integrator.io/connection/oauth2callback` on North America), which the provider's
+        app registration must list. On an `http` connection the client comes from the iClient in
+        `http._iClientId`: with no iClient the request is rejected with 422 `unknown http authURI`,
+        and an iClient whose `oauth2.validDomainNames` lacks the authorization URL's registrable
+        domain is rejected as well (see the 422 examples).
       parameters:
         - name: _id
           in: path
@@ -2959,9 +2993,11 @@ paths:
           $ref: '#/components/responses/404-not-found'
         '422':
           description: |-
-            Connection exists but is not configured for OAuth — e.g. an FTP, S3, or plain-auth
-            HTTP connection. The server fails the handshake pre-check because the connection has
-            no `authURI` in its config.
+            The handshake pre-check failed: the connection has no `authURI` in its config (an FTP,
+            S3, plain-auth or client-credentials HTTP connection — nothing to authorize in a
+            browser); an `http` connection has no iClient (`unknown http authURI: "<registrable
+            domain>"`); or its iClient's `oauth2.validDomainNames` doesn't list the authorization
+            URL's registrable domain.
           content:
             application/json:
               schema:
@@ -2974,6 +3010,16 @@ paths:
                       - code: missing_required_field
                         message: 'Expected field: authURI in the Connection to be present.'
                         source: connector
+                noIClient:
+                  summary: HTTP connection with no iClient
+                  value:
+                    errors:
+                      - message: 'unknown http authURI: "example.com"'
+                domainNotListed:
+                  summary: The iClient's validDomainNames lacks the authorization URL's domain
+                  value:
+                    errors:
+                      - message: The domain of request url should be present in iClient.oauth2.validDomainNames
   /v1/connections/{_id}/dependencies:
     get:
       x-internal: false
@@ -4088,7 +4134,7 @@ components:
                 connection's traffic counts against the referenced connection's limit instead of its own,
                 and its own concurrency and auto-recovery settings have no effect. One level only: the
                 referenced connection may not itself borrow, and a connection that others borrow from
-                cannot start borrowing.
+                cannot start borrowing. A connection cannot reference itself (422).
               examples:
                 - 615dfa0742763671275b70ab
               x-celigo-ai-guidance:
@@ -4125,16 +4171,21 @@ components:
               type: boolean
               description: |-
                 When true, the connection has been taken offline and is skipped during flow execution.
-                The platform tests the connection after a create or `PUT` and updates this shortly
-                afterwards (the audit log records a `system` change; `lastModified` doesn't move), so
-                read it again a few seconds after the write.
+                It is set by the connection test a create or `PUT` runs: the result arrives in the
+                write's response or, when the target is slow to answer, shortly afterwards (the audit
+                log records a `system` change; `lastModified` doesn't move), so read it again a few
+                seconds after the write. On an `http` connection the write runs the test only when
+                `http.ping` is configured, and an `http` connection that was never tested has no
+                `offline` key.
               readOnly: true
             needsAuthorization:
               type: boolean
               readOnly: true
               description: |-
                 OAuth handshake state. Celigo's OAuth callback sets it to `false` once the user consents
-                and the tokens are stored (see `GET /v1/connection/{_id}/oauth2`).
+                and the tokens are stored (see `GET /v1/connection/{_id}/oauth2`). A connection that
+                was never authorized usually has no `needsAuthorization` key, so its absence does not
+                mean the connection is authorized.
             _sourceId:
               type: string
               format: objectId
@@ -5109,15 +5160,18 @@ components:
         clientId:
           type: string
           description: |
-            OAuth client ID (application ID) registered with the API provider.
-            Required for all OAuth 2.0 grant types.
+            OAuth client ID (application ID) registered with the API provider. An `http`
+            connection takes the app from a `custom_oauth2` iClient referenced by `http._iClientId`
+            (an `mcp` connection from `mcp.http._iClientId`) and doesn't store this field: a create
+            that sends `clientId` and `clientSecret` here answers 201 without either (and stores
+            `useIClientFields: true` unless `false` is sent).
           examples:
             - 0oa1b2c3d4EXAMPLE5
         clientSecret:
           type: string
           description: |
-            OAuth client secret (encrypted at rest).
-            Required for "authorizecode" and "clientcredentials" grant types.
+            OAuth client secret (encrypted at rest). Not stored on an `http` connection: the secret
+            belongs on the iClient (see `clientId`).
           writeOnly: true
           examples:
             - cs_abc123EXAMPLE456secret
@@ -5333,9 +5387,11 @@ components:
           - "authorizecode" — Authorization Code flow (browser-based user consent).
             Requires authURI, tokenURI, and user authorization via browser.
           - "clientcredentials" — Client Credentials flow (server-to-server, no user).
-            Requires tokenURI, clientId, clientSecret.
+            Requires tokenURI.
           - "password" — Resource Owner Password flow (username/password exchange).
-            Requires tokenURI, username, password, clientId, clientSecret.
+            Requires tokenURI, username, password.
+          - On an `http` connection the client ID and secret are never stored here: a
+            `custom_oauth2` iClient referenced by `http._iClientId` supplies them.
     JWT:
       type: object
       description: |-
@@ -9560,7 +9616,7 @@ components:
             connection's traffic counts against the referenced connection's limit instead of its own,
             and its own concurrency and auto-recovery settings have no effect. One level only: the
             referenced connection may not itself borrow, and a connection that others borrow from
-            cannot start borrowing.
+            cannot start borrowing. A connection cannot reference itself (422).
           examples:
             - 615dfa0742763671275b70ab
           x-celigo-ai-guidance: