@celigo/api-specs 0.2.213 → 0.2.214

package/dist/api.yml

@@ -8342,11 +8342,22 @@ components:
               format: objectId
               x-celigo-refModel: agents
               description: |
-                Reference to a Celigo on-premise Agent. Required for connection types that need
-                local network or filesystem access (JDBC, filesystem, Oracle RDBMS, and on-premise MongoDB).
+                Reference to a Celigo on-premise Agent. Connection types that need local network or
+                filesystem access (JDBC, filesystem, Oracle RDBMS, and on-premise MongoDB) carry one
+                binding — this agent, or an agent group in `_agentGroupId`; never both.
                 The agent establishes a secure tunnel between the on-premise environment and integrator.io.
               examples:
                 - 5f8d43a1b9e5a80011a35f2c
+            _agentGroupId:
+              type: string
+              format: objectId
+              x-celigo-refModel: agentgroups
+              description: |-
+                On-premise agent group serving this connection, when one is bound
+                instead of a single `_agentId`. Absent on connections that use a
+                single agent or none.
+              examples:
+                - 6650a1b2c3d4e5f60718293a
             _borrowConcurrencyFromConnectionId:
               type: string
               format: objectId
@@ -11124,8 +11135,10 @@ components:
       x-celigo-ai-guidance:
         - The POST is rejected with 422 if type-specific required fields are missing (see the per-type conditional rules).
         - |-
-          For Oracle, a placeholder connection cannot be created without a real connection-level _agentId
-          (validator error agent_mode_only) — direct the user to install a Celigo Agent first. All other
+          For Oracle, a placeholder connection cannot be created without a real on-premise binding — a
+          connection-level _agentId, or an agent group through _agentGroupId (validator error
+          agent_mode_only with neither; live-verified that a POST carrying only _agentGroupId is not
+          answered with it) — direct the user to install a Celigo Agent first. All other
           RDBMS types accept placeholder credentials that satisfy the per-type required fields.
         - |-
           Celigo has native support for these database systems:
@@ -11176,16 +11189,17 @@ components:
             `_iClientId` with `basic` auth is rejected. Both types share the
             `mssql` sub-object; `azuresynapse` is cloud-only, and the SQL Server
             connection form offers service-principal auth in Cloud mode only — it
-            saves `basic` for an on-premise connection (`_agentId` set).
-          - **Oracle** — runs in agent mode only, so requires `_agentId` on the
-            parent connection object. Uses `serviceName` instead of `database`.
+            saves `basic` for an on-premise connection (`_agentId` or `_agentGroupId` set).
+          - **Oracle** — runs in agent mode only, so requires an on-premise binding on
+            the parent connection object: `_agentId`, or an agent group's `_agentGroupId`
+            (one of the two, never both). Uses `serviceName` instead of `database`.
             Optionally also takes `serverType` and `instanceName`.
 
           ## PLACEHOLDER / DUMMY RDBMS CONNECTIONS
 
           For Oracle, placeholder connections cannot be created without a real
-          `_agentId` — the validator will reject them. Direct the user to install
-          a Celigo Agent first. For all other RDBMS types, a placeholder can be
+          `_agentId` or `_agentGroupId` — the validator will reject them. Direct the
+          user to install a Celigo Agent first. For all other RDBMS types, a placeholder can be
           created with dummy credentials matching the rules above.
       x-celigo-ui-override: 'Several requireds mirror the connection form rather than the API: snowflake.warehouse, redshift.clusterIdentifier, redshift.user, and mssql version. The API creates connections without them (live-verified 201), but the form requires them and a functional connection needs them. For mysql, postgresql, and mariadb the form makes password conditional — not required when a full SSL client certificate (ssl.ca, ssl.key, ssl.cert) is supplied instead; the conditional below keeps password required for the common (non-SSL) path, which is the only path the API enforces.'
       required:
@@ -11208,7 +11222,7 @@ components:
             postgresql: PostgreSQL database (default port 5432).
             mssql: Microsoft SQL Server (default port 1433).
             snowflake: Snowflake Data Cloud (requires snowflake.warehouse).
