@celigo/api-specs 0.2.153 → 0.2.155

package/dist/asynchelper.yml

@@ -505,9 +505,8 @@ components:
             - For regular fields: Set to the exact property name (e.g., "firstName", "price", "isActive")
             - For object fields: Set to the object property name, then add child mappings in the 'mappings' array
             - For array fields: Set to the array property name, then configure 'buildArrayHelper'
-            - Two structural blanks: the inner array item of an array of arrays (it has no field name),
-              and the single top-level `objectarray` item of a `rows [ ]` mapping (the array output
-              structure — see the array's description). A child-bearing wrapper and a source-only row that
+            - One structural blank: the single top-level `objectarray` item of a `rows [ ]` mapping (the
+              array output structure — see the array's description). A child-bearing wrapper and a source-only row that
               already exist in a saved document also stay unnamed when the tree is re-sent — filling in a
               name changes the output; it does not complete the row
 
@@ -524,7 +523,9 @@ components:
             }
             ```
 
-            When parsing existing mappings, an empty `generate` inside a parent array is an inner array; an
+            When parsing existing mappings, an empty `generate` on a row inside an `arrayarray` row's
+            `buildArrayHelper` entry is that row's inner array (`arrayarray` fails at run time; see
+            `dataType`); other unnamed rows are the wrappers and source-only rows described above; an
             empty `generate` on the ONLY top-level item, with `dataType: objectarray`, is the `rows [ ]` JSON
             structure — array output, bound as `rows` in templates — and is intentional, not a missing name.
           examples:
@@ -558,17 +559,25 @@ components:
             - `numberarray`: Array of numbers
             - `booleanarray`: Array of booleans
             - `objectarray`: Array of objects (most common array type)
-            - `arrayarray`: Array of arrays (for matrix/table structures)
 
-            Array dataTypes can be populated three ways: pass a source array
-            through unchanged via a JSONPath `extract` alone (when the source is
-            already an array of the right shape), construct/iterate via
-            `buildArrayHelper`, or set a constant with `hardCodedValue`.
+            `arrayarray` is not a type the mapper recognizes: a save accepts it, but every record
+            then fails with `Destination datatype is a required field.` Build an array of arrays
+            in a script hook instead.
+
+            Array dataTypes are populated two ways: construct or iterate through
+            `buildArrayHelper` entries, or set a constant with `hardCodedValue`. The
+            row's own `extract` is never read on an array type: a primitive-array row
+            that has only an `extract` (JSONPath, Handlebars or a literal) yields
+            nothing, with no error, and an `objectarray` row without `buildArrayHelper`
+            or `hardCodedValue` is refused with 422 ("buildArrayHelper" or
+            "hardCodedValue" must be present for object array datatype.). To copy a
+            source array through unchanged, use one entry that iterates it
+            (`buildArrayHelper: [{"extract": "$.items[*]"}]`).
 
             IMPORTANT: The dataType controls which additional fields are relevant:
             - For date-like string fields: extractDateFormat, generateDateFormat, etc. become relevant
             - For object types: 'mappings' array becomes relevant
-            - For array types: a JSONPath `extract` alone, `buildArrayHelper`, or `hardCodedValue` (see above)
+            - For array types: `buildArrayHelper` or `hardCodedValue` (see above)
 
             When analyzing existing mappings or generating new ones, always check dataType first
             to understand what additional fields should be present.
@@ -587,7 +596,6 @@ components:
             - numberarray
             - booleanarray
             - objectarray
-            - arrayarray
           x-enumDescriptions:
             string: Text values; converts other types to their string representation.
             number: Numeric values; attempts conversion from strings.
@@ -597,7 +605,6 @@ components:
             numberarray: Array of numeric values.
             booleanarray: Array of boolean values.
             objectarray: Array of objects, the most common array type.
-            arrayarray: Array of arrays, used for matrix or table structures.
           examples:
             - string
             - number
@@ -640,9 +647,10 @@ components:
             - Valid on scalars and on `object` rows, where the rendered output must
               parse into an object. On an array row the template goes in a
               `buildArrayHelper` entry instead: on an `objectarray` row's own
-              `extract` it is refused with 422 ("buildArrayHelper" must be present
-              for object array datatype), and on a primitive-array row's own
-              `extract` it renders null without an error
+              `extract` it is refused with 422 ("buildArrayHelper" or "hardCodedValue"
+              must be present for object array datatype.), and on a primitive-array
+              row's own `extract` it yields nothing (the field is left out) without an
+              error
 
             ```json
             "extract": "{{record.price}} {{record.currency}}"  // Combines two fields
@@ -784,8 +792,10 @@ components:
             Explicit JSON `null` is itself a valid fallback: the destination field is written as
             JSON null when the extract yields nothing (the Mapper UI's "Use null as default value"
             action). Omitting the key entirely means no fallback — the field is left out of the
-            output when the extract is empty (the UI's "Do nothing" action). Failing the record
-            instead is `conditional.when: fail_record_when_empty`, which excludes a default.
+            output when the extract is missing or an empty string (the UI's "Do nothing" action),
+            while a null source is still written as null unless `conditional.when` is
+            `extract_not_empty`. Failing the record instead is `conditional.when:
+            fail_record_when_empty`, which excludes a default.
           x-celigo-ai-guidance:
             - |-
               `"default": null` and `"default": ""` are distinct saved values, not
@@ -793,11 +803,14 @@ components:
               empty string renders it as `""` when the extract yields nothing.
               Preserve them verbatim when editing or migrating a mapping — dropping
               the key changes runtime behavior from "use null/empty string as
-              default value" to "do nothing" (field omitted from the output).
+              default value" to "do nothing" (a missing or `""` source is left out
+              of the output, while a null source is written as null unless
+              `conditional.when` is `extract_not_empty`).
             - |-
               The four "Action to take if source field has no value" choices map to:
-              do nothing → no `default` key (optionally `conditional.when:
-              extract_not_empty`); use null → `"default": null`; use empty string or
+              do nothing → no `default` key (add `conditional.when:
+              extract_not_empty` to leave a null source out too; without it a null
+              source is written as null); use null → `"default": null`; use empty string or
               a custom value → `"default": "<value>"`; cause the record to fail →
               `conditional.when: fail_record_when_empty` with no `default` key.
           examples:
@@ -1012,8 +1025,7 @@ components:
 
             **When to Use**
             - REQUIRED when dataType ends with "array" (stringarray, objectarray, etc.), unless the
-              row passes a source array through with a JSONPath `extract` alone or sets
-              `hardCodedValue`
+              row sets `hardCodedValue`: an array row's own `extract` is never read (see `dataType`)
             - Each entry in this array contributes elements to the output array
             - Multiple entries allow combining data from different input arrays
 
@@ -1097,28 +1109,10 @@ components:
             }
             ```
 
-            **For Arrays of Arrays (arrayarray)**
-            - Similar to objectarray, but inner arrays have empty 'generate' fields
-            - Used for matrix/table structures
-            ```json
-            {
-              "generate": "matrix",
-              "dataType": "arrayarray",
-              "buildArrayHelper": [
-                {
-                  "extract": "$.rows[*]",  // For each row in the rows array
-                  "mappings": [
-                    {
-                      "dataType": "numberarray",  // Note: No generate field for inner arrays
-                      "buildArrayHelper": [
-                        {"extract": "$.rows.columns[*]"}  // Notice: "rows" is singular in the composite object
-                      ]
-                    }
-                  ]
-                }
-              ]
-            }
-            ```
+            **Arrays of Arrays**
+            - The mapper has no working type for them: `arrayarray` saves, but every record
+              fails with `Destination datatype is a required field.` Build an array of arrays
+              in a script hook instead.
 
             **Important details**
 
@@ -1536,8 +1530,8 @@ components:
         nature is essential for building effective mappings:
 
         1. The schema is self-referential by design - a mapping can contain nested mappings of the same structure
-        2. Complex data structures (nested objects, arrays of objects, arrays of arrays of objects) are ALL
-           handled through this recursive pattern
+        2. Complex data structures (nested objects and arrays of objects, to any depth) are ALL
+           handled through this recursive pattern; an array of arrays is not (build one in a script hook)
         3. Each mapping handles one level of the data structure; deeper levels are handled by nested mappings
 
         When generating mappings programmatically:
@@ -1591,9 +1585,8 @@ components:
               - For regular fields: Set to the exact property name (e.g., "firstName", "price", "isActive")
               - For object fields: Set to the object property name, then add child mappings in the 'mappings' array
               - For array fields: Set to the array property name, then configure 'buildArrayHelper'
-              - Two structural blanks: the inner array item of an array of arrays (it has no field name),
-                and the single top-level `objectarray` item of a `rows [ ]` mapping (the array output
-                structure — see the array's description). A child-bearing wrapper and a source-only row that
+              - One structural blank: the single top-level `objectarray` item of a `rows [ ]` mapping (the
+                array output structure — see the array's description). A child-bearing wrapper and a source-only row that
                 already exist in a saved document also stay unnamed when the tree is re-sent — filling in a
                 name changes the output; it does not complete the row
 
@@ -1610,7 +1603,9 @@ components:
               }
               ```
 
-              When parsing existing mappings, an empty `generate` inside a parent array is an inner array; an
+              When parsing existing mappings, an empty `generate` on a row inside an `arrayarray` row's
+              `buildArrayHelper` entry is that row's inner array (`arrayarray` fails at run time; see
+              `dataType`); other unnamed rows are the wrappers and source-only rows described above; an
               empty `generate` on the ONLY top-level item, with `dataType: objectarray`, is the `rows [ ]` JSON
               structure — array output, bound as `rows` in templates — and is intentional, not a missing name.
             examples:
