@celigo/api-specs 0.2.1

package/dist/integration.yml

@@ -0,0 +1,4406 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: Integrations
+  description: API for managing Celigo integrations — the top-level containers that group flows, connections, and other resources into one unit.
+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: Integrations
+    description: |-
+      Integrations are the top-level containers that group flows, connections, exports,
+      imports, and other resources into a logical unit. Each integration appears as a tile
+      on the Celigo Home page.
+
+      Two flavors exist:
+      - **Standard integrations** — user-created containers that group custom flows.
+      - **Integration App installations** — created from a published connector/template,
+        with install/uninstall steps, settings forms, editions, and optional child
+        integrations. These have `_connectorId` and `_templateId` set.
+
+      Integrations support **Integration Lifecycle Management (ILM)**: clone an integration
+      across environments, then use revisions (snapshot, pull, revert) to promote changes
+      between them. Lifecycle operations carry every resource the integration contains.
+
+      ## Integration schema
+
+      {% openapi-schemas spec="integration" schemas="Integration" grouped="true" %}
+paths:
+  /v1/integrations:
+    get:
+      x-internal: false
+      summary: List integrations
+      description: Returns all integrations in the account. Supports field projection via `include`/`exclude`.
+      operationId: listIntegrations
+      tags:
+        - Integrations
+      parameters:
+        - $ref: '#/components/parameters/Include'
+        - $ref: '#/components/parameters/Exclude'
+        - name: limit
+          in: query
+          required: false
+          description: Maximum number of integrations to return per page. When more results exist, the response includes a `Link` header with a `rel="next"` URL.
+          schema:
+            type: integer
+            minimum: 1
+            examples:
+              - 100
+      responses:
+        '200':
+          description: Successfully retrieved list of integrations.
+          headers:
+            Link:
+              description: |
+                RFC-5988 pagination links. When more pages remain, includes a `<...>; rel="next"` entry;
+                absent on the final page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Integration'
+              examples:
+                default:
+                  value:
+                    - _id: 6842261335b64c0bcb308e4f
+                      name: Shopify → NetSuite Orders
+                      description: Syncs orders, customers, and inventory between Shopify and NetSuite.
+                      mode: settings
+                      sandbox: false
+                      _registeredConnectionIds:
+                        - 626168f90b6ef816b50c82d7
+                        - 6553ebdeda62bb22e7fa81ff
+                      install: []
+                      installSteps: []
+                      uninstallSteps: []
+                      changeEditionSteps: []
+                      flowGroupings: []
+                      apiGroupings: []
+                      createdAt: '2025-06-05T23:19:47.141Z'
+                      lastModified: '2026-05-02T01:02:27.378Z'
+        '204':
+          description: No integrations exist in the account
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+    post:
+      x-internal: false
+      summary: Create an integration
+      description: |-
+        Creates a new integration. Only `name` is required — the server populates all other
+        fields with defaults. Do not include Integration App fields (`_connectorId`, `_templateId`,
+        `install`, `installSteps`, etc.) unless you are creating an IA installation.
+      operationId: createIntegration
+      tags:
+        - Integrations
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              minimal:
+                summary: Minimal create
+                value:
+                  name: Shopify → NetSuite Orders
+              with_description:
+                summary: With description
+                value:
+                  name: Shopify → NetSuite Orders
+                  description: Syncs orders, customers, and inventory between Shopify and NetSuite.
+      responses:
+        '201':
+          description: Integration created successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Integration'
+              examples:
+                created:
+                  summary: Created integration with server-defaulted empty arrays
+                  value:
+                    _id: 6842261335b64c0bcb308e4f
+                    name: Shopify → NetSuite Orders
+                    description: Syncs orders, customers, and inventory between Shopify and NetSuite.
+                    sandbox: false
+                    install: []
+                    installSteps: []
+                    uninstallSteps: []
+                    changeEditionSteps: []
+                    flowGroupings: []
+                    apiGroupings: []
+                    _registeredConnectionIds: []
+                    _registeredLookupCacheIds: []
+                    createdAt: '2025-06-05T23:19:47.141Z'
+                    lastModified: '2025-06-05T23:19:47.141Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/integrations/{_id}:
+    get:
+      x-internal: false
+      summary: Get an integration
+      operationId: getIntegration
+      tags:
+        - Integrations
+      description: Returns the full integration object.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+      responses:
+        '200':
+          description: Successfully retrieved integration.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Integration'
+              examples:
+                standard:
+                  summary: Standard integration
+                  value:
+                    _id: 6842261335b64c0bcb308e4f
+                    name: Shopify → NetSuite Orders
+                    description: Syncs orders, customers, and inventory.
+                    mode: settings
+                    sandbox: false
+                    _registeredConnectionIds:
+                      - 626168f90b6ef816b50c82d7
+                    install: []
+                    installSteps: []
+                    uninstallSteps: []
+                    changeEditionSteps: []
+                    flowGroupings:
+                      - _id: 69d42d09b9c28ea0b7e7c0c0
+                        name: Order sync
+                    apiGroupings: []
+                    createdAt: '2025-06-05T23:19:47.141Z'
+                    lastModified: '2026-05-02T01:02:27.378Z'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    put:
+      x-internal: false
+      summary: Update an integration
+      operationId: updateIntegration
+      tags:
+        - Integrations
+      description: |-
+        Replaces the integration's mutable fields. Send the full object -- omitted fields revert to
+        defaults. GET the integration first, modify the fields you need, then PUT back. For partial
+        updates to `settings`, `flowGroupings`, or `apiGroupings`, prefer PATCH with JSON Patch
+        instead.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              full_replace:
+                summary: Full replace — send every field you want to keep
+                value:
+                  name: Shopify → NetSuite Orders
+                  description: Syncs orders, customers, and inventory between Shopify and NetSuite.
+                  mode: settings
+                  flowGroupings:
+                    - name: Order sync
+      responses:
+        '200':
+          description: Integration updated successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Integration'
+              examples:
+                updated:
+                  summary: Updated integration
+                  value:
+                    _id: 6842261335b64c0bcb308e4f
+                    name: Shopify → NetSuite Orders
+                    description: Syncs orders, customers, and inventory between Shopify and NetSuite.
+                    mode: settings
+                    sandbox: false
+                    _registeredConnectionIds:
+                      - 626168f90b6ef816b50c82d7
+                    install: []
+                    installSteps: []
+                    uninstallSteps: []
+                    changeEditionSteps: []
+                    flowGroupings:
+                      - _id: 69d42d09b9c28ea0b7e7c0c0
+                        name: Order sync
+                    apiGroupings: []
+                    createdAt: '2025-06-05T23:19:47.141Z'
+                    lastModified: '2026-06-09T17:32:31.412Z'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    patch:
+      x-internal: false
+      summary: Patch an integration
+      description: |-
+        Partially updates an integration using a JSON Patch document (RFC 6902).
+        Only the `replace` operation is supported, and only on the following
+        whitelisted paths:
+
+        | Path | Description |
+        |------|-------------|
+        | `/settings` | Integration settings object |
+        | `/flowGroupings` | Flow grouping configuration |
+        | `/apiGroupings` | API grouping configuration |
+
+        All other paths are rejected with `422`.
+      operationId: patchIntegration
+      tags:
+        - Integrations
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/JsonPatchRequest'
+            examples:
+              update_settings:
+                summary: Update integration settings
+                value:
+                  - op: replace
+                    path: /settings
+                    value:
+                      region: us-west-2
+      responses:
+        '204':
+          description: Integration patched successfully
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    delete:
+      x-internal: false
+      summary: Delete an integration
+      operationId: deleteIntegration
+      tags:
+        - Integrations
+      description: |-
+        Deletes an integration. The integration is soft-deleted and retained in the
+        recycle bin for 30 days before permanent removal.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+      responses:
+        '204':
+          description: integration deleted successfully
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-dependency-conflict'
+  /v1/integrations/{_id}/clone:
+    post:
+      x-internal: false
+      summary: Clone an integration
+      description: |
+        Creates a copy of an existing integration.
+        Supports optionally remapping referenced connections (via connectionMap).
+      operationId: cloneIntegration
+      tags:
+        - Integrations
+      parameters:
+        - name: _id
+          in: path
+          description: The unique identifier of the integration to clone
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 69680d7111d1437fbcbce534
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CloneRequest'
+            examples:
+              cross_env_clone:
+                summary: Clone into another environment, remapping both connections
+                value:
+                  _envId: 67b123456789abcdef012345
+                  connectionMap:
+                    626168f90b6ef816b50c82d7: 64a1234567890abcdef12345
+                    6553ebdeda62bb22e7fa81ff: 64a1234567890abcdef12346
+      responses:
+        '200':
+          description: Integration cloned successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CloneResponse'
+              examples:
+                manifest:
+                  summary: Manifest of created resources — mapped connections are reused, not cloned
+                  value:
+                    - model: Integration
+                      _id: 68f52162f00a35a1b26eaafb
+                      name: Clone - Shopify → NetSuite Orders
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/clone/preview:
+    get:
+      x-internal: false
+      summary: Preview cloning an integration
+      description: |
+        Returns a preview of the resources that would be created by cloning the specified integration.
+        The response includes the integration and all transitive dependencies — flows, connections,
+        exports, imports, scripts, async helpers, lookup caches, and tools.
+        No resources are created by this endpoint.
+      operationId: previewCloneIntegration
+      tags:
+        - Integrations
+      parameters:
+        - name: _id
+          in: path
+          description: The unique identifier of the integration to preview cloning
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 69680d7111d1437fbcbce534
+      responses:
+        '200':
+          description: Clone preview retrieved successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ClonePreviewResponse'
+              examples:
+                preview:
+                  summary: Integration with one flow and its transitive dependencies
+                  value:
+                    objects:
+                      - model: Integration
+                        doc:
+                          _id: 6842261335b64c0bcb308e4f
+                          name: Shopify → NetSuite Orders
+                      - model: Flow
+                        doc:
+                          _id: 69f54d6b7009ea11abad707a
+                          name: Shopify orders → NetSuite
+                          _integrationId: 6842261335b64c0bcb308e4f
+                      - model: Export
+                        doc:
+                          _id: 69f54d6a3469e3f5597848a1
+                          name: Shopify new orders
+                          _connectionId: 626168f90b6ef816b50c82d7
+                      - model: Import
+                        doc:
+                          _id: 69f54d6c1e7f3a22cc7848b2
+                          name: NetSuite sales orders
+                          _connectionId: 6553ebdeda62bb22e7fa81ff
+                      - model: Connection
+                        doc:
+                          _id: 626168f90b6ef816b50c82d7
+                          name: Shopify storefront
+                          type: http
+                      - model: Tool
+                        doc:
+                          _id: 69d462d5b9c28ea0b7f82522
+                          name: Get Shopify Order
+                          _integrationId: 6842261335b64c0bcb308e4f
+                    stackRequired: false
+                    _stackId: null
+        '400':
+          description: The `_id` is not a valid ObjectId.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_ref:
+                  summary: Invalid ObjectId format
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _id.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/revisions:
+    get:
+      x-internal: false
+      operationId: listIntegrationRevisions
+      tags:
+        - Integrations
+      summary: List revisions for an integration
+      description: |-
+        Returns every revision entry (snapshots, pulls, reverts) for the integration, newest first.
+        An integration with no revision history returns an empty response (204), not `[]`.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+      responses:
+        '200':
+          description: Revision history, newest first.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RevisionsResponse'
+              examples:
+                one_snapshot:
+                  summary: History with one completed snapshot
+                  value:
+                    - _id: 6a28d2af6d42eb08f8e863e7
+                      type: snapshot
+                      status: completed
+                      description: Stable baseline before deploying v2
+                      _integrationId: 6842261335b64c0bcb308e4f
+                      _fromIntegrationId: 6842261335b64c0bcb308e4f
+                      fromIntegrationName: Shopify → NetSuite Orders
+                      beforeRevisionHash: 34b7ae8d56563e242bc0bd42fd28874442657e58
+                      sandbox: false
+                      _createdByUserId: 624774a6a7574d3ed9f9a5cc
+                      installSteps: []
+                      createdAt: '2026-06-10T02:57:51.483Z'
+                      lastModified: '2026-06-10T02:57:51.483Z'
+        '204':
+          description: No revisions exist for this integration.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/revisions/{_revisionId}:
+    get:
+      x-internal: false
+      operationId: getIntegrationRevision
+      tags:
+        - Integrations
+      summary: Get a revision
+      description: |-
+        Returns the full revision record. The list endpoint already surfaces every field, so this is
+        primarily useful when you have a `_revisionId` in hand (e.g. from a webhook, audit log, or
+        external reference) and want to verify state without re-listing.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+        - name: _revisionId
+          in: path
+          required: true
+          description: Revision id.
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 6a28d2af6d42eb08f8e863e7
+      responses:
+        '200':
+          description: Revision record.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Revision'
+              examples:
+                snapshot:
+                  summary: Completed snapshot revision
+                  value:
+                    _id: 6a28d2af6d42eb08f8e863e7
+                    type: snapshot
+                    status: completed
+                    description: Stable baseline before deploying v2
+                    _integrationId: 6842261335b64c0bcb308e4f
+                    _fromIntegrationId: 6842261335b64c0bcb308e4f
+                    fromIntegrationName: Shopify → NetSuite Orders
+                    beforeRevisionHash: 34b7ae8d56563e242bc0bd42fd28874442657e58
+                    sandbox: false
+                    _createdByUserId: 624774a6a7574d3ed9f9a5cc
+                    installSteps: []
+                    createdAt: '2026-06-10T02:57:51.483Z'
+                    lastModified: '2026-06-10T02:57:51.483Z'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/revisions/create:
+    post:
+      x-internal: false
+      operationId: createIntegrationRevision
+      tags:
+        - Integrations
+      summary: Create a snapshot revision
+      description: |-
+        Takes a point-in-time snapshot of the integration's current state and writes it to the revision
+        history. The returned revision has `type: snapshot` and `status: completed` immediately --
+        snapshots are synchronous and do not require an apply step. This is the only revision type
+        that can be created via the public API; `pull` and `revert` revisions require the Celigo UI.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RevisionCreateRequest'
+            examples:
+              default:
+                value:
+                  description: Stable baseline before deploying v2
+      responses:
+        '201':
+          description: Snapshot revision created.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Revision'
+              examples:
+                snapshot_created:
+                  summary: Snapshot revision — completed immediately
+                  value:
+                    _id: 6a28d2af6d42eb08f8e863e7
+                    type: snapshot
+                    status: completed
+                    description: Stable baseline before deploying v2
+                    _integrationId: 6842261335b64c0bcb308e4f
+                    _fromIntegrationId: 6842261335b64c0bcb308e4f
+                    fromIntegrationName: Shopify → NetSuite Orders
+                    beforeRevisionHash: 34b7ae8d56563e242bc0bd42fd28874442657e58
+                    sandbox: false
+                    _createdByUserId: 624774a6a7574d3ed9f9a5cc
+                    installSteps: []
+                    createdAt: '2026-06-10T02:57:51.483Z'
+                    lastModified: '2026-06-10T02:57:51.483Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/revisions/{_revisionId}/diff:
+    get:
+      x-internal: false
+      operationId: getIntegrationRevisionDiff
+      tags:
+        - Integrations
+      summary: Diff a pending revision
+      description: |-
+        Returns the before/after diff for a pull or revert revision. The diff is materialized on `pull`
+        and `revert` revisions and is retained on their `completed` state -- available for both
+        `inprogress` and `completed` pull/revert revisions. Snapshot revisions are not diffable
+        (there is no source integration to diff against), and `canceled` revisions drop their diff.
+
+        The response body is a `{before, after}` envelope where each side is a map keyed by resource
+        type (e.g. `flow`, `export`, `connection`, `api`, `tool`) whose values are maps of resourceId
+        to full resource snapshot.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+        - name: _revisionId
+          in: path
+          required: true
+          description: Revision id. Must be a `pull` or `revert` revision in `inprogress` or `completed` state.
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 6a28d2af6d42eb08f8e863e7
+      responses:
+        '200':
+          description: Diff envelope for the pending revision.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RevisionDiffResponse'
+              examples:
+                flow_change:
+                  summary: Pull revision that re-enables a flow
+                  value:
+                    before:
+                      flow:
+                        69f54d6b7009ea11abad707a:
+                          name: Shopify orders → NetSuite
+                          disabled: true
+                    after:
+                      flow:
+                        69f54d6b7009ea11abad707a:
+                          name: Shopify orders → NetSuite
+                          disabled: false
+        '400':
+          description: |-
+            Revision is not in a diffable state. Error code `invalid_revision_state`. Occurs on
+            snapshot revisions (no source to diff against), `canceled` revisions (diff dropped), and
+            `inprogress` revisions whose install steps haven't materialized yet.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_revision_state:
+                  value:
+                    errors:
+                      - message: Failed to perform operation. Revision is in an invalid state
+                        code: invalid_revision_state
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/errors:
+    get:
+      x-internal: false
+      operationId: listIntegrationErrors
+      tags:
+        - Integrations
+      summary: Summarize open errors across an integration's flows
+      description: |-
+        Returns a per-flow count of currently open (unresolved) errors for every flow in the integration.
+        Flows with zero open errors still appear so callers see the full flow roster; `lastErrorAt` is
+        only populated when `numError > 0`. Entries do not contain individual error ids -- to get
+        actionable error records, drill into `GET /v1/flows/{_flowId}/{_stepId}/errors` for each flow
+        and step.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+      responses:
+        '200':
+          description: Per-flow open-error summary.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IntegrationErrorsResponse'
+              examples:
+                mixed:
+                  summary: Integration with mixed flows (one with errors, two clean)
+                  value:
+                    - _flowId: 69497fc443fc1f9a03d31bd9
+                      numError: 2
+                      lastErrorAt: '2026-04-12T21:51:39.257Z'
+                    - _flowId: 6949809c3f70c4486d2dae88
+                      numError: 0
+                    - _flowId: 683b8ef5774ae78d3b9b8a89
+                      numError: 0
+        '204':
+          description: Integration has no flows with any reported error state.
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/errors/assign:
+    put:
+      x-internal: false
+      operationId: assignIntegrationErrors
+      tags:
+        - Integrations
+      summary: (Legacy) Assign open errors to a user across an integration
+      description: |-
+        Tags a batch of open errors with an assignee. Errors stay open; this does not resolve or retry
+        them. The `email` must resolve to a user with access to the account.
+
+        Prefer `PUT /v1/flows/{_flowId}/{_stepId}/errors/assign` instead -- it works with a plain
+        bearer token and requires no extra headers. This integration-level endpoint requires an
+        `integrator-ashareid` header, and account-owner PATs have no ashare pointing at themselves, so
+        they cannot call it directly.
+      parameters:
+        - name: integrator-ashareid
+          in: header
+          required: false
+          description: |-
+            Account-share id scoping the request to a specific shared-account context. Only accepted
+            when the bearer token's user is the `sharedWithUser` of that ashare. Not required by the
+            per-step fallback — prefer that endpoint instead.
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 6798f4dc43db9184f4bc8ee0
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/IntegrationErrorsAssignRequest'
+            examples:
+              default:
+                value:
+                  errorIds:
+                    - '6044134138'
+                    - '6027562904'
+                  email: user@example.com
+      responses:
+        '200':
+          description: Errors assigned. Body echoes which ids were affected.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IntegrationErrorsAssignResponse'
+              examples:
+                default:
+                  value:
+                    errorsToReturn:
+                      - '6044134138'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: |-
+            `integrator-ashareid` is malformed (not a 24-char hex id). Error code:
+            `invalid_header_value`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_header_value:
+                  value:
+                    errors:
+                      - code: invalid_header_value
+                        message: The value provided for request header Integrator-AShareId is invalid.
+        '404':
+          description: |-
+            Either the integration is unknown, no `integrator-ashareid` was sent (code: `invalid_ref`,
+            message: "Integration not found."), or the header references a share whose `sharedWithUser`
+            isn't the bearer token's user (code: `access_restricted`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_ref:
+                  summary: No ashare header sent
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Integration not found.
+  /v1/integrations/{_id}/clonefamily:
+    get:
+      x-internal: false
+      operationId: listIntegrationCloneFamily
+      tags:
+        - Integrations
+      summary: List an integration's clone family
+      description: |-
+        Returns every member of the integration's clone family -- the original plus every clone
+        (recursively, across environments). Used by ILM to decide which integrations can be pull/push
+        sources or targets for the current integration.
+
+        This endpoint requires the `integrator-ashareid` header to establish a shared-account context.
+        For simpler clone-relationship lookups, the integration's own `_sourceId` field points to the
+        parent it was cloned from, and `GET /v1/integrations?_sourceId=<id>` lists the children.
+      parameters:
+        - name: integrator-ashareid
+          in: header
+          required: true
+          description: |-
+            Account-share id that scopes the request to a specific shared-account context. The bearer
+            token's user must be the `sharedWithUser` of this ashare.
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 6798f4dc43db9184f4bc8ee0
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+      responses:
+        '200':
+          description: Clone family members.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CloneFamilyResponse'
+              examples:
+                family:
+                  summary: Original integration plus one clone in another environment
+                  value:
+                    - _id: 6842261335b64c0bcb308e4f
+                      name: Shopify → NetSuite Orders
+                    - _id: 68f52162f00a35a1b26eaafb
+                      name: Clone - Shopify → NetSuite Orders
+                      _envId: 67b123456789abcdef012345
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: |-
+            Either the `integrator-ashareid` header is malformed (code: `invalid_header_value`) or it
+            was omitted entirely (code: `get_not_allowed`, "GET resource not allowed for the given
+            model.").
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                get_not_allowed:
+                  summary: Header omitted entirely
+                  value:
+                    errors:
+                      - code: get_not_allowed
+                        message: GET resource not allowed for the given model.
+                invalid_header_value:
+                  summary: Header malformed (not a 24-char hex id)
+                  value:
+                    errors:
+                      - code: invalid_header_value
+                        message: The value provided for request header Integrator-AShareId is invalid.
+        '404':
+          description: |-
+            Integration unknown, or the `integrator-ashareid` references a share whose `sharedWithUser`
+            isn't the bearer token's user (code: `access_restricted`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                access_restricted:
+                  value:
+                    errors:
+                      - code: access_restricted
+                        message: Your access to an integrator.io environment or account has been disabled. For more information, contact account administrator.
+  /v1/integrations/{_id}/flows:
+    get:
+      x-internal: false
+      operationId: listIntegrationFlows
+      tags:
+        - Integrations
+      summary: List flows belonging to an integration
+      description: |-
+        Returns a bare array of full flow objects for every flow in the integration. Each element
+        is a complete flow resource, the same shape as `GET /v1/flows/{_id}`.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+        - name: limit
+          in: query
+          required: false
+          description: Maximum number of flow objects to return.
+          schema:
+            type: integer
+            minimum: 1
+            examples:
+              - 100
+        - name: includeInstances
+          in: query
+          required: false
+          description: |-
+            When true, instance flows generated from abstract (multi-instance)
+            flows are included in the results, which otherwise list only
+            regular and abstract flows.
+          schema:
+            type: boolean
+      responses:
+        '200':
+          description: Array of flow objects.
+          content:
+            application/json:
+              schema:
+                type: array
+                description: Bare array of full flow resource objects.
+                items:
+                  type: object
+                  description: A flow resource. Same shape as returned by `GET /v1/flows/{_id}`.
+              examples:
+                one_flow:
+                  summary: Integration with one flow
+                  value:
+                    - _id: 69f54d6b7009ea11abad707a
+                      name: Shopify orders → NetSuite
+                      _integrationId: 6842261335b64c0bcb308e4f
+                      disabled: false
+                      pageGenerators:
+                        - _exportId: 69f54d6a3469e3f5597848a1
+                      pageProcessors:
+                        - type: import
+                          _importId: 69f54d6c1e7f3a22cc7848b2
+                      createdAt: '2026-05-02T01:03:39.871Z'
+                      lastModified: '2026-05-02T01:03:39.871Z'
+        '204':
+          description: Integration has no flows.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/imports:
+    get:
+      x-internal: false
+      operationId: listIntegrationImports
+      tags:
+        - Integrations
+      summary: List imports belonging to an integration
+      description: |-
+        Returns a bare array of full import objects for every import in the integration. Each element
+        is a complete import resource, the same shape as `GET /v1/imports/{_id}`.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+        - name: limit
+          in: query
+          required: false
+          description: |-
+            Maximum number of import objects to return. **Bug:** the server returns N+1 items for a
+            `limit=N` value.
+          schema:
+            type: integer
+            minimum: 1
+            examples:
+              - 100
+      responses:
+        '200':
+          description: Array of import objects.
+          content:
+            application/json:
+              schema:
+                type: array
+                description: Bare array of full import resource objects.
+                items:
+                  type: object
+                  description: An import resource. Same shape as returned by `GET /v1/imports/{_id}`.
+              examples:
+                one_import:
+                  summary: Integration with one import
+                  value:
+                    - _id: 69f54d6c1e7f3a22cc7848b2
+                      name: NetSuite sales orders
+                      _connectionId: 6553ebdeda62bb22e7fa81ff
+                      adaptorType: NetSuiteDistributedImport
+                      distributed: true
+                      netsuite_da:
+                        recordType: salesorder
+                        operation: add
+                      createdAt: '2026-05-02T01:03:40.027Z'
+                      lastModified: '2026-05-02T01:03:40.027Z'
+        '204':
+          description: Integration has no imports.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/exports:
+    get:
+      x-internal: false
+      operationId: listIntegrationExports
+      tags:
+        - Integrations
+      summary: List exports belonging to an integration
+      description: |-
+        Returns a bare array of full export objects for every export in the integration. Each element
+        is a complete export resource, the same shape as `GET /v1/exports/{_id}`.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+        - name: limit
+          in: query
+          required: false
+          description: |-
+            Maximum number of export objects to return. **Bug:** the server returns N+1 items for a
+            `limit=N` value.
+          schema:
+            type: integer
+            minimum: 1
+            examples:
+              - 100
+      responses:
+        '200':
+          description: Array of export objects.
+          content:
+            application/json:
+              schema:
+                type: array
+                description: Bare array of full export resource objects.
+                items:
+                  type: object
+                  description: An export resource. Same shape as returned by `GET /v1/exports/{_id}`.
+              examples:
+                one_export:
+                  summary: Integration with one export
+                  value:
+                    - _id: 69f54d6a3469e3f5597848a1
+                      name: Shopify new orders
+                      _connectionId: 626168f90b6ef816b50c82d7
+                      adaptorType: HTTPExport
+                      http:
+                        relativeURI: /admin/api/2024-04/orders.json
+                        method: GET
+                      createdAt: '2026-05-02T01:03:38.214Z'
+                      lastModified: '2026-05-02T01:03:38.214Z'
+        '204':
+          description: Integration has no exports.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/connections:
+    get:
+      x-internal: false
+      operationId: listIntegrationConnections
+      tags:
+        - Integrations
+      summary: List connections belonging to an integration
+      description: |-
+        Returns a bare array of full connection objects for every connection registered to the
+        integration. Each element is a complete connection resource, the same shape as
+        `GET /v1/connections/{_id}`. Unlike the flows/imports/exports sub-resource endpoints, this
+        endpoint rejects unknown integration ids with a 404.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+        - name: limit
+          in: query
+          required: false
+          description: Maximum number of connection objects to return.
+          schema:
+            type: integer
+            minimum: 1
+            examples:
+              - 100
+      responses:
+        '200':
+          description: Array of connection objects.
+          content:
+            application/json:
+              schema:
+                type: array
+                description: Bare array of full connection resource objects.
+                items:
+                  type: object
+                  description: A connection resource. Same shape as returned by `GET /v1/connections/{_id}`.
+              examples:
+                one_connection:
+                  summary: Integration with one registered connection
+                  value:
+                    - _id: 626168f90b6ef816b50c82d7
+                      name: Shopify storefront
+                      type: http
+                      sandbox: false
+                      http:
+                        formType: rest
+                        mediaType: json
+                        baseURI: https://celigo-demo.myshopify.com
+                        auth:
+                          type: basic
+                      createdAt: '2022-04-21T14:23:53.118Z'
+                      lastModified: '2026-05-02T01:02:27.378Z'
+        '204':
+          description: Integration has no connections.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/asynchelpers:
+    get:
+      x-internal: false
+      operationId: listIntegrationAsyncHelpers
+      tags:
+        - Integrations
+      summary: List async helpers belonging to an integration
+      description: |-
+        Returns a bare array of async-helper objects for every async helper registered to the
+        integration. Each element is a complete async-helper resource, the same shape as
+        `GET /v1/asynchelpers/{_id}`.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+      responses:
+        '200':
+          description: Array of async-helper objects.
+          content:
+            application/json:
+              schema:
+                type: array
+                description: Bare array of full async-helper resource objects.
+                items:
+                  type: object
+                  description: An async-helper resource. Same shape as returned by `GET /v1/asynchelpers/{_id}`.
+              examples:
+                one_helper:
+                  summary: Integration with one async helper
+                  value:
+                    - _id: 64a1b2c3d4e5f60011223344
+                      name: Salesforce Bulk Query Helper
+                      http:
+                        submit:
+                          sameAsStatus: true
+                        status:
+                          _exportId: 63b1c2d3e4f5a60011334455
+                          statusPath: status
+                          initialWaitTime: 1
+                          pollWaitTime: 4
+                      lastModified: '2026-04-15T14:30:15Z'
+        '204':
+          description: Integration has no async helpers.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/ashares:
+    get:
+      x-internal: false
+      operationId: listIntegrationAshares
+      tags:
+        - Integrations
+      summary: List account shares for an integration
+      description: |-
+        Returns an array of account-share (ashare) objects for the integration. Each entry describes a
+        user who has been granted access to the integration's owning account, along with their access
+        level and authentication metadata. Unlike other integration sub-resource list endpoints, this
+        always returns an array (an integration with no shares returns `[]`).
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+      responses:
+        '200':
+          description: Array of account-share objects.
+          content:
+            application/json:
+              schema:
+                type: array
+                description: Account shares scoped to the integration.
+                items:
+                  type: object
+                  properties:
+                    _id:
+                      type: string
+                      format: objectId
+                      description: Ashare id.
+                      examples:
+                        - 6798f4dc43db9184f4bc8ee0
+                    accepted:
+                      type: boolean
+                      description: When true, the shared user has accepted the invitation.
+                    accessLevel:
+                      type: string
+                      description: Access level granted to the user (e.g. `administrator`, `manage`, `monitor`).
+                      examples:
+                        - administrator
+                    accountSSORequired:
+                      type: boolean
+                      description: When true, the account requires SSO for this user.
+                    accountMFARequired:
+                      type: boolean
+                      description: When true, the account requires MFA for this user.
+                    createdAt:
+                      type: string
+                      format: date-time
+                      examples:
+                        - '2025-01-28T15:16:44.327Z'
+                    lastModified:
+                      type: string
+                      format: date-time
+                      examples:
+                        - '2026-05-02T17:02:59.371Z'
+                    lastSignIn:
+                      type: string
+                      format: date-time
+                      examples:
+                        - '2026-05-02T17:02:59.370Z'
+                    isProductionAdmin:
+                      type: boolean
+                    sharedWithUser:
+                      type: object
+                      description: The user this share was granted to.
+                      properties:
+                        _id:
+                          type: string
+                          format: objectId
+                          examples:
+                            - 624774a6a7574d3ed9f9a5cc
+                        email:
+                          type: string
+                          format: email
+                          examples:
+                            - admin@example.com
+                        name:
+                          type: string
+                          examples:
+                            - Account Admin
+                        lastSignIn:
+                          type: string
+                          format: date-time
+                          examples:
+                            - '2026-05-02T17:02:59.370Z'
+                        allowedToResetMFA:
+                          type: boolean
+                        accountSSOLinked:
+                          type: boolean
+              examples:
+                two_shares:
+                  summary: Two users with access to the integration's account
+                  value:
+                    - _id: 6798f4dc43db9184f4bc8ee0
+                      accepted: true
+                      accessLevel: administrator
+                      accountSSORequired: false
+                      accountMFARequired: false
+                      isProductionAdmin: true
+                      createdAt: '2025-01-28T15:16:44.327Z'
+                      lastModified: '2026-05-02T17:02:59.371Z'
+                      lastSignIn: '2026-05-02T17:02:59.370Z'
+                      sharedWithUser:
+                        _id: 624774a6a7574d3ed9f9a5cc
+                        email: admin@example.com
+                        name: Account Admin
+                        allowedToResetMFA: false
+                    - _id: 690954729ef09ab572f65e5d
+                      accepted: true
+                      accessLevel: monitor
+                      accountSSORequired: false
+                      accountMFARequired: false
+                      createdAt: '2025-11-04T01:18:42.025Z'
+                      lastModified: '2026-04-09T18:48:15.653Z'
+                      sharedWithUser:
+                        _id: 69095422a6fa76e8c7c170eb
+                        email: contributor@example.com
+                        name: Integration User
+                        allowedToResetMFA: false
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/connections/{_connectionId}/register:
+    put:
+      x-internal: false
+      operationId: registerConnectionToIntegration
+      tags:
+        - Integrations
+      summary: Register a connection to an integration (by path)
+      description: |-
+        Registers a single connection to the integration by specifying the connection id in the URL
+        path. No request body is needed. To unregister, use `DELETE` on the same path. Alternatively,
+        use `PUT /v1/integrations/{_id}/connections/register` to register by request body.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+        - name: _connectionId
+          in: path
+          required: true
+          description: Connection id to register.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: connections
+            examples:
+              - 626168f90b6ef816b50c82d7
+      responses:
+        '204':
+          description: Connection registered successfully. No body returned.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    delete:
+      x-internal: false
+      operationId: unregisterConnectionFromIntegration
+      tags:
+        - Integrations
+      summary: Unregister a connection from an integration
+      description: |-
+        Removes a connection's registration from the integration. This does not delete the connection
+        itself -- it only removes it from the integration's registered-connections list.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+        - name: _connectionId
+          in: path
+          required: true
+          description: Connection id to unregister.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: connections
+            examples:
+              - 626168f90b6ef816b50c82d7
+      responses:
+        '204':
+          description: Connection unregistered successfully. No body returned.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/connections/register:
+    put:
+      x-internal: false
+      operationId: registerConnectionToIntegrationByBody
+      tags:
+        - Integrations
+      summary: Register a connection to an integration (by body)
+      description: |-
+        Registers a single connection to the integration by passing the connection id in the request
+        body. Alternatively, use `PUT /v1/integrations/{_id}/connections/{_connectionId}/register` to
+        register by path parameter.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - _connectionId
+              properties:
+                _connectionId:
+                  type: string
+                  format: objectId
+                  x-celigo-refModel: connections
+                  examples:
+                    - 626168f90b6ef816b50c82d7
+                  description: The id of the connection to register.
+            examples:
+              default:
+                value:
+                  _connectionId: 69680d7111d1437fbcbce534
+      responses:
+        '204':
+          description: Connection registered successfully. No body returned.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/lookupcaches/{_lookupCacheId}/register:
+    put:
+      x-internal: false
+      operationId: registerLookupCacheToIntegration
+      tags:
+        - Integrations
+      summary: Register a lookup cache to an integration (by path)
+      description: |-
+        Registers a single lookup cache to the integration by specifying the
+        lookup cache id in the URL path. No request body is needed. To
+        unregister, use `DELETE` on the same path. Alternatively, use
+        `PUT /v1/integrations/{_id}/lookupcaches/register` to register several
+        caches at once by request body.
+
+        Registration also adds an entry to the integration's `aliases[]` when the
+        cache does not already have one: `alias` is a slug of the cache name
+        (lowercased, whitespace and special characters stripped, `_2`/`_3`/…
+        appended on collision) and `_lookupCacheId` points at the cache. Scripts
+        and hooks use the alias as a stable handle for the cache, and
+        deregistering the cache is blocked until the alias is removed.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+        - name: _lookupCacheId
+          in: path
+          required: true
+          description: Lookup cache id to register.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: lookupcaches
+            examples:
+              - 68680d7111d1437fbcbce534
+      responses:
+        '204':
+          description: Lookup cache registered successfully. No body returned.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    delete:
+      x-internal: false
+      operationId: unregisterLookupCacheFromIntegration
+      tags:
+        - Integrations
+      summary: Unregister a lookup cache from an integration
+      description: |-
+        Removes a lookup cache's registration from the integration. This does
+        not delete the lookup cache itself — it only removes it from the
+        integration's `_registeredLookupCacheIds` list. Fails when the cache is
+        not registered on the integration, when a flow step in the integration
+        still references it, or when an alias on the integration (or one of its
+        flows) still points at it — including the alias that registration itself
+        created. Remove the flow-step references and the alias (update the
+        `aliases` array on the integration or flow) first, then retry.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+        - name: _lookupCacheId
+          in: path
+          required: true
+          description: Lookup cache id to unregister.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: lookupcaches
+            examples:
+              - 68680d7111d1437fbcbce534
+      responses:
+        '204':
+          description: Lookup cache unregistered successfully. No body returned.
+        '400':
+          description: |-
+            The cache is not registered on this integration ("The lookup cache
+            which you are trying to deregister is not registered on the
+            integration."), is still referenced by a flow step in the
+            integration ("The lookup cache is being actively used by a flow
+            step in this integration..."), or is still referenced by an alias
+            ("The lookup cache is referenced by an alias in this integration.
+            Remove the alias before deregistering."). Error code: `not_allowed`
+            for all three.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                in_use:
+                  value:
+                    errors:
+                      - code: not_allowed
+                        message: The lookup cache is being actively used by a flow step in this integration. Please remove the lookup cache reference from all flow steps before deregistering.
+                alias_referenced:
+                  value:
+                    errors:
+                      - code: not_allowed
+                        message: The lookup cache is referenced by an alias in this integration. Remove the alias before deregistering.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/lookupcaches/register:
+    put:
+      x-internal: false
+      operationId: registerLookupCachesToIntegration
+      tags:
+        - Integrations
+      summary: Register lookup caches to an integration (by body)
+      description: |-
+        Registers one or more lookup caches to the integration, adding them to
+        its `_registeredLookupCacheIds` list. The request body is a bare JSON
+        array of lookup cache ids; duplicates are collapsed. Alternatively, use
+        `PUT /v1/integrations/{_id}/lookupcaches/{_lookupCacheId}/register` to
+        register a single cache by path parameter.
+
+        Registration also adds an entry to the integration's `aliases[]` for each
+        newly registered cache that does not already have one: `alias` is a slug
+        of the cache name (lowercased, whitespace and special characters stripped,
+        `_2`/`_3`/… appended on collision) and `_lookupCacheId` points at the
+        cache. Scripts and hooks use the alias as a stable handle for the cache,
+        and deregistering the cache is blocked until the alias is removed.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: array
+              description: Lookup cache ids to register.
+              items:
+                type: string
+                format: objectId
+                x-celigo-refModel: lookupcaches
+            examples:
+              default:
+                value:
+                  - 68680d7111d1437fbcbce534
+                  - 68680d7111d1437fbcbce535
+      responses:
+        '204':
+          description: Lookup caches registered successfully. No body returned.
+        '400':
+          description: An entry in the array is not a valid ObjectId.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/tree/metadata:
+    get:
+      x-internal: false
+      operationId: getIntegrationTreeMetadata
+      tags:
+        - Integrations
+      summary: Get integration tree metadata
+      description: |-
+        Returns structural metadata for the integration and its child integrations. The response
+        includes install steps, flow groupings, API groupings, registered connection ids, uninstall
+        steps, and change-edition steps, plus a `childIntegrations` array with the same structure for
+        each child. Primarily useful for Integration App integrations that have install/uninstall steps
+        and child integrations.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+      responses:
+        '200':
+          description: Integration tree metadata.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  integration:
+                    type: object
+                    description: |-
+                      Metadata for the integration itself, including install steps, flow groupings,
+                      API groupings, registered connection ids, uninstall steps, and change-edition steps.
+                  childIntegrations:
+                    type: array
+                    description: Metadata for child integrations (empty array if none).
+                    items:
+                      type: object
+              examples:
+                plain_integration:
+                  summary: Plain integration with no children
+                  value:
+                    integration:
+                      _id: 6842261335b64c0bcb308e4f
+                      name: Shopify → NetSuite Orders
+                      installSteps: []
+                      uninstallSteps: []
+                      changeEditionSteps: []
+                      flowGroupings:
+                        - _id: 69d42d09b9c28ea0b7e7c0c0
+                          name: Order sync
+                      apiGroupings: []
+                      _registeredConnectionIds:
+                        - 626168f90b6ef816b50c82d7
+                    childIntegrations: []
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/resume:
+    put:
+      x-internal: false
+      operationId: resumeIntegration
+      tags:
+        - Integrations
+      summary: Resume an Integration App integration
+      description: |-
+        Resumes a paused Integration App integration. Requires that the integration belongs to an
+        Integration App. No request body is needed.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+      responses:
+        '200':
+          description: Integration resumed successfully.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          description: |-
+            Integration does not belong to an Integration App. Error code: `invalid_ref`, message:
+            "doesnot belongs to any Integration App."
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                notIA:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: doesnot belongs to any Integration App.
+  /v1/integrations/{_id}/changeEdition:
+    post:
+      x-internal: false
+      operationId: changeIntegrationEdition
+      tags:
+        - Integrations
+      summary: Change the edition of an Integration App integration
+      description: |-
+        Triggers an edition change for an Integration App integration that has a `changeEdition`
+        function configured. Requires the integration to belong to an Integration App with edition
+        support.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+      responses:
+        '200':
+          description: Edition change initiated successfully.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          description: |-
+            Integration does not belong to an Integration App with changeEdition support. Error code:
+            `invalid_integration_app`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                notIA:
+                  value:
+                    errors:
+                      - code: invalid_integration_app
+                        message: Integration does not belong to an Integration App with changeEdition support.
+  /v1/integrations/{_id}/initChild:
+    post:
+      x-internal: false
+      operationId: initChildIntegration
+      tags:
+        - Integrations
+      summary: Initialize a child integration
+      description: |-
+        Initializes a child integration under an Integration App parent. Requires the parent integration
+        to belong to an Integration App with an init script configured.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id (the parent Integration App integration).
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+      responses:
+        '200':
+          description: Child integration initialized successfully.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          description: |-
+            Integration App does not have a valid init script. Error code: `invalid_ref`, message:
+            "Script fields invalid or not found."
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                noScript:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Script fields invalid or not found.
+  /v1/integrations/{_id}/detachLicense:
+    put:
+      x-internal: false
+      operationId: detachIntegrationLicense
+      tags:
+        - Integrations
+      summary: Detach the license from an integration
+      description: |-
+        Detaches the license from an integration. Idempotent -- calling it on an integration that
+        already has no license attached is a no-op. No request body is needed.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+      responses:
+        '204':
+          description: License detached (or was already detached). No body returned.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/iLMIgnore:
+    get:
+      x-internal: false
+      operationId: getIntegrationILMIgnoreFields
+      tags:
+        - Integrations
+      summary: List available ILM ignore fields
+      description: |-
+        Returns the catalog of *available* fields that can be ignored when pulling changes between
+        related integrations. Keys are lowercase resource types (`integration`, `flow`, `export`,
+        `import`, `connection`, `script`, ...); values are arrays of dot-path field names that can be
+        excluded from an ILM pull/revert. The key set is platform-driven — treat the response, not
+        the example list, as the authoritative catalog.
+
+        This endpoint requires the `integrator-ashareid` header to establish a shared-account context.
+        The current ignore configuration lives on the integration's `iLMIgnore` field (readable via
+        `GET /v1/integrations/{_id}`); this endpoint only returns the menu of what *can* be ignored.
+        To change the configuration, PATCH the integration with
+        `[{op:"replace", path:"/iLMIgnore", value:{...}}]`.
+      parameters:
+        - name: integrator-ashareid
+          in: header
+          required: true
+          description: |-
+            Account-share id that scopes the request to a specific shared-account context. The bearer
+            token's user must be the `sharedWithUser` of this ashare.
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 6798f4dc43db9184f4bc8ee0
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+      responses:
+        '200':
+          description: Available ignore fields per resource type.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ILMIgnoreResponse'
+              examples:
+                default:
+                  value:
+                    integration:
+                      - name
+                      - description
+                    flow:
+                      - disabled
+                      - name
+                    export:
+                      - name
+                      - http.body
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: |-
+            Either the `integrator-ashareid` header is malformed (code: `invalid_header_value`) or it
+            was omitted entirely (code: `get_not_allowed`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                get_not_allowed:
+                  summary: Header omitted entirely
+                  value:
+                    errors:
+                      - code: get_not_allowed
+                        message: GET resource not allowed for the given model.
+                invalid_header_value:
+                  summary: Header malformed (not a 24-char hex id)
+                  value:
+                    errors:
+                      - code: invalid_header_value
+                        message: The value provided for request header Integrator-AShareId is invalid.
+        '404':
+          description: |-
+            Integration unknown, or the `integrator-ashareid` references a share whose `sharedWithUser`
+            isn't the bearer token's user (code: `access_restricted`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                access_restricted:
+                  value:
+                    errors:
+                      - code: access_restricted
+                        message: Your access to an integrator.io environment or account has been disabled. For more information, contact account administrator.
+  /v1/integrations/{_id}/template:
+    get:
+      x-internal: false
+      operationId: getIntegrationTemplate
+      tags:
+        - Integrations
+      summary: Get a downloadable template for an integration
+      description: |-
+        Packages the integration as an installable template and returns a signed
+        S3 URL where the template `.zip` can be downloaded. The URL is
+        pre-signed and short-lived (it expires shortly after issuance), so fetch
+        the file promptly after calling this endpoint.
+
+        The downloaded `.zip` is the same artifact used to install the integration
+        as a template into another account.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Integration id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+      responses:
+        '200':
+          description: Signed download URL for the integration template zip.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  signedURL:
+                    type: string
+                    description: Pre-signed, short-lived S3 URL to download the template `.zip`.
+                  key:
+                    type: string
+                    description: S3 object key for the generated template `.zip`.
+              examples:
+                default:
+                  summary: Signed template download URL
+                  value:
+                    signedURL: https://integrator-templates.s3.us-east-1.amazonaws.com/6842261335b64c0bcb308e4f.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=b117bf598b5535ed024cdbdfec756172f386fd39ad4e4536e40e5efbbf4ff52a
+                    key: 6842261335b64c0bcb308e4f.zip
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/integrations/{_id}/dependencies:
+    get:
+      x-internal: false
+      operationId: listIntegrationDependencies
+      tags:
+        - Integrations
+      summary: List dependencies of an integration
+      description: |-
+        Returns the set of resources that depend on the specified resource.
+        The response is an object whose keys are dependent-resource types
+        (e.g. `flows`, `imports`) and whose values are arrays of dependency
+        entries. An empty object `{}` means no other resources depend on the
+        target (also returned for a well-formatted but nonexistent id).
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Resource ID.
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 6842261335b64c0bcb308e4f
+      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:
+                no_dependents:
+                  summary: No other resources depend on the integration
+                  value: {}
+        '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:
+    Settings:
+      type: object
+      description: |
+        Configuration settings that can be accessed by hooks, filters, mappings and handlebars templates at runtime.
+
+        It enables customization of the resource's logic, allowing hooks, mappings, filters, and
+        handlebars to access and apply the settings at runtime.
+
+        **Usage**
+
+        The settings object can store arbitrary JSON data that you want to save with the resource.
+        While it's often populated through a form defined in the `settingsForm` field, you can also:
+
+        - Directly provide JSON settings without using a form
+        - Store configuration values used by hooks and templates
+        - Create resource-specific constants and parameters
+        - Maintain lookup tables or mapping structures
+        - Define conditional logic parameters
+
+        **Accessibility**
+
+        Settings are available in:
+        - All handlebars fields for building dynamic payloads
+        - Field mapping expressions
+        - JavaScript hooks via the options object
+        - Filters and transformations
+
+        At runtime, the settings objects in the step's execution chain are gathered into a
+        single `settings` context keyed by fixed scope keys. Flow runs populate the full
+        chain: `settings.integration.*`, `settings.flowGrouping.*` (the flow group the flow
+        belongs to), `settings.flow.*`, `settings.connection.*`, `settings.iClient.*`, and
+        the running step's own scope — `settings.export.*` on exports/lookups,
+        `settings.import.*` on imports (the key matches the step type). Steps executing
+        inside a My API or a Tool receive only the step's own scope plus
+        `settings.connection.*` / `settings.iClient.*`; the integration, flowGrouping, and
+        flow scopes resolve empty there. The scope key is literal — resource display names
+        and settingsForm section labels are never part of the path. The segments after the
+        scope mirror the stored settings JSON key path exactly: a top-level field is
+        `settings.<scope>.<fieldId>`, and nested objects add one segment per JSON key
+        (e.g. `settings.flowGrouping.Customer.region` when the group's settings JSON nests
+        `region` under `Customer`). References without a scope key
+        (e.g. `{{settings.myField}}`) resolve to empty strings.
+
+        **Best practices**
+
+        For non-technical users, create a custom form instead of editing the JSON directly.
+        This provides a user-friendly interface for updating settings without requiring JSON knowledge.
+      additionalProperties: true
+    Form:
+      type: object
+      description: |
+        Configuration for creating user-friendly settings forms that make it easier for less technical users
+        to configure integration resources.
+
+        **Settings form builder**
+
+        The Settings Form Builder allows you to create or edit user-friendly fields that prompt for text entry
+        or selections that will be returned as settings applied to this resource. Your forms can include any
+        field types that you see elsewhere in integrator.io, such as:
+
+        - Text fields
+        - Dropdown selections
+        - Checkboxes
+        - Radio buttons
+        - Date pickers
+        - Multi-select fields
+        - Search fields
+
+        Form fields make it much easier for less technical users to work with your integration settings by:
+
+        - Providing clear labels and help text
+        - Enforcing validation rules
+        - Offering pre-defined selection options
+        - Grouping related settings logically
+        - Supporting conditional visibility
+        - Creating a consistent user experience
+      properties:
+        form:
+          type: object
+          description: |
+            Configuration that defines the structure, fields, and behavior of the settings form.
+
+            This object contains the complete definition of the form's layout, fields, validation rules,
+            and interactive behaviors. The specific structure depends on the form complexity and can include
+            field definitions, sections, conditional display logic, and default values.
+
+            The form configuration is typically created and managed through the visual Form Builder interface
+            rather than edited directly as JSON.
+          properties:
+            fieldMap:
+              type: object
+              description: |
+                A mapping of field identifiers to their configuration objects.
+                Each key in this object represents a unique field ID, and the value contains
+                all the configuration settings for that specific form field.
+              additionalProperties:
+                type: object
+                description: |
+                  Configuration for an individual form field.
+                properties:
+                  id:
+                    type: string
+                    description: |
+                      Unique identifier for this field within the form.
+                      This value typically matches the key in the fieldMap object.
+                    examples:
+                      - url
+                      - mode
+                      - body
+                      - keyValue
+                      - text
+                      - multiline
+                  name:
+                    type: string
+                    description: |
+                      Name of the field, used as the property name when generating the settings object
+                      from the submitted form data.
+                    examples:
+                      - url
+                      - mode
+                      - body
+                      - keyValue
+                      - text
+                      - multiline
+                  type:
+                    type: string
+                    description: |
+                      The type of form control to render for this field.
+                    enum:
+                      - text
+                      - checkbox
+                      - radiogroup
+                      - relativeuri
+                      - editor
+                      - keyvalue
+                      - select
+                      - multiselect
+                      - toggle
+                      - datetime
+                      - date
+                      - exportSelect
+                      - staticMap
+                    x-enumDescriptions:
+                      text: Single-line or multi-line text input field.
+                      checkbox: Boolean checkbox control for true/false values.
+                      radiogroup: Group of mutually exclusive radio button options.
+                      relativeuri: Text input for entering a relative URI path.
+                      editor: Code or content editor with syntax highlighting.
+                      keyvalue: Dynamic list of key-value pair inputs.
+                      select: Dropdown menu for selecting a single option.
+                      multiselect: Dropdown menu that allows selecting multiple options.
+                      toggle: On/off toggle switch control.
+                      datetime: Date and time picker control.
+                      date: Date-only picker control without a time component.
+                      exportSelect: Dropdown whose options are records returned by an export.
+                      staticMap: Static two-column mapping table for pairing source and destination values.
+                    examples:
+                      - text
+                      - checkbox
+                      - radiogroup
+                      - editor
+                      - keyvalue
+                      - select
+                      - multiselect
+                  label:
+                    type: string
+                    description: |
+                      Display label shown next to the field in the form.
+                    examples:
+                      - Some url with handlebars support.
+                      - Mode of operation
+                      - Key-value pairs
+                      - Text
+                  description:
+                    type: string
+                    description: |
+                      Detailed explanation text that appears below the field, providing more context
+                      than the label or helpText.
+                    examples:
+                      - This input is used to collect a set of key-value pairs. The item delete action is optional and set using th showDelete prop. Also note that he key and value names can be configured as well.
+                  helpText:
+                    type: string
+                    description: |
+                      Explanatory text that appears when hovering over the help icon next to the field.
+                      Used to provide additional guidance on how to use the field.
+                    examples:
+                      - example of a custom input.
+                      - This is the most basic input. It models an http form input
+                  required:
+                    type: boolean
+                    description: |
+                      When true, the field must have a value before the form can be submitted.
+                    default: false
+                    examples:
+                      - true
+                      - false
+                  multiline:
+                    type: boolean
+                    description: |
+                      For text fields, determines whether the input should be a multi-line text area
+                      instead of a single-line input.
+                    default: false
+                    examples:
+                      - true
+                      - false
+                  rowsMax:
+                    type: integer
+                    description: |
+                      For multiline text fields, specifies the maximum number of visible rows.
+                    examples:
+                      - 5
+                  inputType:
+                    type: string
+                    description: |
+                      For text fields, specifies the HTML input type attribute to apply additional
+                      validation or specialized input behavior.
+                    enum:
+                      - text
+                      - number
+                      - email
+                      - password
+                      - tel
+                      - url
+                    x-enumDescriptions:
+                      text: Standard text input with no special validation.
+                      number: Numeric input that restricts entry to numbers.
+                      email: Email address input with email format validation.
+                      password: Masked text input that hides the entered characters.
+                      tel: Telephone number input optimized for phone number entry.
+                      url: URL input with web address format validation.
+                    examples:
+                      - number
+                  delimiter:
+                    type: string
+                    description: |
+                      For text fields, specifies a character to use for splitting the input into an array.
+                      Used for collecting multiple values in a single text field.
+                    examples:
+                      - ','
+                  mode:
+                    type: string
+                    description: |
+                      For editor fields, specifies the type of content being edited for syntax highlighting.
+                    enum:
+                      - json
+                      - xml
+                      - csv
+                      - text
+                    x-enumDescriptions:
+                      json: JSON syntax highlighting and validation.
+                      xml: XML syntax highlighting and validation.
+                      csv: CSV format highlighting for comma-separated data.
+                      text: Plain text mode with no syntax highlighting.
+                    examples:
+                      - json
+                  keyName:
+                    type: string
+                    description: |
+                      For keyvalue fields, specifies the placeholder and field name for the key input.
+                    examples:
+                      - theKey
+                  valueName:
+                    type: string
+                    description: |
+                      For keyvalue fields, specifies the placeholder and field name for the value input.
+                    examples:
+                      - theValue
+                  showDelete:
+                    type: boolean
+                    description: |
+                      For keyvalue fields, determines whether to show a delete button for each key-value pair.
+                    examples:
+                      - true
+                      - false
+                  doNotAllowFutureDates:
+                    type: boolean
+                    description: |
+                      For date and datetime fields, restricts selection to dates not in the future.
+                    examples:
+                      - true
+                      - false
+                  skipTimezoneConversion:
+                    type: boolean
+                    description: |
+                      For datetime fields, prevents automatic timezone conversion of the date value.
+                    examples:
+                      - true
+                      - false
+                  options:
+                    type: array
+                    description: |
+                      For fields that present choices (select, multiselect, radiogroup, toggle), defines
+                      the available options.
+                    items:
+                      anyOf:
+                        - title: Option group
+                          type: object
+                          required:
+                            - items
+                          properties:
+                            items:
+                              type: array
+                              items:
+                                oneOf:
+                                  - title: String value
+                                    type: string
+                                  - title: Label-value pair
+                                    type: object
+                                    properties:
+                                      label:
+                                        type: string
+                                        description: |
+                                          Display text for the option.
+                                        examples:
+                                          - United States
+                                          - Canada
+                                          - India
+                                      value:
+                                        type: string
+                                        description: |
+                                          Value to store when this option is selected.
+                                        examples:
+                                          - us
+                                          - cdn
+                                          - in
+                              description: |
+                                Array of option values/labels to display in the selection control.
+                              examples:
+                                - - Create
+                                  - Update
+                                  - Delete
+                                - - label: United States
+                                    value: us
+                                  - label: Canada
+                                    value: cdn
+                        - title: Label-value pair
+                          type: object
+                          required:
+                            - label
+                          properties:
+                            label:
+                              type: string
+                              description: |
+                                Display text for the option.
+                              examples:
+                                - US
+                                - Canada
+                                - India
+                            value:
+                              type: string
+                              description: |
+                                Value to store when this option is selected.
+                              examples:
+                                - us
+                                - cdn
+                                - in
+                  visibleWhen:
+                    type: array
+                    description: |
+                      Conditional display rules that determine when this field should be visible.
+                      If empty or not provided, the field is always visible.
+                    items:
+                      type: object
+                      properties:
+                        field:
+                          type: string
+                          description: |
+                            The ID of another field whose value controls the visibility of this field.
+                          examples:
+                            - mode
+                        is:
+                          type: array
+                          items:
+                            type:
+                              - string
+                              - boolean
+                              - number
+                              - 'null'
+                          description: |
+                            Array of values - if the referenced field has any of these values,
+                            this field will be visible. Values may be strings, booleans (for
+                            checkbox/toggle fields), numbers (for numeric inputs), or null.
+                          examples:
+                            - - Update
+                            - - true
+            layout:
+              type: object
+              description: |
+                Defines how the form fields are arranged and grouped in the UI.
+                The layout can organize fields into columns, sections, or other visual groupings.
+              properties:
+                type:
+                  type: string
+                  description: |
+                    The type of layout to use for the form.
+                  enum:
+                    - column
+                    - collapse
+                    - box
+                    - indent
+                    - tabWithoutSave
+                    - verticalTabWithoutSave
+                  x-enumDescriptions:
+                    column: Arranges form fields in a single vertical column layout.
+                    collapse: Groups fields into collapsible/expandable sections.
+                    box: Wraps field groups in bordered boxes with headings.
+                    indent: Indents field groups to show hierarchy.
+                    tabWithoutSave: Organizes field groups into horizontal tabs (no per-tab save).
+                    verticalTabWithoutSave: Organizes field groups into vertical tabs (no per-tab save).
+                  examples:
+                    - column
+                    - collapse
+                containers:
+                  type: array
+                  description: |
+                    Array of container objects that group fields or contain nested containers.
+                    Each container can represent a column, box, indented section, or collapsible section.
+                  items:
+                    type: object
+                    properties:
+                      type:
+                        type: string
+                        description: |
+                          The visual style of the container.
+                        enum:
+                          - indent
+                          - box
+                          - collapse
+                        x-enumDescriptions:
+                          indent: Indents the contained fields to show hierarchy.
+                          box: Wraps the contained fields in a bordered box with a heading.
+                          collapse: Wraps the contained fields in a collapsible/expandable section.
+                        examples:
+                          - indent
+                          - box
+                          - collapse
+                      label:
+                        type: string
+                        description: |
+                          The heading text displayed for this container.
+                        examples:
+                          - Basic fields
+                          - Advanced fields
+                          - Indented fields
+                          - Boxed fields
+                      fields:
+                        type: array
+                        items:
+                          type: string
+                        description: |
+                          Array of field IDs that should be displayed in this container.
+                          Each ID must correspond to a key in the fieldMap object.
+                        examples:
+                          - - A
+                            - url
+                          - - mode
+                            - body
+                          - - keyValue
+                            - checkbox
+                      containers:
+                        type: array
+                        description: |
+                          Nested containers within this container. Allows for hierarchical organization
+                          of fields with different visual styles.
+                        items:
+                          type: object
+                          properties:
+                            label:
+                              type: string
+                              description: |
+                                The heading text displayed for this nested container.
+                              examples:
+                                - Indented fields
+                                - Boxed fields
+                                - Collapsed fields
+                            fields:
+                              type: array
+                              items:
+                                type: string
+                              description: |
+                                Array of field IDs that should be displayed in this nested container.
+                              examples:
+                                - - keyValue
+                                  - checkbox
+          additionalProperties: true
+        init:
+          type: object
+          description: |
+            Configuration for custom JavaScript initialization that executes when the form is first loaded.
+
+            This object defines a JavaScript hook that prepares the form for use, sets initial field values,
+            performs validation, or otherwise customizes the form behavior before it is displayed to the user.
+
+            **Function signature**
+
+            The initialization function is invoked with a single 'options' argument containing contextual information:
+            ```javascript
+            function formInit(options) {
+              // Process options and return the form object
+              return options.resource.settingsForm.form;
+            }
+            ```
+
+            **Available context**
+
+            The 'options' argument provides access to:
+            - `options.resource` - The current resource being configured
+            - `options.parentResource` - The parent of the current resource
+            - `options.grandparentResource` - The grandparent of the current resource
+            - `options.license` - For integration apps, the license provisioned to the integration
+            - `options.parentLicense` - For integration apps, the parent of the license
+            - `options.sandbox` - Boolean flag indicating whether the script is running in a sandbox environment
+
+
+            **Common uses**
+
+            - Dynamically generate field options based on resource configuration
+            - Pre-populate default values from related resources
+            - Apply conditional logic that depends on resource properties
+            - Add, remove, or modify form fields based on user permissions or account settings
+            - Fetch external data to populate selection options
+            - Implement complex validation rules that depend on resource context
+            - Create branching form experiences based on user selections
+
+            **Return value**
+
+            The function must return a valid form object that the UI can render.
+            Throwing an exception will signal an error to the user.
+          properties:
+            function:
+              type: string
+              description: |
+                The name of the function to execute within the referenced script.
+
+                This property specifies which function to invoke from the script
+                referenced by _scriptId. The function will be called when the form
+                is initialized and should handle any custom setup logic.
+
+                The function must follow the expected signature and return a valid form object.
+              examples:
+                - initializeForm
+                - setupFormState
+                - prepareFormData
+            _scriptId:
+              type: string
+              description: |
+                Reference to a predefined script resource containing the initialization function.
+
+                The referenced script should contain the function specified in the
+                'function' property. This script must be accessible within the user's account
+                and have appropriate permissions.
+              examples:
+                - 60a2c4e6f321d800129a1a3c
+                - 5f8d43a1b9e5a80011a35f2c
+    PreSave:
+      type: object
+      description: |
+        Defines a JavaScript hook that executes before the resource is saved.
+
+        This hook allows for programmatic validation, transformation, or enrichment of the
+        resource itself before it is persisted. It can be used to enforce business rules,
+        set derived properties, or implement cross-field validations that can't be expressed
+        through the standard UI.
+
+        **Function signature**
+
+        The preSave function is invoked with a single 'options' argument containing:
+        ```javascript
+        function preSave(options) {
+          // Process options and return the modified resource
+          return options.newResource;
+        }
+        ```
+
+        **Available context**
+
+        The 'options' argument provides access to:
+        - `options.newResource` - The resource being saved (with pending changes)
+        - `options.oldResource` - The previous version of the resource (before changes)
+        - `options.sandbox` - Boolean flag indicating whether the script is running in a sandbox environment
+
+
+        **Common uses**
+
+        - Enforcing complex business rules across multiple fields
+        - Automatically deriving field values based on other configuration
+        - Performing validation that depends on external systems or data
+        - Normalizing or standardizing configuration values
+        - Adding computed or derived properties
+        - Implementing versioning or change tracking
+        - Dynamically looking up data using the Celigo API module to enrich configuration
+
+        **Return value**
+
+        The function must return the newResource object (potentially modified) to be saved.
+        Throwing an exception will prevent saving and signal an error to the user.
+      properties:
+        function:
+          type: string
+          description: |
+            The name of the function to execute within the referenced script.
+
+            This property specifies which function to invoke from the script
+            referenced by _scriptId. The function will be called just before
+            the resource is saved.
+
+            The function must follow the expected signature and return the resource object.
+          examples:
+            - preSave
+            - validateResource
+            - prepareResourceForSave
+        _scriptId:
+          type: string
+          description: |
+            Reference to a predefined script resource containing the preSave function.
+
+            The referenced script should contain the function specified in the
+            'function' property. This script must be accessible within the user's account
+            and have appropriate permissions.
+          examples:
+            - 60a2c4e6f321d800129a1a3c
+            - 5f8e7d2c1b54e6003a9c7e12
+    IntegrationBase:
+      type: object
+      description: Writable integration fields shared by the request and response schemas.
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 100
+          description: |-
+            Human-readable name for the integration.
+
+            Use a short, descriptive label that helps users identify the integration in the UI.
+          examples:
+            - Shopify → NetSuite Orders
+        description:
+          type:
+            - string
+            - 'null'
+          maxLength: 5120
+          description: |-
+            Optional description of the integration's purpose and behavior.
+
+            Helpful for documentation, onboarding, and clarifying what the integration does.
+        readme:
+          type:
+            - string
+            - 'null'
+          maxLength: 51200
+          description: |-
+            Long-form README content for the integration (typically Markdown).
+
+            Use this to provide setup instructions, prerequisites, and operational notes.
+          x-celigo-ai-guidance:
+            - |-
+              Set this ONLY when the user explicitly provides README content or asks you to
+              write one — author it from THEIR wording and intent,
+              not from your own assumptions.
+              Do NOT generate a README on a create/update the user did not ask for;
+              leave it unset.
+        _connectorId:
+          type: string
+          format: objectId
+          x-celigo-refModel: connectors
+          examples:
+            - 5b3c8f9a2e1d4c0011223344
+          description: |-
+            Integration App (connector) identifier when this integration is based on an installed Integration App.
+
+            If you are not working with an Integration App installation, omit this field.
+        _templateId:
+          type: string
+          format: objectId
+          x-celigo-refModel: templates
+          examples:
+            - 5c1a7b8d4f2e6a0011556677
+          description: |-
+            Template identifier used to create/initialize this integration (commonly for Integration Apps).
+
+            Omit unless you are creating/updating an integration from a template.
+        install:
+          type: array
+          description: |-
+            Install "cards" shown during an Integration App installation.
+
+            These are primarily UI/workflow metadata. Unless you are explicitly modeling an Integration App install experience,
+            omit this field.
+          items:
+            type: object
+            additionalProperties: true
+            properties:
+              name:
+                type: string
+                description: Display name for this install card.
+                examples:
+                  - Connect to Shopify
+              description:
+                type: string
+                description: Help text shown to the user for this install card.
+                examples:
+                  - Authorize access to your Shopify store.
+              imageURL:
+                type: string
+                description: Optional image URL to display for this install card.
+                examples:
+                  - https://www.celigo.com/images/shopify.png
+              _connectionId:
+                type: string
+                format: objectId
+                x-celigo-refModel: connections
+                examples:
+                  - 626168f90b6ef816b50c82d7
+                description: Connection referenced/created/registered by this card (if applicable).
+              installURL:
+                type: string
+                description: URL to open during install (if the card is URL-based).
+                examples:
+                  - https://www.celigo.com/install/shopify
+              completed:
+                type:
+                  - boolean
+                  - 'null'
+                description: When true, this card has been completed. The server also returns `null` for cards whose completion state was never set.
+              installerFunction:
+                type: string
+                description: Optional function name used by the platform to run install logic for this card.
+                examples:
+                  - installShopifyConnection
+              uninstallerFunction:
+                type: string
+                description: Optional function name used by the platform to run uninstall logic for this card.
+                examples:
+                  - uninstallShopifyConnection
+              options:
+                type: object
+                description: Free-form options passed to the installer/uninstaller logic.
+                additionalProperties: true
+              sourceConnection:
+                type: object
+                description: Source connection metadata used to prefill or drive install behavior.
+                additionalProperties: true
+              templateZip:
+                type: boolean
+                description: When true, this card uses a template ZIP artifact.
+              _stackId:
+                type: string
+                format: objectId
+                x-celigo-refModel: stacks
+                examples:
+                  - 5f2a1b3c4d5e6f0011889900
+                description: Stack identifier used by install logic (if applicable).
+              isClone:
+                type: boolean
+                description: When true, this card is part of a clone workflow.
+              form:
+                type: object
+                description: Inline form definition used by this card (if applicable).
+                additionalProperties: true
+        mode:
+          type: string
+          description: |-
+            Integration App lifecycle mode.
+
+            Use this only when dealing with Integration App lifecycle workflows.
+          enum:
+            - install
+            - settings
+            - uninstall
+          x-enumDescriptions:
+            install: The integration is being installed or is in the install workflow.
+            settings: The integration is in settings configuration mode.
+            uninstall: The integration is being uninstalled.
+          examples:
+            - install
+        settings:
+          description: Integration App settings object for this integration.
+          allOf:
+            - description: |-
+                Integration App settings object for this integration.
+
+                These values are typically collected via `settingsForm` and then stored here. When generating values,
+                prefer setting only the fields required by the form/workflow and omit unknown keys.
+            - $ref: '#/components/schemas/Settings'
+        version:
+          type:
+            - string
+            - 'null'
+          examples:
+            - 1.2.0
+          description: |-
+            Integration App version (or template version) associated with this integration.
+
+            Usually system-managed for Integration App installs; omit unless you are explicitly controlling versions.
+        tag:
+          type:
+            - string
+            - 'null'
+          examples:
+            - instance-2
+          description: |-
+            Legacy field for distinguishing multiple instances of the same Integration App within a single Celigo environment.
+
+            Only set this when a customer is running multiple installations of the same Integration App. Otherwise, omit this field.
+        updateInProgress:
+          type: boolean
+          description: |-
+            When true, an Integration App update workflow is currently running. Settable via the
+            API, but normally managed by the platform's update workflow.
+          x-celigo-ai-guidance:
+            - Typically system-managed; omit unless a workflow explicitly requires setting it.
+        celigoAgentAutoRunMode:
+          type: boolean
+          examples:
+            - false
+          description: |-
+            When true, Celigo Agent actions scoped to this integration are allowed to run automatically
+            without a manual approval step.
+
+            Omit unless you are explicitly configuring Celigo Agent behavior for this integration.
+        resolvedAt:
+          type: string
+          format: date-time
+          examples:
+            - '2026-01-15T09:30:00.000Z'
+          description: |-
+            Timestamp indicating when the most recent install/update workflow was resolved/completed.
+
+            Typically system-managed; omit in normal create/update payloads.
+        settingsForm:
+          description: Settings form definition for the integration.
+          allOf:
+            - description: |-
+                Settings form definition for the integration.
+
+                This controls the UI fields shown to users to collect `settings`.
+                Unless you are authoring/patching an Integration App definition, omit this field.
+            - $ref: '#/components/schemas/Form'
+        preSave:
+          description: Pre-save hook configuration used to validate/transform settings before saving.
+          allOf:
+            - description: |-
+                Pre-save hook configuration used to validate/transform settings before saving.
+
+                Unless you are authoring/patching an Integration App definition, omit this field.
+            - $ref: '#/components/schemas/PreSave'
+        update:
+          type: object
+          description: |-
+            Script reference used by the platform to perform integration update logic (e.g., migration between versions).
+
+            Only include when the update workflow explicitly requires it.
+          properties:
+            _scriptId:
+              type: string
+              format: objectId
+              x-celigo-refModel: scripts
+              examples:
+                - 5d4e3f2a1b0c9d0011223344
+              description: Script ID that contains the update implementation.
+            _stackId:
+              type: string
+              format: objectId
+              x-celigo-refModel: stacks
+              examples:
+                - 5f2a1b3c4d5e6f0011889900
+              description: Stack ID that provides runtime context for the update script (if applicable).
+            function:
+              type: string
+              examples:
+                - updateIntegration
+              description: Function name within the script to invoke for updates.
+        installSteps:
+          type: array
+          description: |-
+            Ordered list of lifecycle steps used by the Integration App installer.
+
+            This is primarily Integration App workflow metadata. Omit unless you are working with Integration Apps.
+          items:
+            type: object
+            additionalProperties: true
+            required:
+              - name
+              - type
+            properties:
+              name:
+                type: string
+                description: Display name for the step.
+                examples:
+                  - Connect to NetSuite
+              description:
+                type: string
+                description: Help text shown to the user for the step.
+                examples:
+                  - Authorize access to your NetSuite account.
+              imageUrl:
+                type: string
+                description: Optional image URL for the step.
+                examples:
+                  - https://www.celigo.com/images/netsuite.png
+              completed:
+                type: boolean
+                description: When true, this step has been completed.
+              type:
+                type: string
+                description: Step type.
+                x-celigo-ai-guidance:
+                  - |-
+                    Choose the type that matches the step payload:
+                    - `connection`: step uses `_connectionId`
+                    - `url`: step uses `url` or `getUrlFunction`
+                    - `form`: step uses `form` or `initFormFunction`
+                    - `hidden`: step runs silently without user interaction (no payload)
+                    - `template_zip`: step uses `templateZip`
+                    - `stack`: step uses `_stackId`
+                    - `edition`: step participates in license/edition changes
+                enum:
+                  - connection
+                  - url
+                  - form
+                  - hidden
+                  - template_zip
+                  - stack
+                  - edition
+                x-enumDescriptions:
+                  connection: Step that registers or creates a connection resource.
+                  url: Step that opens an external URL during the install workflow.
+                  form: Step that collects user input via an inline or dynamic form.
+                  hidden: Step that runs silently without user interaction.
+                  template_zip: Step that provisions resources from a template ZIP artifact.
+                  stack: Step that registers or creates a stack resource.
+                  edition: Step that participates in license or edition changes.
+              url:
+                type: string
+                description: 'URL to open (for `type: url`).'
+                examples:
+                  - https://www.celigo.com/install/netsuite
+              form:
+                type: object
+                description: 'Inline form definition (for `type: form`).'
+                additionalProperties: true
+              function:
+                type: string
+                description: Function name to run for this step (script-based behavior).
+                examples:
+                  - runInstallStep
+              initFormFunction:
+                type: string
+                description: 'Function name used to initialize form data (for `type: form`).'
+                examples:
+                  - initSettingsForm
+              _scriptId:
+                type: string
+                format: objectId
+                x-celigo-refModel: scripts
+                examples:
+                  - 5d4e3f2a1b0c9d0011223344
+                description: Script that contains `function`, `initFormFunction`, or `getUrlFunction`.
+              sourceConnection:
+                type: object
+                description: Source connection metadata used to drive install behavior.
+                additionalProperties: true
+              templateZip:
+                type: boolean
+                description: When true, this step uses a template ZIP artifact.
+              _connectionId:
+                type: string
+                format: objectId
+                x-celigo-refModel: connections
+                examples:
+                  - 6553ebdeda62bb22e7fa81ff
+                description: 'Connection referenced/created by this step (for `type: connection`).'
+              _stackId:
+                type: string
+                format: objectId
+                x-celigo-refModel: stacks
+                examples:
+                  - 5f2a1b3c4d5e6f0011889900
+                description: 'Stack referenced/created by this step (for `type: stack`).'
+              isClone:
+                type: boolean
+                description: When true, this step is being applied in a clone workflow.
+              getUrlFunction:
+                type: string
+                description: 'Function name used to compute a URL dynamically (for `type: url`).'
+                examples:
+                  - computeInstallURL
+              options:
+                type: object
+                description: Free-form options used by installer logic for this step.
+                additionalProperties: true
+        uninstallSteps:
+          type: array
+          description: Ordered list of lifecycle steps used by the Integration App uninstaller.
+          items:
+            type: object
+            additionalProperties: true
+            required:
+              - name
+              - type
+            properties:
+              name:
+                type: string
+                description: Display name for the step.
+                examples:
+                  - Connect to NetSuite
+              description:
+                type: string
+                description: Help text shown to the user for the step.
+                examples:
+                  - Authorize access to your NetSuite account.
+              imageUrl:
+                type: string
+                description: Optional image URL for the step.
+                examples:
+                  - https://www.celigo.com/images/netsuite.png
+              completed:
+                type: boolean
+                description: When true, this step has been completed.
+              type:
+                type: string
+                description: Step type.
+                x-celigo-ai-guidance:
+                  - |-
+                    Choose the type that matches the step payload:
+                    - `connection`: step uses `_connectionId`
+                    - `url`: step uses `url` or `getUrlFunction`
+                    - `form`: step uses `form` or `initFormFunction`
+                    - `hidden`: step runs silently without user interaction (no payload)
+                    - `template_zip`: step uses `templateZip`
+                    - `stack`: step uses `_stackId`
+                    - `edition`: step participates in license/edition changes
+                enum:
+                  - connection
+                  - url
+                  - form
+                  - hidden
+                  - template_zip
+                  - stack
+                  - edition
+                x-enumDescriptions:
+                  connection: Step that registers or creates a connection resource.
+                  url: Step that opens an external URL during the uninstall workflow.
+                  form: Step that collects user input via an inline or dynamic form.
+                  hidden: Step that runs silently without user interaction.
+                  template_zip: Step that provisions resources from a template ZIP artifact.
+                  stack: Step that registers or creates a stack resource.
+                  edition: Step that participates in license or edition changes.
+              url:
+                type: string
+                description: 'URL to open (for `type: url`).'
+                examples:
+                  - https://www.celigo.com/install/netsuite
+              form:
+                type: object
+                description: 'Inline form definition (for `type: form`).'
+                additionalProperties: true
+              function:
+                type: string
+                description: Function name to run for this step (script-based behavior).
+                examples:
+                  - runInstallStep
+              initFormFunction:
+                type: string
+                description: 'Function name used to initialize form data (for `type: form`).'
+                examples:
+                  - initSettingsForm
+              _scriptId:
+                type: string
+                format: objectId
+                x-celigo-refModel: scripts
+                examples:
+                  - 5d4e3f2a1b0c9d0011223344
+                description: Script that contains `function`, `initFormFunction`, or `getUrlFunction`.
+              sourceConnection:
+                type: object
+                description: Source connection metadata used to drive install behavior.
+                additionalProperties: true
+              templateZip:
+                type: boolean
+                description: When true, this step uses a template ZIP artifact.
+              _connectionId:
+                type: string
+                format: objectId
+                x-celigo-refModel: connections
+                examples:
+                  - 6553ebdeda62bb22e7fa81ff
+                description: 'Connection referenced/created by this step (for `type: connection`).'
+              _stackId:
+                type: string
+                format: objectId
+                x-celigo-refModel: stacks
+                examples:
+                  - 5f2a1b3c4d5e6f0011889900
+                description: 'Stack referenced/created by this step (for `type: stack`).'
+              isClone:
+                type: boolean
+                description: When true, this step is being applied in a clone workflow.
+              getUrlFunction:
+                type: string
+                description: 'Function name used to compute a URL dynamically (for `type: url`).'
+                examples:
+                  - computeInstallURL
+              options:
+                type: object
+                description: Free-form options used by installer logic for this step.
+                additionalProperties: true
+        changeEditionSteps:
+          type: array
+          description: Ordered list of steps used when changing the integration's edition/license.
+          items:
+            type: object
+            additionalProperties: true
+            required:
+              - name
+              - type
+            properties:
+              name:
+                type: string
+                description: Display name for the step.
+                examples:
+                  - Connect to NetSuite
+              description:
+                type: string
+                description: Help text shown to the user for the step.
+                examples:
+                  - Authorize access to your NetSuite account.
+              imageUrl:
+                type: string
+                description: Optional image URL for the step.
+                examples:
+                  - https://www.celigo.com/images/netsuite.png
+              completed:
+                type: boolean
+                description: When true, this step has been completed.
+              type:
+                type: string
+                description: Step type.
+                x-celigo-ai-guidance:
+                  - |-
+                    Choose the type that matches the step payload:
+                    - `connection`: step uses `_connectionId`
+                    - `url`: step uses `url` or `getUrlFunction`
+                    - `form`: step uses `form` or `initFormFunction`
+                    - `hidden`: step runs silently without user interaction (no payload)
+                    - `template_zip`: step uses `templateZip`
+                    - `stack`: step uses `_stackId`
+                    - `edition`: step participates in license/edition changes
+                enum:
+                  - connection
+                  - url
+                  - form
+                  - hidden
+                  - template_zip
+                  - stack
+                  - edition
+                x-enumDescriptions:
+                  connection: Step that registers or creates a connection resource.
+                  url: Step that opens an external URL during the edition change workflow.
+                  form: Step that collects user input via an inline or dynamic form.
+                  hidden: Step that runs silently without user interaction.
+                  template_zip: Step that provisions resources from a template ZIP artifact.
+                  stack: Step that registers or creates a stack resource.
+                  edition: Step that participates in license or edition changes.
+              url:
+                type: string
+                description: 'URL to open (for `type: url`).'
+                examples:
+                  - https://www.celigo.com/install/netsuite
+              form:
+                type: object
+                description: 'Inline form definition (for `type: form`).'
+                additionalProperties: true
+              function:
+                type: string
+                description: Function name to run for this step (script-based behavior).
+                examples:
+                  - runInstallStep
+              initFormFunction:
+                type: string
+                description: 'Function name used to initialize form data (for `type: form`).'
+                examples:
+                  - initSettingsForm
+              _scriptId:
+                type: string
+                format: objectId
+                x-celigo-refModel: scripts
+                examples:
+                  - 5d4e3f2a1b0c9d0011223344
+                description: Script that contains `function`, `initFormFunction`, or `getUrlFunction`.
+              sourceConnection:
+                type: object
+                description: Source connection metadata used to drive install behavior.
+                additionalProperties: true
+              templateZip:
+                type: boolean
+                description: When true, this step uses a template ZIP artifact.
+              _connectionId:
+                type: string
+                format: objectId
+                x-celigo-refModel: connections
+                examples:
+                  - 6553ebdeda62bb22e7fa81ff
+                description: 'Connection referenced/created by this step (for `type: connection`).'
+              _stackId:
+                type: string
+                format: objectId
+                x-celigo-refModel: stacks
+                examples:
+                  - 5f2a1b3c4d5e6f0011889900
+                description: 'Stack referenced/created by this step (for `type: stack`).'
+              isClone:
+                type: boolean
+                description: When true, this step is being applied in a clone workflow.
+              getUrlFunction:
+                type: string
+                description: 'Function name used to compute a URL dynamically (for `type: url`).'
+                examples:
+                  - computeInstallURL
+              options:
+                type: object
+                description: Free-form options used by installer logic for this step.
+                additionalProperties: true
+        pendingLicense:
+          type:
+            - object
+            - 'null'
+          description: |-
+            Pending license/edition change information for the integration.
+
+            The server returns `null` when no license/edition change is pending (rather than omitting the field).
+            Only include when a license/edition change workflow explicitly requires it.
+          properties:
+            opts:
+              type: object
+              description: Free-form license options/payload.
+              additionalProperties: true
+            _editionId:
+              type:
+                - string
+                - 'null'
+              format: objectId
+              examples:
+                - 5e6f7a8b9c0d1e0011334455
+              description: Target edition ID for the pending license change, or `null` when cleared.
+        _parentId:
+          type: string
+          format: objectId
+          x-celigo-refModel: integrations
+          examples:
+            - 6842261335b64c0bcb308e4f
+          description: |-
+            Parent integration ID when this integration was created as a child of another integration.
+            Invalid ids are silently dropped by the server. Omit unless creating/updating child integrations.
+        childDisplayName:
+          type: string
+          examples:
+            - West region store
+          description: |-
+            Display name used for a child integration created during installation.
+
+            Omit unless creating/updating child integrations.
+        initChild:
+          type: object
+          description: |-
+            Script reference used to initialize a child integration during installation.
+
+            Only include when the child initialization workflow explicitly requires it.
+          properties:
+            function:
+              type: string
+              examples:
+                - initChildIntegration
+              description: Function name to invoke to initialize the child integration.
+            _scriptId:
+              type: string
+              format: objectId
+              x-celigo-refModel: scripts
+              examples:
+                - 5d4e3f2a1b0c9d0011223344
+              description: Script ID that contains the initChild function.
+            _stackId:
+              type: string
+              format: objectId
+              x-celigo-refModel: stacks
+              examples:
+                - 5f2a1b3c4d5e6f0011889900
+              description: Stack ID that provides runtime context for initChild (if applicable).
+        flowGroupings:
+          type: array
+          description: |-
+            UI grouping configuration that groups an integration's flows into named
+            sections. Works on ANY integration — this is NOT an Integration-App-only
+            feature; a plain integration can define flow groupings too.
+
+            Omit unless you are explicitly configuring flow grouping behavior.
+          x-celigo-ai-guidance:
+            - |-
+              Set this ONLY when the user explicitly asks to group flows into named sections (e.g.
+              "create the integration with flow groups Order Intake and Fulfillment").
+              Otherwise omit it — do not synthesize groupings the user did not ask for.
+          items:
+            type: object
+            additionalProperties: true
+            required:
+              - name
+            properties:
+              _id:
+                type: string
+                format: objectId
+                readOnly: true
+                description: Server-assigned grouping id.
+              name:
+                type: string
+                description: Display name for the flow grouping section.
+                examples:
+                  - Order sync
+              settings:
+                type: object
+                description: |-
+                  Group-level settings for flows in this group. At runtime, flows in the
+                  group read these values under the fixed scope key `flowGrouping` — e.g.
+                  the Handlebars expression `{{{settings.flowGrouping.salesOrganization}}}`
+                  or the Mapper 2.0 envelope path `$.settings.flowGrouping.salesOrganization`.
+                additionalProperties: true
+                x-celigo-ai-guidance:
+                  - |-
+                    Segments after the `flowGrouping` scope key mirror the stored settings JSON
+                    key path exactly — nested objects add one segment per JSON key. E.g. when
+                    the grouping's settings JSON is `{"Customer": {"region": "west"}}`, the
+                    runtime reference is `{{{settings.flowGrouping.Customer.region}}}`
+                    (`Customer` is a JSON key here, not a settingsForm section label).
+                  - |-
+                    The runtime reference path always uses the literal scope key `flowGrouping`,
+                    never the grouping's `name` or any settingsForm section label. Both
+                    `{{settings.<fieldId>}}` (scope key missing) and paths built from UI labels
+                    (e.g. `{{settings.<groupName>.<sectionLabel>.<fieldId>}}`) silently resolve
+                    to empty strings at runtime.
+              settingsForm:
+                description: Form definition for this flow grouping's settings UI.
+                allOf:
+                  - description: Form definition for this flow grouping's settings UI.
+                  - $ref: '#/components/schemas/Form'
+        apiGroupings:
+          type: array
+          description: |-
+            UI grouping configuration for APIs within the integration.
+
+            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`.
+          items:
+            type: object
+            additionalProperties: true
+            required:
+              - name
+            properties:
+              _id:
+                type: string
+                format: objectId
+                readOnly: true
+                description: Server-assigned grouping id.
+              name:
+                type: string
+                description: Display name for the API grouping section.
+                examples:
+                  - Inventory APIs
+              settings:
+                type: object
+                description: Group-level settings for APIs in this group.
+                additionalProperties: true
+                x-celigo-ai-guidance:
+                  - |-
+                    Unlike `flowGroupings[].settings`, this object does not round-trip through the
+                    public API: `settings` values sent on POST/PATCH/PUT are silently discarded and
+                    the persisted grouping keeps only `_id` and `name`. API executions also receive
+                    no integration-document-level settings in their runtime `settings` context, so
+                    grouping values could not be referenced from grouped APIs' steps in any case.
+                    For values an API's steps must read at runtime, define them in the step
+                    resource's own `settings`.
+              settingsForm:
+                description: Form definition for this API grouping's settings UI.
+                allOf:
+                  - description: Form definition for this API grouping's settings UI.
+                  - $ref: '#/components/schemas/Form'
+        netSuiteDistributedAdaptor:
+          type: object
+          description: |-
+            NetSuite distributed adaptor metadata (platform feature).
+
+            Only include if you are explicitly configuring distributed NetSuite adaptor behavior.
+          properties:
+            accountId:
+              type: string
+              examples:
+                - TSTDRV1234567
+              description: NetSuite account identifier.
+            environment:
+              type: string
+              description: NetSuite environment.
+              enum:
+                - production
+                - beta
+                - sandbox
+              x-enumDescriptions:
+                production: The NetSuite production environment.
+                beta: The NetSuite beta/release-preview environment.
+                sandbox: A dedicated NetSuite sandbox account environment.
+            integrationId:
+              type: string
+              examples:
+                - celigo_integration_app
+              description: Identifier used by the distributed adaptor for this integration.
+        _sourceId:
+          type: string
+          format: objectId
+          examples:
+            - 6842261335b64c0bcb308e4f
+          description: |-
+            System-assigned source identifier for the integration.
+
+            Typically system-managed; omit in normal create/update payloads.
+        sampleIntegration:
+          type: boolean
+          description: |-
+            Indicates this integration is a sample/demo integration (used for templates/examples).
+
+            Typically system-managed.
+        syncs:
+          type: boolean
+          description: |-
+            Indicates whether this integration uses Sync resources.
+
+            Typically system-managed.
+        aliases:
+          type: array
+          description: Named aliases that map to specific resources within the integration.
+          items:
+            type: object
+            properties:
+              alias:
+                type: string
+                description: Alias name for the resource reference.
+                examples:
+                  - ordersExport
+              description:
+                type: string
+                description: Description of what this alias represents.
+                examples:
+                  - Shopify orders export used across flows.
+              _exportId:
+                type: string
+                format: objectId
+                x-celigo-refModel: exports
+                examples:
+                  - 69f54d6a3469e3f5597848a1
+                description: Export referenced by this alias.
+              _importId:
+                type: string
+                format: objectId
+                x-celigo-refModel: imports
+                examples:
+                  - 69f54d6c1e7f3a22cc7848b2
+                description: Import referenced by this alias.
+              _flowId:
+                type: string
+                format: objectId
+                x-celigo-refModel: flows
+                examples:
+                  - 69f54d6b7009ea11abad707a
+                description: Flow referenced by this alias.
+              _connectionId:
+                type: string
+                format: objectId
+                x-celigo-refModel: connections
+                examples:
+                  - 626168f90b6ef816b50c82d7
+                description: Connection referenced by this alias.
+              _lookupCacheId:
+                type: string
+                format: objectId
+                x-celigo-refModel: lookupcaches
+                examples:
+                  - 68680d7111d1437fbcbce534
+                description: |-
+                  Lookup cache referenced by this alias. Added automatically when the
+                  cache is registered to the integration (the alias is a slug of the
+                  cache name), and must be removed before the cache can be deregistered.
+        iLMIgnore:
+          type: object
+          description: Configuration to exclude specific resources from integration lifecycle management.
+          additionalProperties: true
+    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`.
+          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
+    Integration:
+      type: object
+      description: Integration object as returned by the API.
+      required:
+        - _id
+        - name
+        - createdAt
+        - lastModified
+        - install
+        - installSteps
+        - uninstallSteps
+        - changeEditionSteps
+        - flowGroupings
+        - apiGroupings
+        - _registeredConnectionIds
+      allOf:
+        - $ref: '#/components/schemas/IntegrationBase'
+        - $ref: '#/components/schemas/ResourceResponse'
+        - type: object
+          properties:
+            _registeredConnectionIds:
+              type: array
+              readOnly: true
+              description: |-
+                Connections registered to this integration. Managed by the platform when users
+                register connections through the UI or the integration's registerConnection
+                operation; client-sent values are ignored (PUT-verified).
+              items:
+                type: string
+                format: objectId
+                x-celigo-refModel: connections
+              x-celigo-ai-guidance:
+                - |-
+                  This is managed by the platform when users register connections through the UI or when using the
+                  Integration “registerConnection” API operation. It is not set via normal integration create/update requests.
+            _registeredLookupCacheIds:
+              type: array
+              readOnly: true
+              description: Lookup caches registered to this integration, managed by the platform.
+              items:
+                type: string
+                format: objectId
+                x-celigo-refModel: lookupcaches
+    Request:
+      type: object
+      description: Fields that can be sent when creating or updating an integration.
+      required:
+        - name
+      allOf:
+        - $ref: '#/components/schemas/IntegrationBase'
+    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
+    JsonPatchOperation:
+      type: object
+      description: A single JSON Patch operation (RFC 6902).
+      required:
+        - op
+        - path
+      properties:
+        op:
+          type: string
+          enum:
+            - replace
+            - add
+            - remove
+          x-enumDescriptions:
+            replace: Replaces the value at the specified path.
+            add: Sets the value at the specified path.
+            remove: Removes the value at the specified path.
+          description: The operation to perform.
+        path:
+          type: string
+          description: |-
+            JSON Pointer (RFC 6901) to the field to patch. Only
+            whitelisted paths are accepted — unlisted paths return
+            `422` with `"<path> is not a whitelisted property"`.
+        value:
+          description: The new value to set. Required for `replace` and `add`, omit for `remove`.
+    JsonPatchRequest:
+      type: array
+      description: |-
+        A JSON Patch document (RFC 6902). Send an array of patch
+        operations on whitelisted fields — all other paths are rejected
+        with 422.
+      minItems: 1
+      items:
+        $ref: '#/components/schemas/JsonPatchOperation'
+    CloneRequest:
+      type: object
+      description: Request body for cloning an integration.
+      required:
+        - connectionMap
+      properties:
+        name:
+          type: string
+          description: Name for the cloned integration. If omitted, the server generates "Clone - <original name>".
+          examples:
+            - Clone - Integration 1
+        description:
+          type: string
+          description: Description for the cloned integration.
+          examples:
+            - Cloned copy of the Shopify to NetSuite orders integration.
+        _envId:
+          type: string
+          format: objectId
+          x-celigo-refModel: environments
+          description: |
+            Target environment _id. When provided, the clone is created in the
+            specified environment instead of the current one. Use
+            GET /v1/environments to list available environments and their _ids.
+            Omit to clone within the same environment.
+          examples:
+            - 67b123456789abcdef012345
+        connectionMap:
+          type: object
+          description: |
+            Mapping of original connection _ids to replacement connection _ids.
+            Keys are source connection _ids on the original integration; values
+            are target connection _ids in the destination environment.
+          additionalProperties:
+            type: string
+          example:
+            5f7c579b6411271af4e7cefa: 64a1234567890abcdef12345
+            5f7c579b6411271af4e7cefb: 64a1234567890abcdef12346
+      additionalProperties: true
+    CloneResponse:
+      description: Response body for a clone operation. Some clone endpoints return the cloned resource, while others may return a list of related created resources.
+      oneOf:
+        - title: integration
+          $ref: '#/components/schemas/Integration'
+        - title: resource list
+          type: array
+          items:
+            type: object
+            properties:
+              model:
+                type: string
+                description: Model name of the created resource (e.g., Flow, Export, Import).
+                examples:
+                  - Flow
+              _id:
+                type: string
+                format: objectId
+                description: Unique id of the created resource.
+                examples:
+                  - 68f52162f00a35a1b26eaafb
+              name:
+                type: string
+                description: Optional name of the created resource.
+                examples:
+                  - Clone - Shopify orders → NetSuite
+            required:
+              - _id
+    ClonePreviewResponse:
+      type: object
+      description: |
+        Preview of the resources that would be created by a clone operation.
+        Each object in the `objects` array represents a resource that will be
+        cloned, including the target resource and all transitive dependencies
+        (connections, scripts, exports, imports, etc.).
+      properties:
+        objects:
+          type: array
+          description: |
+            List of resources that would be created by the clone. Always includes
+            the target resource and may include transitive dependencies such as
+            connections, scripts, exports, imports, async helpers, and lookup caches.
+          items:
+            type: object
+            properties:
+              model:
+                type: string
+                description: |
+                  The model type of the resource. Observed values include
+                  AsyncHelper, Connection, Export, Flow, Import, Integration,
+                  LookupCache, Script, and Tool.
+                examples:
+                  - Flow
+              doc:
+                type: object
+                description: The full resource document that would be created by the clone.
+                additionalProperties: true
+        stackRequired:
+          type: boolean
+          description: Whether the clone requires a stack (connector-level) environment to proceed.
+        _stackId:
+          type:
+            - string
+            - 'null'
+          description: The stack id associated with the resource, or null if no stack is involved.
+          examples:
+            - 5f8d43a1b9e5a80011a35f2c
+    Revision:
+      type: object
+      description: |-
+        Integration Lifecycle Management (ILM) revision entry. Revisions capture point-in-time state of an
+        integration and drive snapshot, pull, and revert workflows across environments.
+      properties:
+        _id:
+          type: string
+          format: objectId
+          description: Revision id.
+          examples:
+            - 6a28d2af6d42eb08f8e863e7
+        _integrationId:
+          type: string
+          format: objectId
+          description: Id of the integration this revision belongs to.
+          x-celigo-refModel: integrations
+          examples:
+            - 6842261335b64c0bcb308e4f
+        _fromIntegrationId:
+          type: string
+          format: objectId
+          description: |-
+            For `pull` / `revert` revisions, the id of the source integration the changes originated from.
+            For `snapshot` revisions this equals `_integrationId`.
+          x-celigo-refModel: integrations
+          examples:
+            - 6842261335b64c0bcb308e4f
+        _fromIntegrationEnvId:
+          type: string
+          format: objectId
+          description: Environment id of the source integration.
+          examples:
+            - 67b123456789abcdef012345
+        fromIntegrationName:
+          type: string
+          description: Display name of the source integration at revision time (frozen copy).
+          examples:
+            - Shopify → NetSuite Orders
+        type:
+          type: string
+          description: Revision kind.
+          enum:
+            - snapshot
+            - pull
+            - revert
+          x-enumDescriptions:
+            snapshot: Point-in-time capture of the current integration state.
+            pull: Changes pulled in from a related integration in another environment or clone.
+            revert: Restoration of the integration to a prior revision state.
+        status:
+          type: string
+          description: |-
+            Lifecycle status. `completed` revisions are terminal; `inprogress` (pull/revert) revisions can
+            be diffed and either applied or canceled. `failed` revisions surfaced an error mid-process;
+            `canceled` revisions were aborted before apply.
+          enum:
+            - inprogress
+            - completed
+            - failed
+            - canceled
+          x-enumDescriptions:
+            inprogress: The revision is currently being prepared and can be diffed, applied, or canceled.
+            completed: The revision has been finalized and applied successfully.
+            failed: The revision encountered an error during processing.
+            canceled: The revision was aborted before being applied.
+        description:
+          type: string
+          description: Human-entered label describing what the revision captures.
+          examples:
+            - Stable baseline before deploying v2
+        beforeRevisionHash:
+          type: string
+          description: Content hash of the integration state prior to this revision.
+          examples:
+            - 34b7ae8d56563e242bc0bd42fd28874442657e58
+        transactionHash:
+          type: string
+          description: |-
+            Transaction hash of the revision write. Present on `pull` and `revert` revisions; absent on
+            plain snapshots.
+          examples:
+            - a1f3c7e90b2d4856ff19c0e7a3b5d28f4c6e0179
+        afterRevisionHash:
+          type: string
+          description: |-
+            Content hash of the integration state after the revision was applied. Present on `pull` and
+            `revert` revisions.
+          examples:
+            - 7d9e2b4a1c3f5068ab82d4e0fc16937255ab8c40
+        _revertToRevisionId:
+          type: string
+          format: objectId
+          description: For `revert` revisions, the id of the target revision being reverted to.
+          examples:
+            - 6a28d2af6d42eb08f8e863e7
+        revertToRevisionHash:
+          type: string
+          description: |-
+            Content hash of the revision being reverted to — echoes `beforeRevisionHash` of the
+            `_revertToRevisionId` revision.
+          examples:
+            - 34b7ae8d56563e242bc0bd42fd28874442657e58
+        _createdByUserId:
+          type: string
+          format: objectId
+          x-celigo-refModel: users
+          examples:
+            - 624774a6a7574d3ed9f9a5cc
+          description: User id of the creator.
+        installSteps:
+          type: array
+          description: |-
+            Install steps associated with the revision (empty for normal snapshots; populated when the
+            revision is part of a pull/revert that requires user-facing install actions).
+          items:
+            type: object
+            additionalProperties: true
+        createdAt:
+          type: string
+          format: date-time
+          description: When the revision was created.
+          examples:
+            - '2026-06-10T02:57:51.483Z'
+        lastModified:
+          type: string
+          format: date-time
+          description: Last update time of the revision record.
+          examples:
+            - '2026-06-10T02:57:51.483Z'
+    RevisionsResponse:
+      type: array
+      description: |-
+        List of revisions for an integration, newest first. Empty history returns
+        an empty response rather than `[]`.
+      items:
+        $ref: '#/components/schemas/Revision'
+    RevisionCreateRequest:
+      type: object
+      description: |-
+        Request body for `POST /v1/integrations/{_id}/revisions/create`. Creates a `snapshot` revision of
+        the integration's current state.
+      properties:
+        description:
+          type: string
+          minLength: 1
+          examples:
+            - Stable baseline before deploying v2
+          description: |-
+            Human-readable label shown in the Revisions tab. Required — the UI enforces a non-empty value
+            and so does the API.
+      required:
+        - description
+    RevisionDiffResponse:
+      type: object
+      description: |-
+        Structured before/after diff for a revision. Only available while the revision is in a `pending`
+        state (e.g. a queued `pull` or `revert`). Completed snapshot revisions are read-only and return
+        HTTP 400 `invalid_revision_state` — the diff is computed during the apply window, not retained.
+
+        Shape is the platform's internal diff document — a map of resource type → per-resource
+        before/after blocks. Treated as an opaque envelope here; specific field layout is not guaranteed
+        stable across platform versions.
+      additionalProperties: true
+    IntegrationErrorsResponse:
+      type: array
+      description: |-
+        Per-flow open-error summary for an integration. One entry per flow in the integration; flows with
+        zero open errors still appear so callers see the full roster. Empty integrations (no flows) return
+        HTTP 204 with no body.
+      items:
+        type: object
+        properties:
+          _flowId:
+            type: string
+            format: objectId
+            description: Id of the flow these counts apply to.
+            x-celigo-refModel: flows
+            examples:
+              - 69497fc443fc1f9a03d31bd9
+          numError:
+            type: integer
+            minimum: 0
+            description: |-
+              Count of currently open (unresolved) errors on this flow. Only
+              errors within the account's data-retention window are counted —
+              older open errors are excluded.
+            examples:
+              - 2
+          lastErrorAt:
+            type: string
+            format: date-time
+            description: |-
+              Timestamp of the most recent open error on this flow, scoped to
+              the account's data-retention window. Omitted when `numError` is 0.
+            examples:
+              - '2026-04-12T21:51:39.257Z'
+    IntegrationErrorsAssignRequest:
+      type: object
+      description: |-
+        Request body for `PUT /v1/integrations/{_id}/errors/assign`. Assigns a batch of open errors —
+        across any flow in the integration — to a user by email. Errors remain open; only the assignee
+        tag changes.
+      properties:
+        errorIds:
+          type: array
+          description: |-
+            Ids of open errors to assign. Obtain from the per-step endpoint
+            `GET /v1/flows/{_flowId}/{_stepId}/errors` → each entry's `errorId`. The integration-level
+            `GET /v1/integrations/{_id}/errors` only returns per-flow *aggregates* (no individual error
+            ids), so the error ids must come from the per-step endpoint. Platform caps batch size around
+            ~1000; chunk larger sets client-side.
+          minItems: 1
+          items:
+            type: string
+            examples:
+              - '6044134138'
+        email:
+          type: string
+          format: email
+          examples:
+            - user@example.com
+          description: |-
+            Email of the account user to assign the errors to. Must match an existing user with access to
+            the account; the API does not create users implicitly and rejects unknown emails.
+      required:
+        - errorIds
+        - email
+    IntegrationErrorsAssignResponse:
+      type: object
+      description: |-
+        Echo of the mutation — ids of errors that were reassigned. Mirrors the shape of the per-step
+        `PUT /v1/flows/{_id}/{_stepId}/errors/assign` response.
+      properties:
+        errorsToReturn:
+          type: array
+          description: Error ids that were affected by the mutation.
+          items:
+            type: string
+            examples:
+              - '6044134138'
+    CloneFamilyResponse:
+      type: array
+      description: |-
+        Members of an integration's clone family — the original integration plus every clone (including
+        clones of clones, across environments). Used by ILM to decide which integrations can pull from or
+        push to the current one.
+      items:
+        type: object
+        description: One integration in the clone family.
+        properties:
+          _id:
+            type: string
+            format: objectId
+            description: Integration id.
+            x-celigo-refModel: integrations
+            examples:
+              - 6842261335b64c0bcb308e4f
+          name:
+            type: string
+            description: Display name of the integration.
+            examples:
+              - Shopify → NetSuite Orders
+          _envId:
+            type: string
+            format: objectId
+            x-celigo-refModel: environments
+            examples:
+              - 67b123456789abcdef012345
+            description: Environment id the integration belongs to.
+        additionalProperties: true
+    ILMIgnoreResponse:
+      type: object
+      description: |-
+        Catalog of resource-type → field-path lists that are *available* to be ignored during ILM pulls
+        and reverts. This is the full menu of what can be configured — to see the current ignore
+        configuration, read the `iLMIgnore` field on the integration itself via
+        `GET /v1/integrations/{_id}`.
+
+        Keys are lowercase resource type names (e.g. `integration`, `flow`, `export`, `import`,
+        `connection`, `script`). Each value is an array of dot-path strings naming fields that can be
+        excluded. Only resource types that have configurable ignores appear as keys.
+      additionalProperties:
+        type: array
+        description: Field paths (dotted) that can be ignored for this resource type.
+        items:
+          type: string
+      example:
+        integration:
+          - settings.general.description
+          - settings.general.name
+        flow:
+          - scheduling.startTime
+          - disabled
+        export:
+          - http.relativeURI
+          - delta.dateField
+        import:
+          - http.relativeURI
+          - mapping
+        connection:
+          - http.baseURI
+          - http.auth.token.token
+    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
+        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
+    400-bad-request:
+      description: |
+        Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: invalid_request
+                    message: The request body failed validation.
+    422-unprocessable-entity:
+      description: |
+        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: unprocessable_entity
+                    message: The request could not be processed due to a semantic error.
+    404-not-found:
+      description: |
+        Not found. The requested resource does not exist or is not visible to the caller.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: not_found
+                    message: The requested resource was not found.
+    422-dependency-conflict:
+      description: |-
+        The resource has dependents that must be deleted first. Each entry
+        in the `errors` array names one blocking resource.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: dependencies_not_deleted
+                    message: export 6902d88c10b42b2eaac9b2a1 must be deleted before you can delete connection 6398ddf316be761fb16a6523
+x-enable-proxy: true
+x-internal: false