-            oracle: Oracle Database; runs in agent mode and requires a connection-level _agentId (default port 1521, uses serviceName instead of database).
+            oracle: Oracle Database; runs in agent mode and requires a connection-level _agentId or _agentGroupId (default port 1521, uses serviceName instead of database).
             bigquery: Google BigQuery; requires service account credentials in the bigquery sub-object.
             redshift: Amazon Redshift — provisioned clusters or Redshift Serverless; authenticates with static access keys or an AWS IAM role iClient (redshift.authType).
             mariadb: MariaDB database (default port 3306).
@@ -11433,7 +11447,7 @@ components:
                 iClient — a client secret, or on SQL Server a certificate — and
                 `_iClientId` must reference it. The SQL Server connection form
                 offers `azure-service-principal` in Cloud mode only and saves
-                `basic` for an on-premise connection (`_agentId` set).
+                `basic` for an on-premise connection (`_agentId` or `_agentGroupId` set).
               default: basic
               examples:
                 - basic
@@ -11899,9 +11913,9 @@ components:
           422 "Expected field: <field> to be present" if any of the three is missing. database is not
           required; when omitted, set it per operation instead.
         - |-
-          For an on-premise MongoDB instance, set the connection-level _agentId (the form's "On-premise"
-          mode) so traffic routes through a Celigo Agent. Cloud-reachable instances (including Atlas)
-          need no agent.
+          For an on-premise MongoDB instance, bind the connection to one agent (connection-level
+          _agentId) or to one agent group (_agentGroupId) — the form's "On-premise" mode — so traffic
+          routes through a Celigo Agent. Cloud-reachable instances (including Atlas) need no agent.
         - |-
           ## AUTHENTICATION
           Username and password are optional — only required when the MongoDB server has
@@ -12601,8 +12615,8 @@ components:
       description: |-
         Configuration for filesystem connections. Used when the connection type is "filesystem".
         Provides access to directories on a Celigo on-premise Agent's host or mounted network
-        drives, so a connection-level `_agentId` is required — cloud-only deployments cannot use
-        this type. File-based PGP encryption/decryption is configured through the connection-level
+        drives, so an on-premise binding is required — a connection-level `_agentId`, or an agent
+        group through `_agentGroupId` — and cloud-only deployments cannot use this type. File-based PGP encryption/decryption is configured through the connection-level
         `pgp` object.
       properties:
         ping:
@@ -12648,9 +12662,10 @@ components:
           mounted network drives.
 
           ## AGENT REQUIREMENT
-          A Celigo Agent is REQUIRED for filesystem connections (set _agentId on the parent
-          connection object). The agent provides the filesystem access — cloud-only
-          deployments cannot use this connection type.
+          A Celigo Agent is REQUIRED for filesystem connections: bind the parent connection
+          object to one agent (_agentId) or to one agent group (_agentGroupId) — one of the
+          two, never both. The agent provides the filesystem access — cloud-only deployments
+          cannot use this connection type.
     token:
       type: object
       description: |
@@ -13124,13 +13139,17 @@ components:
         Configuration for JDBC (Java Database Connectivity) connections. Used when the connection
         type is "jdbc". Provides access through Java JDBC drivers to databases not covered by the
         rdbms type — such as NetSuite SuiteAnalytics, Databricks, DB2, and Workday. The driver runs
-        on a Celigo on-premise Agent, so most jdbc connections need a connection-level _agentId.
+        on a Celigo on-premise Agent, so most jdbc connections need an on-premise binding — a
+        connection-level _agentId, or an agent group through _agentGroupId.
       x-celigo-ai-guidance:
         - The POST is rejected with 422 if type-specific required fields are missing (see the per-type conditional rules).
         - |-