@@ -1644,17 +1639,25 @@ components:
               - `numberarray`: Array of numbers
               - `booleanarray`: Array of booleans
               - `objectarray`: Array of objects (most common array type)
-              - `arrayarray`: Array of arrays (for matrix/table structures)
 
-              Array dataTypes can be populated three ways: pass a source array
-              through unchanged via a JSONPath `extract` alone (when the source is
-              already an array of the right shape), construct/iterate via
-              `buildArrayHelper`, or set a constant with `hardCodedValue`.
+              `arrayarray` is not a type the mapper recognizes: a save accepts it, but every record
+              then fails with `Destination datatype is a required field.` Build an array of arrays
+              in a script hook instead.
+
+              Array dataTypes are populated two ways: construct or iterate through
+              `buildArrayHelper` entries, or set a constant with `hardCodedValue`. The
+              row's own `extract` is never read on an array type: a primitive-array row
+              that has only an `extract` (JSONPath, Handlebars or a literal) yields
+              nothing, with no error, and an `objectarray` row without `buildArrayHelper`
+              or `hardCodedValue` is refused with 422 ("buildArrayHelper" or
+              "hardCodedValue" must be present for object array datatype.). To copy a
+              source array through unchanged, use one entry that iterates it
+              (`buildArrayHelper: [{"extract": "$.items[*]"}]`).
 
               IMPORTANT: The dataType controls which additional fields are relevant:
               - For date-like string fields: extractDateFormat, generateDateFormat, etc. become relevant
               - For object types: 'mappings' array becomes relevant
