@celigo/api-specs 0.2.213 → 0.2.215

package/dist/agentgroup.yml

@@ -0,0 +1,1026 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: On-premise agent groups
+  description: 'API for managing Celigo on-premise agent groups: sets of agents that can serve the same connection, so one host failing does not stop your flows.'
+  x-celigo-ai-guidance:
+    - |-
+      API for managing on-premise agent groups in Celigo.
+      An on-premise agent group is an ordered set of on-premise agents
+      (locally installed tunnel software, not AI agents). A connection binds
+      either a single `_agentId` or an `_agentGroupId`, never both. When a
+      connection is bound to a group, the platform picks a healthy member for
+      every dispatch.
+servers:
+  - url: https://api.integrator.io
+    description: Production (US / default region)
+  - url: https://api.eu.integrator.io
+    description: Production (EU region)
+  - url: https://api.au.integrator.io
+    description: Production (AU region)
+  - url: https://api.ca.integrator.io
+    description: Production (CA region)
+security:
+  - bearerAuth: []
+tags:
+  - name: On-premise agent groups
+    description: |-
+      An on-premise agent group is an ordered set of agents that can each reach
+      the same systems. A connection binds either `_agentId` (one agent) or
+      `_agentGroupId` (a group) — never both.
+
+      When a connection is bound to a group, the platform resolves a healthy
+      member on every dispatch. Per the eligibility rule the platform
+      implements, a member stops receiving new work when it goes offline, when
+      its heartbeat goes stale, or when its local worker reports unhealthy, and
+      the connection stays online while any member can still serve (source-only:
+      read from the platform's dispatch code; not yet observed on an entitled
+      account).
+
+      Agents themselves are unaware of grouping — a group is N ordinary agents,
+      each with its own tunnel. Use the On-premise Agents API to install,
+      configure, and monitor the members.
+
+      ## Ordering
+
+      `members` order is failover priority. `members[0]` is preferred and is
+      used whenever it is eligible. Reordering takes effect on the next
+      dispatch and does not interrupt work in flight (source-only, as above).
+
+      ## Health
+
+      Health is not embedded in these responses. Read `offline` and
+      `lastHeartbeatAt` from `GET /v1/agents` for each `members[]._agentId` to
+      compose a live view of the group.
+
+      ## On-premise agent group schema
+
+      {% openapi-schemas spec="agentgroup" schemas="AgentGroup" grouped="true" %}
+paths:
+  /v1/agentgroups:
+    get:
+      x-internal: false
+      summary: List agent groups
+      description: |-
+        Returns all on-premise agent groups configured in the environment. Member
+        health is not included — fetch `GET /v1/agents` and match on
+        `members[]._agentId` to show which members are currently eligible.
+      operationId: listAgentGroups
+      tags:
+        - On-premise agent groups
+      parameters:
+        - $ref: '#/components/parameters/Include'
+        - $ref: '#/components/parameters/Exclude'
+        - name: limit
+          in: query
+          required: false
+          description: Maximum number of agent groups to return per page.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            default: 1000
+            examples:
+              - 100
+        - name: sort_by
+          in: query
+          required: false
+          description: Field to sort the agent group list by (for example `name`).
+          schema:
+            type: string
+            examples:
+              - name
+        - name: after
+          in: query
+          required: false
+          description: |-
+            Opaque pagination cursor from a previous page's `Link` header;
+            returns results after that position. Invalid cursor values return
+            400 `invalid_query_param`.
+          schema:
+            type: string
+        - name: before
+          in: query
+          required: false
+          description: |-
+            Opaque pagination cursor from a previous page's `Link` header;
+            returns results before that position. Invalid cursor values return
+            400 `invalid_query_param`.
+          schema:
+            type: string
+        - name: permissions
+          in: query
+          required: false
+          description: |-
+            When true, each returned agent group additionally carries
+            `_accessLevel` — the calling user's effective access to that group.
+          schema:
+            type: boolean
+            examples:
+              - true
+      responses:
+        '200':
+          description: Array of agent group objects.
+          x-celigo-ai-guidance:
+            - Successfully retrieved list of agent groups
+          headers:
+            Link:
+              description: |-
+                RFC 5988 pagination links. Includes `<...>; rel="next"` when more
+                pages remain; absent on the final page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/AgentGroup'
+              examples:
+                default:
+                  value:
+                    - _id: 6512ab7939dc306a3806eab5
+                      name: Production ERP agents
+                      description: Two hosts in separate racks, both reach the prod Oracle instance.
+                      members:
+                        - _agentId: 62e1387939dc306a3806eab5
+                        - _agentId: 5ecd2c3ce1ec9c4fcaf60b10
+                      routingPolicy: failover
+                      createdAt: '2026-07-02T10:30:00.000Z'
+                      lastModified: '2026-08-14T01:52:12.086Z'
+                    - _id: 6512ab7939dc306a3806eac1
+                      name: Warehouse SFTP agents
+                      members:
+                        - _agentId: 6398ddf316be761fb16a6523
+                      routingPolicy: failover
+                      createdAt: '2026-07-20T08:00:00.000Z'
+                      lastModified: '2026-07-20T08:00:00.000Z'
+        '204':
+          description: No agent groups exist in this environment.
+        '400':
+          description: Invalid pagination cursor in `after` or `before`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_cursor:
+                  value:
+                    errors:
+                      - code: invalid_query_param
+                        message: Please provide a valid cursor(i.e after or before query param) to encode or decode.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          description: '`limit` is outside the accepted range.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_limit:
+                  value:
+                    errors:
+                      - code: invalid_query_param
+                        message: The query parameter "limit" has invalid value.
+    post:
+      x-internal: false
+      summary: Create an agent group
+      operationId: createAgentGroup
+      tags:
+        - On-premise agent groups
+      description: |-
+        Creates an on-premise agent group. Every member must be an existing agent
+        in the same environment. `members` order is failover priority.
+
+        The service does not reject a group whose members share one agent
+        extension (source-only — agent extension placement is not
+        customer-controllable), but such a group is not highly available: that
+        host is a single point of failure in front of the group.
+
+        Requires the agent groups entitlement. Only the `name` check runs before
+        it, so an account without the entitlement gets 403 `feature_not_entitled`
+        for any request that has a `name`, whatever its `members` or
+        `routingPolicy` (live-verified with `members` absent, `[]`, a non-array,
+        a nonexistent agent id, and four repeats of one id, and with
+        `routingPolicy: balanced` — every shape answered 403). Reads, updates and
+        deletes do not check the entitlement — on the same account, list and get
+        answer normally and `PUT` / `DELETE` on an unknown id answer 404, not 403
+        (live-verified).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              two-members:
+                summary: Two-member failover group
+                value:
+                  name: Production ERP agents
+                  description: Two hosts in separate racks, both reach the prod Oracle instance.
+                  members:
+                    - _agentId: 62e1387939dc306a3806eab5
+                    - _agentId: 5ecd2c3ce1ec9c4fcaf60b10
+                  routingPolicy: failover
+              minimal:
+                summary: Minimal request
+                value:
+                  name: Warehouse SFTP agents
+                  members:
+                    - _agentId: 6398ddf316be761fb16a6523
+      responses:
+        '201':
+          description: Created agent group.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AgentGroup'
+              examples:
+                created:
+                  value:
+                    _id: 6512ab7939dc306a3806eab5
+                    name: Production ERP agents
+                    description: Two hosts in separate racks, both reach the prod Oracle instance.
+                    members:
+                      - _agentId: 62e1387939dc306a3806eab5
+                      - _agentId: 5ecd2c3ce1ec9c4fcaf60b10
+                    routingPolicy: failover
+                    createdAt: '2026-07-02T10:30:00.000Z'
+                    lastModified: '2026-07-02T10:30:00.000Z'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: The account is not entitled to on-premise agent groups.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not-entitled:
+                  summary: Account not entitled to agent groups
+                  value:
+                    errors:
+                      - code: feature_not_entitled
+                        message: On-premise agent groups are not enabled for this account.
+                        source: resource
+        '422':
+          description: |-
+            Validation failed. A missing, blank or non-string `name` answers
+            `required_field_missing` before the entitlement check (live-verified).
+            The rules below are read from the agent management service's validation
+            and are source-only until an entitled account confirms them — the probe
+            account is not entitled to agent groups. On an entitled account, a
+            non-array `members` answers `invalid_field_type`, and these rules answer
+            with `field` set to the path at fault: more than 3 members
+            (`max_members_exceeded`), a repeated `_agentId` (`duplicate_member`), an
+            agent that does not exist (`invalid_ref`), an agent in another
+            environment (`agent_group_member_environment_mismatch`),
+            `routingPolicy: balanced` (`invalid_routing_policy`), or a `name` over
+            100 characters (`size_limit_exceeded`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                missing-name:
+                  value:
+                    errors:
+                      - code: required_field_missing
+                        message: 'required field: name is missing'
+                too-many-members:
+                  summary: More than 3 members
+                  value:
+                    errors:
+                      - field: members
+                        code: max_members_exceeded
+                        message: An on-premise agent group cannot have more than 3 members.
+                duplicate-member:
+                  summary: Same agent listed twice
+                  value:
+                    errors:
+                      - field: members
+                        code: duplicate_member
+                        message: On-premise agent 62e1387939dc306a3806eab5 is listed more than once in this group.
+                environment-mismatch:
+                  summary: Member in a different environment
+                  value:
+                    errors:
+                      - field: members
+                        code: agent_group_member_environment_mismatch
+                        message: On-premise agent 62e1387939dc306a3806eab5 belongs to a different environment than this group.
+                balanced-not-supported:
+                  summary: Routing policy reserved for a later release
+                  value:
+                    errors:
+                      - field: routingPolicy
+                        code: invalid_routing_policy
+                        message: Routing policy balanced is not supported.
+  /v1/agentgroups/{_id}:
+    get:
+      x-internal: false
+      summary: Get an agent group
+      operationId: getAgentGroup
+      tags:
+        - On-premise agent groups
+      description: |-
+        Returns a single on-premise agent group. Member health is not embedded —
+        read `GET /v1/agents` for each `members[]._agentId` to show live
+        eligibility.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Agent group resource ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: agentgroups
+      responses:
+        '200':
+          description: Agent group object.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AgentGroup'
+              examples:
+                two-members:
+                  summary: Two-member failover group
+                  value:
+                    _id: 6512ab7939dc306a3806eab5
+                    name: Production ERP agents
+                    description: Two hosts in separate racks, both reach the prod Oracle instance.
+                    members:
+                      - _agentId: 62e1387939dc306a3806eab5
+                      - _agentId: 5ecd2c3ce1ec9c4fcaf60b10
+                    routingPolicy: failover
+                    createdAt: '2026-07-02T10:30:00.000Z'
+                    lastModified: '2026-08-14T01:52:12.086Z'
+        '400':
+          description: '`_id` is not a valid ObjectId.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                malformed-id:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _id.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            No agent group has this id in the environment. A group in the recycle
+            bin answers with the recycle-bin message instead (source-only: no group
+            could be created on the probe account to put one there).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not-found:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: On-premise agent group not found for the given id.
+                in-recycle-bin:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: You are trying to access an on-premise agent group that is already in the Recycle Bin. Please restore it from the Recycle Bin and try your request again.
+    put:
+      x-internal: false
+      summary: Update an agent group
+      operationId: updateAgentGroup
+      tags:
+        - On-premise agent groups
+      description: |-
+        Replaces an on-premise agent group. Send the complete desired document:
+        the service's update handler treats the body as a **full replace, not a
+        merge** — omitting `members` clears the membership list, and omitting
+        `description` or `routingPolicy` clears those fields (source-only: read
+        from the handler, not yet confirmed on an entitled account; sending the
+        whole document is correct under either behaviour). There is no PATCH on
+        this resource (live-verified: `PATCH` answers 404 `resource_not_found`).
+
+        Reordering `members` changes failover priority and, per the dispatch
+        rule the service implements, takes effect on the next dispatch without
+        interrupting work already in flight (source-only).
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Agent group resource ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: agentgroups
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              add-member:
+                summary: Add a third member
+                value:
+                  name: Production ERP agents
+                  description: Two hosts in separate racks, both reach the prod Oracle instance.
+                  members:
+                    - _agentId: 62e1387939dc306a3806eab5
+                    - _agentId: 5ecd2c3ce1ec9c4fcaf60b10
+                    - _agentId: 6398ddf316be761fb16a6523
+                  routingPolicy: failover
+              reprioritize:
+                summary: Promote the second host to preferred
+                value:
+                  name: Production ERP agents
+                  members:
+                    - _agentId: 5ecd2c3ce1ec9c4fcaf60b10
+                    - _agentId: 62e1387939dc306a3806eab5
+      responses:
+        '200':
+          description: Updated agent group.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AgentGroup'
+              examples:
+                updated:
+                  value:
+                    _id: 6512ab7939dc306a3806eab5
+                    name: Production ERP agents
+                    description: Two hosts in separate racks, both reach the prod Oracle instance.
+                    members:
+                      - _agentId: 62e1387939dc306a3806eab5
+                      - _agentId: 5ecd2c3ce1ec9c4fcaf60b10
+                      - _agentId: 6398ddf316be761fb16a6523
+                    routingPolicy: failover
+                    createdAt: '2026-07-02T10:30:00.000Z'
+                    lastModified: '2026-08-21T11:04:55.120Z'
+        '400':
+          description: The body is not a JSON object, or `_id` is not a valid ObjectId.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                body-not-object:
+                  value:
+                    errors:
+                      - code: invalid_request
+                        message: AgentGroup document should be a JSON object.
+                malformed-id:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _id.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          description: |-
+            No agent group has this id in the environment (live-verified). A group
+            in the recycle bin answers with the recycle-bin message instead
+            (source-only, as on GET). The lookup runs after the `name` check — an
+            empty body on an unknown id answers 422 `required_field_missing`, not
+            404 (live-verified) — and before any member rule.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not-found:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: On-premise agent group not found for the given id.
+                in-recycle-bin:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: You are trying to access an on-premise agent group that is already in the Recycle Bin. Please restore it from the Recycle Bin and try your request again.
+        '422':
+          description: |-
+            Validation failed. A missing, blank or non-string `name` answers
+            `required_field_missing` (live-verified). The member and routing rules
+            answer as on create — source-only until an entitled account confirms
+            them: `invalid_field_type` for a non-array `members`, and
+            `max_members_exceeded`, `duplicate_member`, `invalid_ref`,
+            `agent_group_member_environment_mismatch`, `invalid_routing_policy` or
+            `size_limit_exceeded` with `field` set to the path at fault.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                missing-name:
+                  value:
+                    errors:
+                      - code: required_field_missing
+                        message: 'required field: name is missing'
+    delete:
+      x-internal: false
+      summary: Delete an agent group
+      operationId: deleteAgentGroup
+      tags:
+        - On-premise agent groups
+      description: |-
+        Deletes an on-premise agent group. Soft-deleted and retained in the
+        recycle bin for 30 days. Member agents are not deleted or uninstalled —
+        only the grouping is removed.
+
+        The service refuses the delete with 409 `agent_group_in_use` while any
+        connection is still bound to this group (source-only: no group could be
+        created on the probe account to bind one). Re-point those connections to
+        a single `_agentId`, or to another group, first, and check
+        `GET /v1/agentgroups/{_id}/dependencies` before deleting.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Agent group resource ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: agentgroups
+      responses:
+        '204':
+          description: Agent group deleted.
+        '400':
+          description: '`_id` is not a valid ObjectId.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                malformed-id:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _id.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            No active agent group has this id. An unknown id answers with the
+            recycle-bin message (live-verified); a group already in the recycle bin
+            answers the same way (source-only).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not-active:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: You are trying to access an on-premise agent group that is already in the Recycle Bin. Please restore it from the Recycle Bin and try your request again.
+        '409':
+          description: |-
+            The agent group is still bound to at least one connection (source-only:
+            read from the service's delete guard, not yet confirmed on an entitled
+            account).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                in-use:
+                  value:
+                    errors:
+                      - code: agent_group_in_use
+                        message: This on-premise agent group is used by one or more connections and cannot be deleted.
+  /v1/agentgroups/{_id}/dependencies:
+    get:
+      x-internal: false
+      operationId: listAgentGroupDependencies
+      tags:
+        - On-premise agent groups
+      summary: List dependencies of an agent group
+      description: |-
+        Returns resources that depend on this on-premise agent group. Keys are
+        resource types (`connections`); values are arrays of dependency entries.
+
+        Check dependencies before deleting — the service refuses DELETE with 409
+        `agent_group_in_use` while any connection is still bound (source-only until
+        an entitled account confirms it). Returns `{}` for both zero-dependency and
+        nonexistent IDs (live-verified for a nonexistent id).
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Agent group resource ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: agentgroups
+      responses:
+        '200':
+          description: |
+            Dependency map. Keys are resource-type strings; values are arrays
+            of dependency entries. Returns `{}` when no dependents exist.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DependencyResponse'
+              examples:
+                none:
+                  summary: No dependents (also returned for a nonexistent ID)
+                  value: {}
+        '400':
+          description: '`_id` is not a valid ObjectId.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                malformed-id:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _id.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  parameters:
+    Include:
+      name: include
+      in: query
+      required: false
+      description: |-
+        Comma-separated list of fields to project into each returned record.
+        Triggers summary projection: the response contains a minimal identity
+        set (`_id`, `name`, plus resource-specific fields) with the requested
+        fields added on top. Supports dot notation for nested fields.
+        Mutually exclusive with `exclude`.
+      schema:
+        type: string
+      example: _integrationId,disabled,lastModified
+    Exclude:
+      name: exclude
+      in: query
+      required: false
+      description: |-
+        Comma-separated list of fields to strip from the default response.
+        Unlike `include`, does not trigger summary projection — returns the
+        full record with the named fields removed. Protected identity fields
+        (e.g. `name`) cannot be stripped. Mutually exclusive with `include`.
+      schema:
+        type: string
+      example: createdAt,lastModified
+  schemas:
+    AgentGroupBase:
+      type: object
+      description: Fields for creating or updating an on-premise agent group.
+      properties:
+        name:
+          type: string
+          maxLength: 100
+          description: |-
+            Display name identifying the group of on-premise agents. The server caps
+            it at 100 characters (`size_limit_exceeded`) — a cap read from the model's
+            size limit, enforced by the same plugin that caps agent names (verified
+            live there), not yet confirmed on an agent group.
+          x-celigo-ai-guidance:
+            - |-
+              Name the group after the systems its members reach, not after a single host —
+              the point of a group is that any member can serve the work.
+          examples:
+            - Production ERP agents
+        description:
+          type: string
+          maxLength: 5120
+          description: |-
+            Optional note about the group's purpose or the hosts it spans; capped at
+            5,120 characters by the same model size limit as `name` (source-only).
+          examples:
+            - Two hosts in separate racks, both reach the prod Oracle instance.
+        members:
+          type: array
+          maxItems: 3
+          description: |-
+            Ordered list of member on-premise agents. **Array order is failover priority** —
+            `members[0]` is the preferred member and is used whenever it is eligible.
+            The service's validation allows at most 3 members, rejects a repeated
+            `_agentId`, and requires every member to belong to the same environment
+            as the group (rules read from the service — source-only until an
+            entitled account confirms them; the matching 422 codes are on the
+            create and update operations).
+          x-celigo-ai-guidance:
+            - |-
+              Order matters. The platform picks the first eligible member in this array,
+              so put the preferred host first.
+            - |-
+              Place members on different hosts. Two members behind the same agent
+              extension share a failure domain, which defeats the purpose of the group.
+          items:
+            type: object
+            required:
+              - _agentId
+            properties:
+              _agentId:
+                type: string
+                format: objectId
+                description: Reference to a member on-premise agent.
+                x-celigo-refModel: agents
+                examples:
+                  - 62e1387939dc306a3806eab5
+          examples:
+            - - _agentId: 62e1387939dc306a3806eab5
+              - _agentId: 5ecd2c3ce1ec9c4fcaf60b10
+        routingPolicy:
+          type: string
+          enum:
+            - failover
+            - balanced
+          default: failover
+          x-enumDescriptions:
+            failover: Always dispatch to the first eligible member in `members`; later members only take over when earlier ones are unavailable.
+            balanced: Reserved for a later release; the service's validation rejects it with 422 `invalid_routing_policy` (source-only until an entitled account confirms it)
+          description: |-
+            How the platform picks a member for each dispatch. Leave it at
+            `failover` (the only accepted value today); member order in `members`
+            is the priority order.
+
+            Absent is treated as `failover`.
+          examples:
+            - failover
+    ResourceResponse:
+      type: object
+      description: Response
+      x-celigo-ai-guidance:
+        - Core response fields shared by all Celigo resources
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Unique identifier for the resource. Format is a 24-character hexadecimal string.
+          x-celigo-ai-guidance:
+            - |-
+              The _id is used in:
+              - API endpoints that operate on a specific resource (e.g., GET, PUT, DELETE)
+              - References from other resources (e.g., flows that use this resource)
+              - Job history and error tracking
+          examples:
+            - 5f8d43a1b9e5a80011a35f2c
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was created. Set automatically and cannot be modified.
+          x-celigo-ai-guidance:
+            - Recorded in ISO 8601 with a UTC timezone (Z suffix).
+          examples:
+            - '2023-04-01T09:15:32Z'
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was last updated. Changes whenever any property is modified.
+          x-celigo-ai-guidance:
+            - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+            - |-
+              Records that something was written, not what — a settings edit, a flag flip, or a
+              platform workflow all move it. What changed and when is in the audit log: the
+              per-resource route `GET /v1/{resourceType}/{_id}/audit` for the types its
+              `resourceType` enum lists, or the account-wide
+              `GET /v1/audit?resourceType=<singular>&_resourceId={_id}` for the further types that
+              endpoint's enum accepts (users, environments, notifications among them). A type absent
+              from both enums — jobs, connectors, templates — has only this timestamp.
+          examples:
+            - '2023-04-15T14:30:15Z'
+        deletedAt:
+          type:
+            - string
+            - 'null'
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was soft-deleted. When null or absent, the resource is active.
+          x-celigo-ai-guidance:
+            - Non-null means the resource is soft-deleted (in the recycle bin) — recoverable within the retention period before permanent removal.
+          examples:
+            - '2023-05-20T11:45:32Z'
+      required:
+        - _id
+    AgentGroup:
+      type: object
+      required:
+        - _id
+        - name
+        - createdAt
+        - lastModified
+      description: |-
+        On-premise agent group object as returned by the API. Member health is
+        **not** embedded — read `offline` and `lastHeartbeatAt` from
+        `GET /v1/agents` for each `_agentId` to compose a live view of the group.
+      allOf:
+        - $ref: '#/components/schemas/AgentGroupBase'
+        - $ref: '#/components/schemas/ResourceResponse'
+        - type: object
+          properties:
+            _accessLevel:
+              type: string
+              readOnly: true
+              description: |-
+                The calling user's effective access level for this group.
+                Present only when the list request sets `permissions=true`.
+              examples:
+                - manage
+    Error:
+      type: object
+      description: Standard error response envelope returned by integrator.io APIs.
+      properties:
+        errors:
+          type: array
+          description: List of errors that occurred while processing the request.
+          items:
+            type: object
+            properties:
+              code:
+                oneOf:
+                  - type: string
+                  - type: integer
+                description: |-
+                  Machine-readable error code. Usually a string like
+                  `invalid_ref`, `missing_required_field`, or `unauthorized`;
+                  may be an **integer** when the error mirrors an upstream HTTP
+                  status (e.g. `500`) — most commonly returned by connection-ping
+                  and adaptor-proxy responses.
+              message:
+                type: string
+                description: Human-readable description of the error.
+              field:
+                type: string
+                description: |-
+                  Optional pointer to the document field that caused the error.
+                  Used by structural validation errors (`missing_required_field`,
+                  `invalid_ref`) to indicate which field is at fault
+                  (e.g. `_id`, `type`, `http.baseURI`).
+              source:
+                type: string
+                description: |-
+                  Optional origin layer for the error — e.g. `application` when
+                  the error came from the remote system the adaptor called,
+                  `connector` when the adaptor itself rejected the request.
+            required:
+              - message
+      required:
+        - errors
+    Request:
+      type: object
+      description: Fields for creating or updating an on-premise agent group.
+      x-celigo-ai-guidance:
+        - Fields that can be sent when creating or updating an on-premise agent group
+        - |-
+          Send the complete desired document on every PUT — `name`, `members`,
+          and any `description` or `routingPolicy` you want kept. The update
+          operation documents a full replace in which an omitted `members` clears
+          the list; sending the whole document is correct whether or not that
+          holds on a given account.
+      required:
+        - name
+      allOf:
+        - $ref: '#/components/schemas/AgentGroupBase'
+    DependencyEntry:
+      type: object
+      description: A single resource that depends on the queried resource.
+      properties:
+        id:
+          type: string
+          description: Unique identifier of the dependent resource.
+          examples:
+            - 61f92026dd053843b5d72350
+        name:
+          type: string
+          description: Display name of the dependent resource.
+          examples:
+            - Import Orders to NetSuite
+        type:
+          type: string
+          description: |-
+            Sub-type of the dependent resource when its collection distinguishes one, such as
+            `stream` for a listener export. Only present for resource types that carry a `type`.
+          examples:
+            - stream
+        paths:
+          type: array
+          description: |-
+            Dot-notation paths within the dependent resource that reference
+            the target resource. `[*]` denotes array elements.
+          items:
+            type: string
+          examples:
+            - - hooks.preSavePage._scriptId
+        accessLevel:
+          type: string
+          description: The caller's access level on the dependent resource.
+          examples:
+            - manage
+        dependencyIds:
+          type: object
+          description: |-
+            Map of resource types to arrays of IDs that this dependent
+            resource references on the target. Keys are singular or plural
+            resource type strings; values are arrays of ID strings.
+          additionalProperties:
+            type: array
+            items:
+              type: string
+          example:
+            script:
+              - 64ff4b21612a134bd2f45531
+      required:
+        - id
+        - name
+        - paths
+        - accessLevel
+        - dependencyIds
+    DependencyResponse:
+      type: object
+      description: |
+        Map of dependent-resource types to arrays of dependency entries.
+        Keys are plural resource type strings (e.g. `flows`, `imports`,
+        `connections`). An empty object `{}` means no dependents.
+      additionalProperties:
+        type: array
+        items:
+          $ref: '#/components/schemas/DependencyEntry'
+      example:
+        exports:
+          - id: 64ff4b21612a134bd2f45534
+            name: Bank FTP Export
+            paths:
+              - hooks.preSavePage._scriptId
+            accessLevel: manage
+            dependencyIds:
+              script:
+                - 64ff4b21612a134bd2f45531
+        flows:
+          - id: 64ff4b22612a134bd2f45538
+            name: CAMT-053 to Celigo CAM Format
+            paths:
+              - pageGenerators[*]._exportId
+            accessLevel: manage
+            dependencyIds:
+              export:
+                - 64ff4b21612a134bd2f45534
+  responses:
+    401-unauthorized:
+      description: |-
+        Unauthorized. The request lacks a valid bearer token, or the provided token
+        failed to authenticate.
+
+        Note: the 401 response is produced by the auth middleware **before** the
+        request reaches the endpoint handler, so it does **not** follow the
+        standard `{errors: [...]}` envelope. Instead the body is a bare
+        `{message: string}` object with no `code`, no `errors` array. Callers
+        handling 401s should key off the HTTP status and the `message` string,
+        not try to destructure an `errors[]`.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                description: |-
+                  Human-readable description of the auth failure. Known values:
+                  - `"Unauthorized"` — no `Authorization` header on the request.
+                  - `"Bearer Authentication Failed"` — header present but token
+                    is invalid, revoked, or expired.
+            required:
+              - message
+          examples:
+            missing_token:
+              summary: No Authorization header sent
+              value:
+                message: Unauthorized
+            invalid_token:
+              summary: Bearer token invalid or revoked
+              value:
+                message: Bearer Authentication Failed
+    403-forbidden:
+      description: |
+        Forbidden. The authenticated caller does not have permission to perform this operation.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: forbidden
+                    message: You do not have permission to access this resource.
+x-enable-proxy: true
+x-internal: false