-          The agent and activedirectory types require a real connection-level _agentId: the POST fails with
-          422 "The JDBC connection requires Agent. Expected field: _agentId to be present in the connection
-          doc." A placeholder cannot be created without one, so the user should install a Celigo Agent first.
+          The agent and activedirectory types require a real on-premise binding — a connection-level
+          _agentId, or an agent group through _agentGroupId (one of the two, never both; the agent-mode
+          check accepts either — live-verified for both agent and activedirectory: a POST carrying only
+          _agentGroupId is not answered with agent_mode_only): with neither, the POST fails with 422 "The JDBC
+          connection requires Agent. Expected field: _agentId to be present in the connection doc." A
+          placeholder cannot be created without one, so the user should install a Celigo Agent first.
           Other types commonly run on an agent too, but only these two are validator-enforced (live-verified
           celigo-labs-2 2026-06-11).
       x-celigo-ui-override: 'Two activedirectory requireds mirror the connection form rather than the API: password and port (default 389). The API creates an activedirectory connection without them (it auto-defaults port to 389), but the form requires both, so they are encoded to mirror the form. The workday user and password requireds are NOT form overrides — they are enforced by the API itself (POST returns 422 "Expected field: user/password to be present"). Per-type forms also require named entries inside jdbc.properties (netsuitejdbc AccountID + ServerDataSource; db2 AuthScheme; workday tenant/connectionType/authScheme; activedirectory LDAPVersion/BaseDN) — documented in prose since they live in the properties name/value array.'

package/dist/connection.yml

@@ -1028,7 +1028,7 @@ paths:
         | `/autoRecoverRateLimitErrors` | Rate-limit auto-recovery toggle. Turning it on copies the current level into the target; turning it off unsets the target and leaves the level at its current value |
         | `/http/rateLimit/failStatusCode`, `/http/rateLimit/failPath`, `/http/rateLimit/failHeaders` | Rate-limit detection rules. Send `failHeaders` as the whole array; on one element only `replace` of an existing entry works (e.g. `/http/rateLimit/failHeaders/0`), and `add` or `remove` on an element fails with 422 |
         | `/http/rateLimit/limit` | Wait between consecutive requests, in milliseconds. Accepted only at a concurrency of 1: set `/http/targetConcurrencyLevel` (while `autoRecoverRateLimitErrors` is true) or `/http/concurrencyLevel` (while it is false) to 1 in the same patch; at any other level it fails with 422 `invalid_concurrency_level` |
-        | `/endUserProvidedFields` | Dot-paths MCP end users must supply on their own child copy of this connection. `replace` with `[]` or `remove` clears the list, and `add` on `/endUserProvidedFields/-` appends one path; a path the account owns (`type`, `_agentId`, `wrapper._stackId`, any `<adaptor>._iClientId`) is rejected |
+        | `/endUserProvidedFields` | Dot-paths MCP end users must supply on their own child copy of this connection. `replace` with `[]` or `remove` clears the list, and `add` on `/endUserProvidedFields/-` appends one path; a path the account owns (`type`, `_agentId`, `_agentGroupId`, `wrapper._stackId`, any `<adaptor>._iClientId`) is rejected |
 
         `replace` and `add` both set the value (a currently unset field is fine);
         `remove` unsets it. A `null` value is rejected. Any other path — including
@@ -4175,11 +4175,22 @@ components:
               format: objectId
               x-celigo-refModel: agents
               description: |
-                Reference to a Celigo on-premise Agent. Required for connection types that need
-                local network or filesystem access (JDBC, filesystem, Oracle RDBMS, and on-premise MongoDB).
+                Reference to a Celigo on-premise Agent. Connection types that need local network or
+                filesystem access (JDBC, filesystem, Oracle RDBMS, and on-premise MongoDB) carry one
+                binding — this agent, or an agent group in `_agentGroupId`; never both.
                 The agent establishes a secure tunnel between the on-premise environment and integrator.io.
               examples:
                 - 5f8d43a1b9e5a80011a35f2c
+            _agentGroupId:
+              type: string
+              format: objectId
+              x-celigo-refModel: agentgroups
+              description: |-
+                On-premise agent group serving this connection, when one is bound
+                instead of a single `_agentId`. Absent on connections that use a
+                single agent or none.
+              examples:
+                - 6650a1b2c3d4e5f60718293a
             _borrowConcurrencyFromConnectionId:
               type: string
               format: objectId
@@ -6957,8 +6968,10 @@ components:
       x-celigo-ai-guidance:
         - The POST is rejected with 422 if type-specific required fields are missing (see the per-type conditional rules).
         - |-
-          For Oracle, a placeholder connection cannot be created without a real connection-level _agentId
-          (validator error agent_mode_only) — direct the user to install a Celigo Agent first. All other
+          For Oracle, a placeholder connection cannot be created without a real on-premise binding — a
+          connection-level _agentId, or an agent group through _agentGroupId (validator error
+          agent_mode_only with neither; live-verified that a POST carrying only _agentGroupId is not
+          answered with it) — direct the user to install a Celigo Agent first. All other
           RDBMS types accept placeholder credentials that satisfy the per-type required fields.
         - |-
           Celigo has native support for these database systems:
@@ -7009,16 +7022,17 @@ components:
             `_iClientId` with `basic` auth is rejected. Both types share the
             `mssql` sub-object; `azuresynapse` is cloud-only, and the SQL Server
             connection form offers service-principal auth in Cloud mode only — it
-            saves `basic` for an on-premise connection (`_agentId` set).
-          - **Oracle** — runs in agent mode only, so requires `_agentId` on the
-            parent connection object. Uses `serviceName` instead of `database`.
+            saves `basic` for an on-premise connection (`_agentId` or `_agentGroupId` set).
+          - **Oracle** — runs in agent mode only, so requires an on-premise binding on
+            the parent connection object: `_agentId`, or an agent group's `_agentGroupId`
+            (one of the two, never both). Uses `serviceName` instead of `database`.
             Optionally also takes `serverType` and `instanceName`.
 
           ## PLACEHOLDER / DUMMY RDBMS CONNECTIONS
 
           For Oracle, placeholder connections cannot be created without a real
-          `_agentId` — the validator will reject them. Direct the user to install
-          a Celigo Agent first. For all other RDBMS types, a placeholder can be
+          `_agentId` or `_agentGroupId` — the validator will reject them. Direct the
+          user to install a Celigo Agent first. For all other RDBMS types, a placeholder can be
           created with dummy credentials matching the rules above.
       x-celigo-ui-override: 'Several requireds mirror the connection form rather than the API: snowflake.warehouse, redshift.clusterIdentifier, redshift.user, and mssql version. The API creates connections without them (live-verified 201), but the form requires them and a functional connection needs them. For mysql, postgresql, and mariadb the form makes password conditional — not required when a full SSL client certificate (ssl.ca, ssl.key, ssl.cert) is supplied instead; the conditional below keeps password required for the common (non-SSL) path, which is the only path the API enforces.'
       required:
@@ -7041,7 +7055,7 @@ components:
             postgresql: PostgreSQL database (default port 5432).
             mssql: Microsoft SQL Server (default port 1433).
             snowflake: Snowflake Data Cloud (requires snowflake.warehouse).
-            oracle: Oracle Database; runs in agent mode and requires a connection-level _agentId (default port 1521, uses serviceName instead of database).
+            oracle: Oracle Database; runs in agent mode and requires a connection-level _agentId or _agentGroupId (default port 1521, uses serviceName instead of database).
             bigquery: Google BigQuery; requires service account credentials in the bigquery sub-object.
             redshift: Amazon Redshift — provisioned clusters or Redshift Serverless; authenticates with static access keys or an AWS IAM role iClient (redshift.authType).
             mariadb: MariaDB database (default port 3306).
@@ -7266,7 +7280,7 @@ components:
                 iClient — a client secret, or on SQL Server a certificate — and
                 `_iClientId` must reference it. The SQL Server connection form
                 offers `azure-service-principal` in Cloud mode only and saves
-                `basic` for an on-premise connection (`_agentId` set).
+                `basic` for an on-premise connection (`_agentId` or `_agentGroupId` set).
               default: basic
               examples:
                 - basic
@@ -7732,9 +7746,9 @@ components:
           422 "Expected field: <field> to be present" if any of the three is missing. database is not
           required; when omitted, set it per operation instead.
         - |-