-              - For array types: a JSONPath `extract` alone, `buildArrayHelper`, or `hardCodedValue` (see above)
+              - For array types: `buildArrayHelper` or `hardCodedValue` (see above)
 
               When analyzing existing mappings or generating new ones, always check dataType first
               to understand what additional fields should be present.
@@ -1673,7 +1676,6 @@ components:
               - numberarray
               - booleanarray
               - objectarray
-              - arrayarray
             x-enumDescriptions:
               string: Text values; converts other types to their string representation.
               number: Numeric values; attempts conversion from strings.
@@ -1683,7 +1685,6 @@ components:
               numberarray: Array of numeric values.
               booleanarray: Array of boolean values.
               objectarray: Array of objects, the most common array type.
-              arrayarray: Array of arrays, used for matrix or table structures.
             examples:
               - string
               - number
@@ -1726,9 +1727,10 @@ components:
               - Valid on scalars and on `object` rows, where the rendered output must
                 parse into an object. On an array row the template goes in a
                 `buildArrayHelper` entry instead: on an `objectarray` row's own
-                `extract` it is refused with 422 ("buildArrayHelper" must be present
-                for object array datatype), and on a primitive-array row's own
-                `extract` it renders null without an error
+                `extract` it is refused with 422 ("buildArrayHelper" or "hardCodedValue"
+                must be present for object array datatype.), and on a primitive-array
+                row's own `extract` it yields nothing (the field is left out) without an
+                error
 
               ```json
               "extract": "{{record.price}} {{record.currency}}"  // Combines two fields
@@ -1870,8 +1872,10 @@ components:
               Explicit JSON `null` is itself a valid fallback: the destination field is written as
               JSON null when the extract yields nothing (the Mapper UI's "Use null as default value"
               action). Omitting the key entirely means no fallback — the field is left out of the
-              output when the extract is empty (the UI's "Do nothing" action). Failing the record
-              instead is `conditional.when: fail_record_when_empty`, which excludes a default.
+              output when the extract is missing or an empty string (the UI's "Do nothing" action),
+              while a null source is still written as null unless `conditional.when` is
+              `extract_not_empty`. Failing the record instead is `conditional.when:
+              fail_record_when_empty`, which excludes a default.
             x-celigo-ai-guidance:
               - |-
                 `"default": null` and `"default": ""` are distinct saved values, not
@@ -1879,11 +1883,14 @@ components:
                 empty string renders it as `""` when the extract yields nothing.
                 Preserve them verbatim when editing or migrating a mapping — dropping
                 the key changes runtime behavior from "use null/empty string as
-                default value" to "do nothing" (field omitted from the output).
+                default value" to "do nothing" (a missing or `""` source is left out
+                of the output, while a null source is written as null unless
+                `conditional.when` is `extract_not_empty`).
               - |-
                 The four "Action to take if source field has no value" choices map to:
-                do nothing → no `default` key (optionally `conditional.when:
-                extract_not_empty`); use null → `"default": null`; use empty string or
+                do nothing → no `default` key (add `conditional.when:
+                extract_not_empty` to leave a null source out too; without it a null
+                source is written as null); use null → `"default": null`; use empty string or
                 a custom value → `"default": "<value>"`; cause the record to fail →
                 `conditional.when: fail_record_when_empty` with no `default` key.
             examples:
@@ -2098,8 +2105,7 @@ components:
 
               **When to Use**
               - REQUIRED when dataType ends with "array" (stringarray, objectarray, etc.), unless the
-                row passes a source array through with a JSONPath `extract` alone or sets
-                `hardCodedValue`
+                row sets `hardCodedValue`: an array row's own `extract` is never read (see `dataType`)
               - Each entry in this array contributes elements to the output array
               - Multiple entries allow combining data from different input arrays
 
@@ -2183,28 +2189,10 @@ components:
               }
               ```
 
