@celigo/api-specs 0.2.69 → 0.2.71

package/dist/api.yml

@@ -144,7 +144,9 @@ paths:
       description: |-
         Creates a new API. For `script` mode, include `script._scriptId` and `script.function` (the
         server also copies these to the top level in the response). For `builder` mode,
-        `builder.request` is required (at minimum `relativeURI` and `method`).
+        `builder.request` can be added later — an API created without it has no route until
+        `relativeURI` and `method` are set — but when it is present it must carry both, or the
+        request fails with 422 `invalid_api_builder_request`.
 
         Builder-mode APIs are created with `logging: {"mode": "basic"}` when the account license
         has logging enabled -- the request body cannot override this (`logging` is ignored on POST
@@ -666,7 +668,13 @@ paths:
       summary: Update the grouping for one or more APIs
       description: |-
         Assigns or removes an API grouping for the specified API resources. Pass
-        `_apiGroupingId: null` to ungroup. Nonexistent API IDs are silently accepted.
+        `_apiGroupingId: null` or omit it to ungroup. Nonexistent API IDs are silently accepted.
+
+        Every API in `_apiIds` must belong to the same integration, and the grouping must be
+        one of that integration's `apiGroupings`. Each API is re-saved through full validation,
+        so an API that cannot be saved as it stands (for example a builder API whose response
+        router is not configured yet) fails the request with 400 `apigrouping_update_error`;
+        regroup such an API with a full `PUT /v1/apis/{_id}` instead.
       requestBody:
         required: true
         content:
@@ -704,7 +712,34 @@ paths:
         '204':
           description: API grouping updated successfully (no body returned).
         '400':
-          $ref: '#/components/responses/400-bad-request'
+          description: |-
+            The request was rejected: the APIs span more than one integration
+            (`invalid_request`), or one API could not be re-saved with the new grouping
+            (`apigrouping_update_error` — the grouping belongs to another integration, or the
+            API fails its own validation).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                differentIntegrations:
+                  summary: APIs belong to different integrations
+                  value:
+                    errors:
+                      - code: invalid_request
+                        message: Unable to update apis for apigrouping, since apis belongs to different integrations.
+                groupingNotInIntegration:
+                  summary: Grouping belongs to another integration
+                  value:
+                    errors:
+                      - code: apigrouping_update_error
+                        message: 'Failed to update api grouping for api: Get Customer. Error: API grouping does not belong to Integration: 6a429af50547257e3301246c.'
+                apiFailsValidation:
+                  summary: API cannot be re-saved as it stands
+                  value:
+                    errors:
+                      - code: apigrouping_update_error
+                        message: 'Failed to update api grouping for api: Get Customer. Error: Response router id must be "apiRouter"..'
         '401':
           $ref: '#/components/responses/401-unauthorized'
   /v1/apis/{_id}/logs:
@@ -2119,7 +2154,8 @@ paths:
         combination of `version`, `method`, and `relativeURI` must be unique. Reusing all
         three returns a 422 `clone_api_already_exists`. Pass `_integrationId` to create the
         clone inside an integration — when omitted, the clone is created standalone rather
-        than inheriting the source API's integration.
+        than inheriting the source API's integration. Add `_apiGroupingId` to file the clone
+        under one of that integration's `apiGroupings`.
 
         Only **builder-type** APIs can be cloned — cloning any other API type returns a 400
         `clone_not_supported`.
@@ -2168,12 +2204,32 @@ paths:
                     standalone — it does not inherit the source API's integration.
                   examples:
                     - 6a429af50547257e3301246c
+                _apiGroupingId:
+                  type:
+                    - string
+                    - 'null'
+                  format: objectId
+                  description: |-
+                    Grouping inside the target integration that the clone is filed under; `null`
+                    or omitted leaves it ungrouped. Honored only together with `_integrationId` —
+                    sent without it, the clone is created standalone and the grouping is dropped
+                    silently. A grouping that belongs to a different integration fails the clone
+                    with 422 `apigrouping_not_belong` and nothing is created.
+                  examples:
+                    - 60a1b2c3d4e5f60012345678
             examples:
               default:
                 summary: Clone to a new version
                 value:
                   version: v2
                   name: IDP (v2)
+              intoGroup:
+                summary: Clone into an integration's API grouping
+                value:
+                  version: v2
+                  name: IDP (v2)
+                  _integrationId: 6a429af50547257e3301246c
+                  _apiGroupingId: 60a1b2c3d4e5f60012345678
       responses:
         '201':
           description: |-
@@ -2234,8 +2290,9 @@ paths:
           $ref: '#/components/responses/404-not-found'
         '422':
           description: |-
-            An API with the same `version`, `method`, and `relativeURI` already exists. Clone
-            with a different `version` (or change the method/URI) to create a distinct API.
+            An API with the same `version`, `method`, and `relativeURI` already exists — clone
+            with a different `version` (or change the method/URI) to create a distinct API — or
+            `_apiGroupingId` is not one of the target integration's `apiGroupings`.
           content:
             application/json:
               schema:
@@ -2246,6 +2303,13 @@ paths:
                     errors:
                       - code: clone_api_already_exists
                         message: The clone API already exists with the same version, method and relative uri.
+                groupingNotInIntegration:
+                  summary: Grouping belongs to a different integration
+                  value:
+                    errors:
+                      - field: _apiGroupingId
+                        code: apigrouping_not_belong
+                        message: 'Failed to create Api for _id "68ae4264b5f755d2dd3796b4" due to: API grouping does not belong to Integration: 6a429af50547257e3301246c'
   /v1/apis/{_id}/clone/validate:
     post:
       x-internal: false
@@ -3332,6 +3396,15 @@ components:
             API. On reads the field is omitted when unset, never `null`.
           examples:
             - 60a1b2c3d4e5f60012345678
+          x-celigo-ai-guidance:
+            - |-
+              The id must be one of the `apiGroupings` of the integration named by _integrationId
+              in the same write; any other id fails with 422 `apigrouping_not_belong` — including
+              a PUT that changes _integrationId but keeps the previous grouping. When moving an
+              API, send the target integration's grouping or `null` (Unassigned).
+            - |-
+              `PATCH /v1/apis/{_id}` rejects `/_apiGroupingId` (422, not a whitelisted property);
+              regroup with a full PUT or with `PUT /v1/apis/updateApiGrouping`.
         description:
           type: string
           description: Optional description of the API's purpose.
@@ -3678,11 +3751,13 @@ components:
       description: |-
         Request body for creating or updating an API.
 
-        For builder-mode APIs, populate the `builder` object (at minimum
-        `builder.request.relativeURI` and `builder.request.method`); the `script`
-        field is ignored. For script-mode APIs, populate `script` with `_scriptId`
-        and `function`; the `builder` field is ignored. On PUT, send the complete
-        object — omitted fields revert to defaults.
+        For builder-mode APIs, populate the `builder` object; the `script` field is
+        ignored. `builder.request` can be omitted on create — the API has no route
+        until `relativeURI` and `method` are set — but when it is present it must
+        carry both, or the write fails with 422 `invalid_api_builder_request`. For
+        script-mode APIs, populate `script` with `_scriptId` and `function`; the
+        `builder` field is ignored. On PUT, send the complete object — omitted
+        fields revert to defaults.
 
         Set `type` explicitly to `builder` or `script`. The server infers `script`
         when `type` is omitted, but new APIs must declare it.
@@ -4856,12 +4931,24 @@ components:
               type: string
               format: objectId
               x-celigo-refModel: connections
-              description: |
-                Reference to another connection to share concurrency limits with.
-                When set, this connection's concurrency is counted against the referenced
-                connection's limit instead of maintaining its own.
+              description: |-
+                Reference to another connection to share concurrency limits with. When set, this
+                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.
               examples:
                 - 615dfa0742763671275b70ab
+              x-celigo-ai-guidance:
+                - |-
+                  Set this when several connections target one external account whose API enforces a
+                  single account-wide concurrency limit (for example one NetSuite account): put the limit
+                  on one parent connection and point the others here, so their combined traffic can never
+                  exceed it.
+                - |-
+                  A borrower drains through the parent's queue as well as its ceiling, so a high-volume
+                  borrower competes with the parent's own flows — settle the priority split before
+                  choosing who borrows from whom.
             debugDate:
               type: string
               format: date-time
@@ -5239,21 +5326,52 @@ components:
             Required for some authentication configurations to identify the calling application.
         concurrencyLevel:
           type: integer
-          description: |
-            General concurrency level for this connection. Controls the overall
-            maximum concurrent requests across all operation types.
-            Values above the account's licensed maximum (25 standard, 50 with an Environments license) are silently clamped down.
+          description: |-
+            Maximum number of requests this connection sends to NetSuite in parallel, across SOAP,
+            REST and RESTlet calls. Values above the integrator.io license ceiling (25 standard, 50
+            with an Environments license) are stored as that ceiling. NetSuite separately enforces one
+            concurrency limit per NetSuite account that every caller of its SOAP, REST and RESTlet
+            APIs shares — all integrator.io connections to that account and every other client
+            calling those APIs from outside integrator.io (other integrations, third-party tools).
           minimum: 1
           maximum: 50
           default: 5
+          x-celigo-ai-guidance:
+            - |-
+              Before raising this connection's ceiling — `targetConcurrencyLevel` while
+              `autoRecoverRateLimitErrors` is on (the default; a PUT of `concurrencyLevel` then
+              changes nothing), `concurrencyLevel` only while it is off — total the ceilings of every
+              connection that targets the same NetSuite `account` and `environment` (a connection
+              that borrows counts under its parent) and keep that total, plus whatever calls the
+              account's APIs from outside integrator.io, within the NetSuite account limit; a value
+              that fits this connection alone can still push the whole account over.
+            - |-
+              The NetSuite limit is the service-tier base (Standard 5, Premium 15, Enterprise and
+              Ultimate 20; legacy tiers 5–20) plus 10 per SuiteCloud Plus license; a sandbox matches
+              its production account. Development and partner accounts are fixed at 5 and do not
+              scale with licenses. NetSuite shows the limit at Setup > Integration > Integration
+              Management > Integration Governance; integrator.io cannot read it — ask for the number
+              rather than assuming headroom.
+            - |-
+              Over the limit, NetSuite rejects requests from every caller of that account at once,
+              not only this connection's — SOAP: `ExceededConcurrentRequestLimitFault` /
+              `WS_REQUEST_BLOCKED`; REST web services: HTTP 429; RESTlets: HTTP 400
+              `SSS_REQUEST_LIMIT_EXCEEDED`. To run several connections against one NetSuite account,
+              put the limit on one parent and point the others at it with
+              `_borrowConcurrencyFromConnectionId`; otherwise raise in small steps.
         targetConcurrencyLevel:
           type: integer
-          description: |
+          description: |-
             Target concurrency level for auto-scaling. The system adjusts concurrency
             between 1 and this value based on rate limit and governance feedback.
           minimum: 1
           maximum: 50
           default: 5
+          x-celigo-ai-guidance:
+            - |-
+              With `autoRecoverRateLimitErrors` on, this is the level the connection climbs back to
+              after a recovery, so it — not `concurrencyLevel` — is the value that must fit the shared
+              NetSuite account budget described on `concurrencyLevel`.
         _iClientId:
           type: string
           format: objectId

package/dist/connection.yml

@@ -3164,12 +3164,24 @@ components:
               type: string
               format: objectId
               x-celigo-refModel: connections
-              description: |
-                Reference to another connection to share concurrency limits with.
-                When set, this connection's concurrency is counted against the referenced
-                connection's limit instead of maintaining its own.
+              description: |-
+                Reference to another connection to share concurrency limits with. When set, this
+                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.
               examples:
                 - 615dfa0742763671275b70ab
+              x-celigo-ai-guidance:
+                - |-
+                  Set this when several connections target one external account whose API enforces a
+                  single account-wide concurrency limit (for example one NetSuite account): put the limit
+                  on one parent connection and point the others here, so their combined traffic can never
+                  exceed it.
+                - |-
+                  A borrower drains through the parent's queue as well as its ceiling, so a high-volume
+                  borrower competes with the parent's own flows — settle the priority split before
+                  choosing who borrows from whom.
             debugDate:
               type: string
               format: date-time
@@ -3547,21 +3559,52 @@ components:
             Required for some authentication configurations to identify the calling application.
         concurrencyLevel:
           type: integer
-          description: |
-            General concurrency level for this connection. Controls the overall
-            maximum concurrent requests across all operation types.
-            Values above the account's licensed maximum (25 standard, 50 with an Environments license) are silently clamped down.
+          description: |-
+            Maximum number of requests this connection sends to NetSuite in parallel, across SOAP,
+            REST and RESTlet calls. Values above the integrator.io license ceiling (25 standard, 50
+            with an Environments license) are stored as that ceiling. NetSuite separately enforces one
+            concurrency limit per NetSuite account that every caller of its SOAP, REST and RESTlet
+            APIs shares — all integrator.io connections to that account and every other client
+            calling those APIs from outside integrator.io (other integrations, third-party tools).
           minimum: 1
           maximum: 50
           default: 5
+          x-celigo-ai-guidance:
+            - |-
+              Before raising this connection's ceiling — `targetConcurrencyLevel` while
+              `autoRecoverRateLimitErrors` is on (the default; a PUT of `concurrencyLevel` then
+              changes nothing), `concurrencyLevel` only while it is off — total the ceilings of every
+              connection that targets the same NetSuite `account` and `environment` (a connection
+              that borrows counts under its parent) and keep that total, plus whatever calls the
+              account's APIs from outside integrator.io, within the NetSuite account limit; a value
+              that fits this connection alone can still push the whole account over.
+            - |-
+              The NetSuite limit is the service-tier base (Standard 5, Premium 15, Enterprise and
+              Ultimate 20; legacy tiers 5–20) plus 10 per SuiteCloud Plus license; a sandbox matches
+              its production account. Development and partner accounts are fixed at 5 and do not
+              scale with licenses. NetSuite shows the limit at Setup > Integration > Integration
+              Management > Integration Governance; integrator.io cannot read it — ask for the number
+              rather than assuming headroom.
+            - |-
+              Over the limit, NetSuite rejects requests from every caller of that account at once,
+              not only this connection's — SOAP: `ExceededConcurrentRequestLimitFault` /
+              `WS_REQUEST_BLOCKED`; REST web services: HTTP 429; RESTlets: HTTP 400
+              `SSS_REQUEST_LIMIT_EXCEEDED`. To run several connections against one NetSuite account,
+              put the limit on one parent and point the others at it with
+              `_borrowConcurrencyFromConnectionId`; otherwise raise in small steps.
         targetConcurrencyLevel:
           type: integer
-          description: |
+          description: |-
             Target concurrency level for auto-scaling. The system adjusts concurrency
             between 1 and this value based on rate limit and governance feedback.
           minimum: 1
           maximum: 50
           default: 5
+          x-celigo-ai-guidance:
+            - |-
+              With `autoRecoverRateLimitErrors` on, this is the level the connection climbs back to
+              after a recovery, so it — not `concurrencyLevel` — is the value that must fit the shared
+              NetSuite account budget described on `concurrencyLevel`.
         _iClientId:
           type: string
           format: objectId
@@ -8266,6 +8309,16 @@ components:
             cannot start borrowing.
           examples:
             - 615dfa0742763671275b70ab
+          x-celigo-ai-guidance:
+            - |-
+              Set this when several connections target one external account whose API enforces a
+              single account-wide concurrency limit (for example one NetSuite account): put the limit
+              on one parent connection and point the others here, so their combined traffic can never
+              exceed it.
+            - |-
+              A borrower drains through the parent's queue as well as its ceiling, so a high-volume
+              borrower competes with the parent's own flows — settle the priority split before
+              choosing who borrows from whom.
         autoRecoverRateLimitErrors:
           type: boolean
           default: true

package/dist/enduser.yml

@@ -2177,12 +2177,24 @@ components:
               type: string
               format: objectId
               x-celigo-refModel: connections
-              description: |
-                Reference to another connection to share concurrency limits with.
-                When set, this connection's concurrency is counted against the referenced
-                connection's limit instead of maintaining its own.
+              description: |-
+                Reference to another connection to share concurrency limits with. When set, this
+                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.
               examples:
                 - 615dfa0742763671275b70ab
+              x-celigo-ai-guidance:
+                - |-
+                  Set this when several connections target one external account whose API enforces a
+                  single account-wide concurrency limit (for example one NetSuite account): put the limit
+                  on one parent connection and point the others here, so their combined traffic can never
+                  exceed it.
+                - |-
+                  A borrower drains through the parent's queue as well as its ceiling, so a high-volume
+                  borrower competes with the parent's own flows — settle the priority split before
+                  choosing who borrows from whom.
             debugDate:
               type: string
               format: date-time
@@ -2560,21 +2572,52 @@ components:
             Required for some authentication configurations to identify the calling application.
         concurrencyLevel:
           type: integer
-          description: |
-            General concurrency level for this connection. Controls the overall
-            maximum concurrent requests across all operation types.
-            Values above the account's licensed maximum (25 standard, 50 with an Environments license) are silently clamped down.
+          description: |-
+            Maximum number of requests this connection sends to NetSuite in parallel, across SOAP,
+            REST and RESTlet calls. Values above the integrator.io license ceiling (25 standard, 50
+            with an Environments license) are stored as that ceiling. NetSuite separately enforces one
+            concurrency limit per NetSuite account that every caller of its SOAP, REST and RESTlet
+            APIs shares — all integrator.io connections to that account and every other client
+            calling those APIs from outside integrator.io (other integrations, third-party tools).
           minimum: 1
           maximum: 50
           default: 5
+          x-celigo-ai-guidance:
+            - |-
+              Before raising this connection's ceiling — `targetConcurrencyLevel` while
+              `autoRecoverRateLimitErrors` is on (the default; a PUT of `concurrencyLevel` then
+              changes nothing), `concurrencyLevel` only while it is off — total the ceilings of every
+              connection that targets the same NetSuite `account` and `environment` (a connection
+              that borrows counts under its parent) and keep that total, plus whatever calls the
+              account's APIs from outside integrator.io, within the NetSuite account limit; a value
+              that fits this connection alone can still push the whole account over.
+            - |-
+              The NetSuite limit is the service-tier base (Standard 5, Premium 15, Enterprise and
+              Ultimate 20; legacy tiers 5–20) plus 10 per SuiteCloud Plus license; a sandbox matches
+              its production account. Development and partner accounts are fixed at 5 and do not
+              scale with licenses. NetSuite shows the limit at Setup > Integration > Integration
+              Management > Integration Governance; integrator.io cannot read it — ask for the number
+              rather than assuming headroom.
+            - |-
+              Over the limit, NetSuite rejects requests from every caller of that account at once,
+              not only this connection's — SOAP: `ExceededConcurrentRequestLimitFault` /
+              `WS_REQUEST_BLOCKED`; REST web services: HTTP 429; RESTlets: HTTP 400
+              `SSS_REQUEST_LIMIT_EXCEEDED`. To run several connections against one NetSuite account,
+              put the limit on one parent and point the others at it with
+              `_borrowConcurrencyFromConnectionId`; otherwise raise in small steps.
         targetConcurrencyLevel:
           type: integer
-          description: |
+          description: |-
             Target concurrency level for auto-scaling. The system adjusts concurrency
             between 1 and this value based on rate limit and governance feedback.
           minimum: 1
           maximum: 50
           default: 5
+          x-celigo-ai-guidance:
+            - |-
+              With `autoRecoverRateLimitErrors` on, this is the level the connection climbs back to
+              after a recovery, so it — not `concurrencyLevel` — is the value that must fit the shared
+              NetSuite account budget described on `concurrencyLevel`.
         _iClientId:
           type: string
           format: objectId

package/dist/integration.yml

@@ -287,7 +287,9 @@ paths:
         | `/flowGroupings` | Flow grouping configuration |
         | `/apiGroupings` | API grouping configuration |
 
-        All other paths are rejected with `422`.
+        All other paths are rejected with `422`. A successful patch returns no body, so the
+        server-assigned `_id` of a grouping added through `/flowGroupings` or `/apiGroupings`
+        is only available from a follow-up `GET`.
       operationId: patchIntegration
       tags:
         - Integrations
@@ -4088,7 +4090,19 @@ components:
 
             Used to group APIs into named sections with their own settings/settingsForm.
             Works identically to `flowGroupings` but for API resources. Create groupings here,
-            then assign APIs to them via `PUT /v1/apis/updateApiGrouping`.
+            then assign APIs to them via `PUT /v1/apis/updateApiGrouping`. A grouping that still
+            has member APIs survives being removed from this array — ungroup its APIs first.
+          x-celigo-ai-guidance:
+            - |-
+              `Unassigned` is a reserved name (422 `invalid_apigrouping_name`) and names must be
+              unique within the integration (422 `duplicate_field`).
+            - |-
+              Removing a grouping that still has member APIs returns success but leaves the
+              grouping in place; move those APIs with `PUT /v1/apis/updateApiGrouping` first.
+            - |-
+              `POST` and `PUT` answer with the saved integration, so a new grouping's `_id` is
+              in the response; `PATCH` answers `204` with no body, so after a patch the `_id`
+              comes from a follow-up `GET`.
           items:
             type: object
             additionalProperties: true

package/dist/mcp-server.yml

@@ -3987,12 +3987,24 @@ components:
               type: string
               format: objectId
               x-celigo-refModel: connections
-              description: |
-                Reference to another connection to share concurrency limits with.
-                When set, this connection's concurrency is counted against the referenced
-                connection's limit instead of maintaining its own.
+              description: |-
+                Reference to another connection to share concurrency limits with. When set, this
+                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.
               examples:
                 - 615dfa0742763671275b70ab
+              x-celigo-ai-guidance:
+                - |-
+                  Set this when several connections target one external account whose API enforces a
+                  single account-wide concurrency limit (for example one NetSuite account): put the limit
+                  on one parent connection and point the others here, so their combined traffic can never
+                  exceed it.
+                - |-
+                  A borrower drains through the parent's queue as well as its ceiling, so a high-volume
+                  borrower competes with the parent's own flows — settle the priority split before
+                  choosing who borrows from whom.
             debugDate:
               type: string
               format: date-time
@@ -4370,21 +4382,52 @@ components:
             Required for some authentication configurations to identify the calling application.
         concurrencyLevel:
           type: integer
-          description: |
-            General concurrency level for this connection. Controls the overall
-            maximum concurrent requests across all operation types.
-            Values above the account's licensed maximum (25 standard, 50 with an Environments license) are silently clamped down.
+          description: |-
+            Maximum number of requests this connection sends to NetSuite in parallel, across SOAP,
+            REST and RESTlet calls. Values above the integrator.io license ceiling (25 standard, 50
+            with an Environments license) are stored as that ceiling. NetSuite separately enforces one
+            concurrency limit per NetSuite account that every caller of its SOAP, REST and RESTlet
+            APIs shares — all integrator.io connections to that account and every other client
+            calling those APIs from outside integrator.io (other integrations, third-party tools).
           minimum: 1
           maximum: 50
           default: 5
+          x-celigo-ai-guidance:
+            - |-
+              Before raising this connection's ceiling — `targetConcurrencyLevel` while
+              `autoRecoverRateLimitErrors` is on (the default; a PUT of `concurrencyLevel` then
+              changes nothing), `concurrencyLevel` only while it is off — total the ceilings of every
+              connection that targets the same NetSuite `account` and `environment` (a connection
+              that borrows counts under its parent) and keep that total, plus whatever calls the
+              account's APIs from outside integrator.io, within the NetSuite account limit; a value
+              that fits this connection alone can still push the whole account over.
+            - |-
+              The NetSuite limit is the service-tier base (Standard 5, Premium 15, Enterprise and
+              Ultimate 20; legacy tiers 5–20) plus 10 per SuiteCloud Plus license; a sandbox matches
+              its production account. Development and partner accounts are fixed at 5 and do not
+              scale with licenses. NetSuite shows the limit at Setup > Integration > Integration
+              Management > Integration Governance; integrator.io cannot read it — ask for the number
+              rather than assuming headroom.
+            - |-
+              Over the limit, NetSuite rejects requests from every caller of that account at once,
+              not only this connection's — SOAP: `ExceededConcurrentRequestLimitFault` /
+              `WS_REQUEST_BLOCKED`; REST web services: HTTP 429; RESTlets: HTTP 400
+              `SSS_REQUEST_LIMIT_EXCEEDED`. To run several connections against one NetSuite account,
+              put the limit on one parent and point the others at it with
+              `_borrowConcurrencyFromConnectionId`; otherwise raise in small steps.
         targetConcurrencyLevel:
           type: integer
-          description: |
+          description: |-
             Target concurrency level for auto-scaling. The system adjusts concurrency
             between 1 and this value based on rate limit and governance feedback.
           minimum: 1
           maximum: 50
           default: 5
+          x-celigo-ai-guidance:
+            - |-
+              With `autoRecoverRateLimitErrors` on, this is the level the connection climbs back to
+              after a recovery, so it — not `concurrencyLevel` — is the value that must fit the shared
+              NetSuite account budget described on `concurrencyLevel`.
         _iClientId:
           type: string
           format: objectId

package/dist/tool.yml

@@ -6602,12 +6602,24 @@ components:
               type: string
               format: objectId
               x-celigo-refModel: connections
-              description: |
-                Reference to another connection to share concurrency limits with.
-                When set, this connection's concurrency is counted against the referenced
-                connection's limit instead of maintaining its own.
+              description: |-
+                Reference to another connection to share concurrency limits with. When set, this
+                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.
               examples:
                 - 615dfa0742763671275b70ab
+              x-celigo-ai-guidance:
+                - |-
+                  Set this when several connections target one external account whose API enforces a
+                  single account-wide concurrency limit (for example one NetSuite account): put the limit
+                  on one parent connection and point the others here, so their combined traffic can never
+                  exceed it.
+                - |-
+                  A borrower drains through the parent's queue as well as its ceiling, so a high-volume
+                  borrower competes with the parent's own flows — settle the priority split before
+                  choosing who borrows from whom.
             debugDate:
               type: string
               format: date-time
@@ -6985,21 +6997,52 @@ components:
             Required for some authentication configurations to identify the calling application.
         concurrencyLevel:
           type: integer
-          description: |
-            General concurrency level for this connection. Controls the overall
-            maximum concurrent requests across all operation types.
-            Values above the account's licensed maximum (25 standard, 50 with an Environments license) are silently clamped down.
+          description: |-
+            Maximum number of requests this connection sends to NetSuite in parallel, across SOAP,
+            REST and RESTlet calls. Values above the integrator.io license ceiling (25 standard, 50
+            with an Environments license) are stored as that ceiling. NetSuite separately enforces one
+            concurrency limit per NetSuite account that every caller of its SOAP, REST and RESTlet
+            APIs shares — all integrator.io connections to that account and every other client
+            calling those APIs from outside integrator.io (other integrations, third-party tools).
           minimum: 1
           maximum: 50
           default: 5
+          x-celigo-ai-guidance:
+            - |-
+              Before raising this connection's ceiling — `targetConcurrencyLevel` while
+              `autoRecoverRateLimitErrors` is on (the default; a PUT of `concurrencyLevel` then
+              changes nothing), `concurrencyLevel` only while it is off — total the ceilings of every
+              connection that targets the same NetSuite `account` and `environment` (a connection
+              that borrows counts under its parent) and keep that total, plus whatever calls the
+              account's APIs from outside integrator.io, within the NetSuite account limit; a value
+              that fits this connection alone can still push the whole account over.
+            - |-
+              The NetSuite limit is the service-tier base (Standard 5, Premium 15, Enterprise and
+              Ultimate 20; legacy tiers 5–20) plus 10 per SuiteCloud Plus license; a sandbox matches
+              its production account. Development and partner accounts are fixed at 5 and do not
+              scale with licenses. NetSuite shows the limit at Setup > Integration > Integration
+              Management > Integration Governance; integrator.io cannot read it — ask for the number
+              rather than assuming headroom.
+            - |-
+              Over the limit, NetSuite rejects requests from every caller of that account at once,
+              not only this connection's — SOAP: `ExceededConcurrentRequestLimitFault` /
+              `WS_REQUEST_BLOCKED`; REST web services: HTTP 429; RESTlets: HTTP 400
+              `SSS_REQUEST_LIMIT_EXCEEDED`. To run several connections against one NetSuite account,
+              put the limit on one parent and point the others at it with
+              `_borrowConcurrencyFromConnectionId`; otherwise raise in small steps.
         targetConcurrencyLevel:
           type: integer
-          description: |
+          description: |-
             Target concurrency level for auto-scaling. The system adjusts concurrency
             between 1 and this value based on rate limit and governance feedback.
           minimum: 1
           maximum: 50
           default: 5
+          x-celigo-ai-guidance:
+            - |-
+              With `autoRecoverRateLimitErrors` on, this is the level the connection climbs back to
+              after a recovery, so it — not `concurrencyLevel` — is the value that must fit the shared
+              NetSuite account budget described on `concurrencyLevel`.
         _iClientId:
           type: string
           format: objectId

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.69",
+  "version": "0.2.71",
   "private": false,
   "description": "Public OpenAPI bundles (dist/) and the celigo-cli lint schema pack (schemas.json).",
   "keywords": [

package/schemas.json

@@ -1,7 +1,7 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "5a9800c",
+		"iasCommit": "de043a7",
 		"generatedAt": "2026-10-02"
 	},
 	"roots": {