-          For an on-premise MongoDB instance, set the connection-level _agentId (the form's "On-premise"
-          mode) so traffic routes through a Celigo Agent. Cloud-reachable instances (including Atlas)
-          need no agent.
+          For an on-premise MongoDB instance, bind the connection to one agent (connection-level
+          _agentId) or to one agent group (_agentGroupId) — the form's "On-premise" mode — so traffic
+          routes through a Celigo Agent. Cloud-reachable instances (including Atlas) need no agent.
         - |-
           ## AUTHENTICATION
           Username and password are optional — only required when the MongoDB server has
@@ -8434,8 +8448,8 @@ components:
       description: |-
         Configuration for filesystem connections. Used when the connection type is "filesystem".
         Provides access to directories on a Celigo on-premise Agent's host or mounted network
-        drives, so a connection-level `_agentId` is required — cloud-only deployments cannot use
-        this type. File-based PGP encryption/decryption is configured through the connection-level
+        drives, so an on-premise binding is required — a connection-level `_agentId`, or an agent
+        group through `_agentGroupId` — and cloud-only deployments cannot use this type. File-based PGP encryption/decryption is configured through the connection-level
         `pgp` object.
       properties:
         ping:
@@ -8481,9 +8495,10 @@ components:
           mounted network drives.
 
           ## AGENT REQUIREMENT
-          A Celigo Agent is REQUIRED for filesystem connections (set _agentId on the parent
-          connection object). The agent provides the filesystem access — cloud-only
-          deployments cannot use this connection type.
+          A Celigo Agent is REQUIRED for filesystem connections: bind the parent connection
+          object to one agent (_agentId) or to one agent group (_agentGroupId) — one of the
+          two, never both. The agent provides the filesystem access — cloud-only deployments
+          cannot use this connection type.
     token:
       type: object
       description: |
@@ -8957,13 +8972,17 @@ components:
         Configuration for JDBC (Java Database Connectivity) connections. Used when the connection
         type is "jdbc". Provides access through Java JDBC drivers to databases not covered by the
         rdbms type — such as NetSuite SuiteAnalytics, Databricks, DB2, and Workday. The driver runs
-        on a Celigo on-premise Agent, so most jdbc connections need a connection-level _agentId.
+        on a Celigo on-premise Agent, so most jdbc connections need an on-premise binding — a
+        connection-level _agentId, or an agent group through _agentGroupId.
       x-celigo-ai-guidance:
         - The POST is rejected with 422 if type-specific required fields are missing (see the per-type conditional rules).
         - |-
-          The agent and activedirectory types require a real connection-level _agentId: the POST fails with
-          422 "The JDBC connection requires Agent. Expected field: _agentId to be present in the connection
-          doc." A placeholder cannot be created without one, so the user should install a Celigo Agent first.
+          The agent and activedirectory types require a real on-premise binding — a connection-level
+          _agentId, or an agent group through _agentGroupId (one of the two, never both; the agent-mode
+          check accepts either — live-verified for both agent and activedirectory: a POST carrying only
+          _agentGroupId is not answered with agent_mode_only): with neither, the POST fails with 422 "The JDBC
+          connection requires Agent. Expected field: _agentId to be present in the connection doc." A
+          placeholder cannot be created without one, so the user should install a Celigo Agent first.
           Other types commonly run on an agent too, but only these two are validator-enforced (live-verified
           celigo-labs-2 2026-06-11).
       x-celigo-ui-override: 'Two activedirectory requireds mirror the connection form rather than the API: password and port (default 389). The API creates an activedirectory connection without them (it auto-defaults port to 389), but the form requires both, so they are encoded to mirror the form. The workday user and password requireds are NOT form overrides — they are enforced by the API itself (POST returns 422 "Expected field: user/password to be present"). Per-type forms also require named entries inside jdbc.properties (netsuitejdbc AccountID + ServerDataSource; db2 AuthScheme; workday tenant/connectionType/authScheme; activedirectory LDAPVersion/BaseDN) — documented in prose since they live in the properties name/value array.'
@@ -9910,12 +9929,32 @@ components:
           format: objectId
           x-celigo-refModel: agents
           description: |-
-            Reference to a Celigo on-premise Agent. Required for types that need local network or
-            filesystem access (filesystem, jdbc agent/activedirectory, Oracle rdbms, and on-premise
-            mongodb). The agent establishes a secure tunnel between the on-premise environment and
-            integrator.io.
+            Reference to a Celigo on-premise Agent. Types that run on an agent (filesystem, jdbc
+            agent/activedirectory, Oracle rdbms, and on-premise mongodb) need one binding — this
+            agent, or an agent group through `_agentGroupId`; either satisfies the requirement
+            (live-verified for filesystem, jdbc `agent` and `activedirectory`, and Oracle: with
+            neither id the POST answers 422 `agent_mode_only`; with `_agentGroupId` alone it does not).
+            The agent establishes a secure tunnel between the on-premise environment and
+            integrator.io. The connection form writes one of the two ids and omits the other; a
+            connection never carries both.
           examples:
             - 5f8d43a1b9e5a80011a35f2c
+        _agentGroupId:
+          type: string
+          format: objectId
+          x-celigo-refModel: agentgroups
+          description: |-
+            On-premise agent group that serves this connection instead of a single
+            `_agentId`; a connection binds one or the other, never both — the connection
+            form writes one id and omits the other. Requests go to the first healthy
+            member in the group's priority order (source-only: the dispatch rule the
+            platform implements), so one host failing does not stop the flow. On an
+            account whose license does not include agent groups, sending it fails with
+            422 `agent_groups_subscription_required` — "Your license does not support
+            the agent groups feature." (live-verified); an id that names no group adds
+            422 `invalid_ref` on `_agentGroupId` to the same response.
+          examples:
+            - 6650a1b2c3d4e5f60718293a
         _borrowConcurrencyFromConnectionId:
           type: string
           format: objectId
@@ -10001,9 +10040,10 @@ components:
           x-celigo-ai-guidance:
             - |-
               List only the credential and tenant fields that differ per end user, never a path the
-              account owns: `type`, `_agentId`, `wrapper._stackId`, or any `<adaptor>._iClientId`
+              account owns: `type`, `_agentId`, `_agentGroupId`, `wrapper._stackId`, or any `<adaptor>._iClientId`
               (e.g. `http._iClientId`) fails the save with 422
-              `mcp_end_user_provided_field_not_allowed`.
+              `mcp_end_user_provided_field_not_allowed` (live-verified for `_agentGroupId`:
+              "_agentGroupId is managed by the account owner and cannot be requested from an end user.").
             - |-
               This is the only MCP end-user field writable through `/v1/connections`; the child
               connections themselves are created by the end-user setup page, and `connectionRole:
@@ -10216,7 +10256,11 @@ components:
                       then:
                         required:
                           - filesystem
-                          - _agentId
+                        anyOf:
+                          - required:
+                              - _agentId
+                          - required:
+                              - _agentGroupId
                       else:
                         if:
                           properties:
@@ -10260,8 +10304,11 @@ components:
                                 required:
                                   - jdbc
                               then:
-                                required:
-                                  - _agentId
+                                anyOf:
+                                  - required:
+                                      - _agentId
+                                  - required:
+                                      - _agentGroupId
                             else:
                               if:
                                 properties:

package/dist/enduser.yml

@@ -2200,11 +2200,22 @@ components:
               format: objectId
               x-celigo-refModel: agents
               description: |
-                Reference to a Celigo on-premise Agent. Required for connection types that need
-                local network or filesystem access (JDBC, filesystem, Oracle RDBMS, and on-premise MongoDB).
+                Reference to a Celigo on-premise Agent. Connection types that need local network or
+                filesystem access (JDBC, filesystem, Oracle RDBMS, and on-premise MongoDB) carry one
+                binding — this agent, or an agent group in `_agentGroupId`; never both.
                 The agent establishes a secure tunnel between the on-premise environment and integrator.io.
               examples:
                 - 5f8d43a1b9e5a80011a35f2c
+            _agentGroupId:
+              type: string
+              format: objectId
+              x-celigo-refModel: agentgroups
+              description: |-
+                On-premise agent group serving this connection, when one is bound
+                instead of a single `_agentId`. Absent on connections that use a
+                single agent or none.
+              examples:
+                - 6650a1b2c3d4e5f60718293a
             _borrowConcurrencyFromConnectionId:
               type: string
               format: objectId
@@ -4982,8 +4993,10 @@ components:
       x-celigo-ai-guidance:
         - The POST is rejected with 422 if type-specific required fields are missing (see the per-type conditional rules).
         - |-
-          For Oracle, a placeholder connection cannot be created without a real connection-level _agentId
-          (validator error agent_mode_only) — direct the user to install a Celigo Agent first. All other
+          For Oracle, a placeholder connection cannot be created without a real on-premise binding — a
+          connection-level _agentId, or an agent group through _agentGroupId (validator error
+          agent_mode_only with neither; live-verified that a POST carrying only _agentGroupId is not
+          answered with it) — direct the user to install a Celigo Agent first. All other
           RDBMS types accept placeholder credentials that satisfy the per-type required fields.
         - |-
           Celigo has native support for these database systems:
@@ -5034,16 +5047,17 @@ components:
             `_iClientId` with `basic` auth is rejected. Both types share the
             `mssql` sub-object; `azuresynapse` is cloud-only, and the SQL Server
             connection form offers service-principal auth in Cloud mode only — it
-            saves `basic` for an on-premise connection (`_agentId` set).
-          - **Oracle** — runs in agent mode only, so requires `_agentId` on the
-            parent connection object. Uses `serviceName` instead of `database`.
+            saves `basic` for an on-premise connection (`_agentId` or `_agentGroupId` set).
+          - **Oracle** — runs in agent mode only, so requires an on-premise binding on
+            the parent connection object: `_agentId`, or an agent group's `_agentGroupId`
+            (one of the two, never both). Uses `serviceName` instead of `database`.
             Optionally also takes `serverType` and `instanceName`.
 
           ## PLACEHOLDER / DUMMY RDBMS CONNECTIONS
 
           For Oracle, placeholder connections cannot be created without a real
-          `_agentId` — the validator will reject them. Direct the user to install
-          a Celigo Agent first. For all other RDBMS types, a placeholder can be
+          `_agentId` or `_agentGroupId` — the validator will reject them. Direct the
+          user to install a Celigo Agent first. For all other RDBMS types, a placeholder can be
           created with dummy credentials matching the rules above.
       x-celigo-ui-override: 'Several requireds mirror the connection form rather than the API: snowflake.warehouse, redshift.clusterIdentifier, redshift.user, and mssql version. The API creates connections without them (live-verified 201), but the form requires them and a functional connection needs them. For mysql, postgresql, and mariadb the form makes password conditional — not required when a full SSL client certificate (ssl.ca, ssl.key, ssl.cert) is supplied instead; the conditional below keeps password required for the common (non-SSL) path, which is the only path the API enforces.'
       required:
@@ -5066,7 +5080,7 @@ components:
             postgresql: PostgreSQL database (default port 5432).
             mssql: Microsoft SQL Server (default port 1433).
             snowflake: Snowflake Data Cloud (requires snowflake.warehouse).
-            oracle: Oracle Database; runs in agent mode and requires a connection-level _agentId (default port 1521, uses serviceName instead of database).
+            oracle: Oracle Database; runs in agent mode and requires a connection-level _agentId or _agentGroupId (default port 1521, uses serviceName instead of database).
             bigquery: Google BigQuery; requires service account credentials in the bigquery sub-object.
             redshift: Amazon Redshift — provisioned clusters or Redshift Serverless; authenticates with static access keys or an AWS IAM role iClient (redshift.authType).
             mariadb: MariaDB database (default port 3306).
@@ -5291,7 +5305,7 @@ components:
                 iClient — a client secret, or on SQL Server a certificate — and
                 `_iClientId` must reference it. The SQL Server connection form
                 offers `azure-service-principal` in Cloud mode only and saves
-                `basic` for an on-premise connection (`_agentId` set).
+                `basic` for an on-premise connection (`_agentId` or `_agentGroupId` set).
               default: basic
               examples:
                 - basic
@@ -5757,9 +5771,9 @@ components:
           422 "Expected field: <field> to be present" if any of the three is missing. database is not
           required; when omitted, set it per operation instead.
         - |-
-          For an on-premise MongoDB instance, set the connection-level _agentId (the form's "On-premise"
-          mode) so traffic routes through a Celigo Agent. Cloud-reachable instances (including Atlas)
-          need no agent.
+          For an on-premise MongoDB instance, bind the connection to one agent (connection-level
+          _agentId) or to one agent group (_agentGroupId) — the form's "On-premise" mode — so traffic
+          routes through a Celigo Agent. Cloud-reachable instances (including Atlas) need no agent.
         - |-
           ## AUTHENTICATION
           Username and password are optional — only required when the MongoDB server has
@@ -6459,8 +6473,8 @@ components:
       description: |-
         Configuration for filesystem connections. Used when the connection type is "filesystem".
         Provides access to directories on a Celigo on-premise Agent's host or mounted network
-        drives, so a connection-level `_agentId` is required — cloud-only deployments cannot use
-        this type. File-based PGP encryption/decryption is configured through the connection-level
+        drives, so an on-premise binding is required — a connection-level `_agentId`, or an agent
+        group through `_agentGroupId` — and cloud-only deployments cannot use this type. File-based PGP encryption/decryption is configured through the connection-level
         `pgp` object.
       properties:
         ping:
@@ -6506,9 +6520,10 @@ components:
           mounted network drives.
 
           ## AGENT REQUIREMENT
-          A Celigo Agent is REQUIRED for filesystem connections (set _agentId on the parent
-          connection object). The agent provides the filesystem access — cloud-only
-          deployments cannot use this connection type.
+          A Celigo Agent is REQUIRED for filesystem connections: bind the parent connection
+          object to one agent (_agentId) or to one agent group (_agentGroupId) — one of the
+          two, never both. The agent provides the filesystem access — cloud-only deployments
+          cannot use this connection type.
     token:
       type: object
       description: |
@@ -6982,13 +6997,17 @@ components:
         Configuration for JDBC (Java Database Connectivity) connections. Used when the connection
         type is "jdbc". Provides access through Java JDBC drivers to databases not covered by the
         rdbms type — such as NetSuite SuiteAnalytics, Databricks, DB2, and Workday. The driver runs
-        on a Celigo on-premise Agent, so most jdbc connections need a connection-level _agentId.
+        on a Celigo on-premise Agent, so most jdbc connections need an on-premise binding — a
+        connection-level _agentId, or an agent group through _agentGroupId.
       x-celigo-ai-guidance:
         - The POST is rejected with 422 if type-specific required fields are missing (see the per-type conditional rules).
         - |-
-          The agent and activedirectory types require a real connection-level _agentId: the POST fails with
-          422 "The JDBC connection requires Agent. Expected field: _agentId to be present in the connection
-          doc." A placeholder cannot be created without one, so the user should install a Celigo Agent first.
+          The agent and activedirectory types require a real on-premise binding — a connection-level
+          _agentId, or an agent group through _agentGroupId (one of the two, never both; the agent-mode
+          check accepts either — live-verified for both agent and activedirectory: a POST carrying only
+          _agentGroupId is not answered with agent_mode_only): with neither, the POST fails with 422 "The JDBC
+          connection requires Agent. Expected field: _agentId to be present in the connection doc." A
+          placeholder cannot be created without one, so the user should install a Celigo Agent first.
           Other types commonly run on an agent too, but only these two are validator-enforced (live-verified
           celigo-labs-2 2026-06-11).
       x-celigo-ui-override: 'Two activedirectory requireds mirror the connection form rather than the API: password and port (default 389). The API creates an activedirectory connection without them (it auto-defaults port to 389), but the form requires both, so they are encoded to mirror the form. The workday user and password requireds are NOT form overrides — they are enforced by the API itself (POST returns 422 "Expected field: user/password to be present"). Per-type forms also require named entries inside jdbc.properties (netsuitejdbc AccountID + ServerDataSource; db2 AuthScheme; workday tenant/connectionType/authScheme; activedirectory LDAPVersion/BaseDN) — documented in prose since they live in the properties name/value array.'