-              **For Arrays of Arrays (arrayarray)**
-              - Similar to objectarray, but inner arrays have empty 'generate' fields
-              - Used for matrix/table structures
-              ```json
-              {
-                "generate": "matrix",
-                "dataType": "arrayarray",
-                "buildArrayHelper": [
-                  {
-                    "extract": "$.rows[*]",  // For each row in the rows array
-                    "mappings": [
-                      {
-                        "dataType": "numberarray",  // Note: No generate field for inner arrays
-                        "buildArrayHelper": [
-                          {"extract": "$.rows.columns[*]"}  // Notice: "rows" is singular in the composite object
-                        ]
-                      }
-                    ]
-                  }
-                ]
-              }
-              ```
+              **Arrays of Arrays**
+              - The mapper has no working type for them: `arrayarray` saves, but every record
+                fails with `Destination datatype is a required field.` Build an array of arrays
+                in a script hook instead.
 
               **Important details**
 
@@ -2848,7 +2836,7 @@ components:
               - Unmapped Value
               - '{Original Value}'
             x-celigo-ai-guidance:
-              - 'Omit this field entirely when no fallback value is intended. The API rejects an empty string with [invalid_field] Invalid value '''' for field ''default'' — emitting default: "" to mean "no default" fails validation; leaving the key out is the valid spelling of that intent.'
+              - 'Omit this field entirely when no fallback value is intended: a miss the lookup lets through then leaves the mapped field out, and with `allowFailures: false` a miss fails the record whatever the default. An empty string is a value, not "no default" — the save accepts `default: ""`, and an allowed miss writes `""`.'
           allowFailures:
             type:
               - boolean
@@ -3007,6 +2995,11 @@ components:
                   dropped fields. Either map every field downstream logic
                   needs forward, or author Transform 2.0 with
                   ``mode: "modify"`` instead.
+                - |-
+                  An import's ``responseTransform`` is the exception: it accepts
+                  version ``"1"`` only (``"2"`` is refused with 422, verified live
+                  2026-10-21), so there, map every response field that response
+                  mapping needs.
               items:
                 type: array
                 items:

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: