@celigo/api-specs 0.2.1

package/dist/environment.yml

@@ -0,0 +1,568 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: Environments
+  description: API for managing Celigo environments — isolated partitions of an account, each with its own users and integrations.
+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: Environments
+    description: |-
+      Environments partition a Celigo account into separate, isolated spaces.
+      Each environment has its own users, integrations, connections, and flows,
+      functioning like independent accounts under a single license.
+
+      Requires the environments feature to be enabled. Every account with the
+      feature starts with a Production environment that cannot be disabled.
+
+      ## Environment schema
+
+      {% openapi-schemas spec="environment" schemas="Environment" grouped="true" %}
+paths:
+  /v1/environments:
+    get:
+      x-internal: false
+      summary: List environments
+      operationId: listEnvironments
+      tags:
+        - Environments
+      description: |-
+        Returns all environments in the account. Requires the environments
+        feature to be enabled -- accounts without it receive
+        `feature_not_enabled`. Every account with the feature has at least
+        one environment (Production). The full list is returned in a single
+        unpaginated response.
+      responses:
+        '200':
+          description: List of environments.
+          x-celigo-ai-guidance:
+            - Successfully retrieved list of environments
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Environment'
+              examples:
+                default:
+                  value:
+                    - _id: 68f76c67f7876d161ffb9c52
+                      _envUserId: 624cb0346309dc3a543733a2
+                      name: Production
+                      enabled: true
+                      lastModified: '2025-10-21T11:20:07.448Z'
+                      createdAt: '2025-10-21T11:20:07.448Z'
+                    - _id: 69150a05578417f9fa40dbe4
+                      _envUserId: 69150a05578417f9fa40dbe6
+                      name: Sandbox
+                      description: Pre-production testing environment
+                      enabled: true
+                      lastModified: '2025-11-12T22:28:22.433Z'
+                      createdAt: '2025-11-12T22:28:22.433Z'
+        '204':
+          description: No environments exist in the account
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+    post:
+      x-internal: false
+      summary: Create an environment
+      operationId: createEnvironment
+      tags:
+        - Environments
+      description: |-
+        Creates a new environment. The environment starts disabled; use the
+        toggle endpoint to enable it. `name` is the only required field and
+        must be unique within the account.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              minimal:
+                summary: Minimal create
+                value:
+                  name: Staging
+              withDescription:
+                summary: With description
+                value:
+                  name: Staging
+                  description: Pre-production testing environment
+      responses:
+        '201':
+          description: Environment created.
+          x-celigo-ai-guidance:
+            - environment created successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Environment'
+              examples:
+                default:
+                  value:
+                    _id: 60a2c4e6f321d800129a1a3c
+                    _envUserId: 60a2c4e6f321d800129a1a3e
+                    name: Staging
+                    description: Pre-production testing environment
+                    enabled: false
+                    apim: {}
+                    lastModified: '2025-08-10T14:22:33.000Z'
+                    createdAt: '2025-08-10T14:22:33.000Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/environments/{_id}:
+    get:
+      x-internal: false
+      summary: Get an environment
+      operationId: getEnvironment
+      tags:
+        - Environments
+      description: Retrieves a single environment by ID.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Environment ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: environments
+      responses:
+        '200':
+          description: Environment details.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Environment'
+              examples:
+                production:
+                  summary: Production environment
+                  value:
+                    _id: 68f76c67f7876d161ffb9c52
+                    _envUserId: 624cb0346309dc3a543733a2
+                    name: Production
+                    enabled: true
+                    lastModified: '2025-10-21T11:20:07.448Z'
+                    createdAt: '2025-10-21T11:20:07.448Z'
+                sandbox:
+                  summary: Sandbox with APIM
+                  value:
+                    _id: 69150a05578417f9fa40dbe4
+                    _envUserId: 69150a05578417f9fa40dbe6
+                    name: Sandbox
+                    description: Pre-production testing environment
+                    enabled: true
+                    apim:
+                      environmentId: 0b893522-51b3-482f-8935-2251b3b82f28
+                      environmentHRID: sandbox
+                      groupId: 0b37df28-5543-40dc-b7df-28554310dc1b
+                    lastModified: '2025-11-12T22:28:22.433Z'
+                    createdAt: '2025-11-12T22:28:22.433Z'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    put:
+      x-internal: false
+      summary: Update an environment
+      operationId: updateEnvironment
+      tags:
+        - Environments
+      description: |-
+        Replaces an environment's mutable fields (`name`, `description`,
+        `apim`). To enable or disable an environment, use the toggle
+        endpoint instead.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Environment ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: environments
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              rename:
+                summary: Rename an environment
+                value:
+                  name: Staging
+              updateDescription:
+                summary: Update description
+                value:
+                  name: Sandbox
+                  description: Updated environment description
+      responses:
+        '200':
+          description: Updated environment.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Environment'
+              examples:
+                updated:
+                  summary: Sandbox environment after a description update
+                  value:
+                    _id: 69150a05578417f9fa40dbe4
+                    _envUserId: 69150a05578417f9fa40dbe6
+                    name: Sandbox
+                    description: Updated environment description
+                    enabled: true
+                    apim:
+                      environmentId: 0b893522-51b3-482f-8935-2251b3b82f28
+                      environmentHRID: sandbox
+                      groupId: 0b37df28-5543-40dc-b7df-28554310dc1b
+                    createdAt: '2025-11-12T22:28:22.433Z'
+                    lastModified: '2026-06-09T17:45:12.882Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/environments/{_id}/enable:
+    put:
+      x-internal: false
+      operationId: toggleEnvironment
+      tags:
+        - Environments
+      summary: Toggle an environment on or off
+      description: |-
+        Toggles the enabled state of an environment -- a disabled environment
+        becomes enabled and vice versa. The Production environment cannot be
+        disabled, and pending user invitations must be resolved before
+        disabling any environment.
+
+        Requires a `Content-Type: application/json` header even though no
+        request body is needed.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Environment ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: environments
+      responses:
+        '204':
+          description: Environment state toggled.
+        '400':
+          description: The Production environment cannot be disabled.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - code: disable_not_allowed
+                    message: Production environment cannot be disabled.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          description: Pending user invitations must be resolved before disabling.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - code: resolve_pending_invitation
+                    message: Please resolve pending invitations before disabling this environment.
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    EnvironmentBase:
+      type: object
+      description: Writable fields shared by the request and response schemas.
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 100
+          description: Display name for the environment. Must be unique within the account.
+          x-celigo-ai-guidance:
+            - |-
+              Enter a clear and distinguishable name.
+              A unique identifier will prove helpful later when selecting it from a list of
+              environments in your account.
+          examples:
+            - Sandbox
+        description:
+          type:
+            - string
+            - 'null'
+          description: |-
+            Free-text description of the environment's purpose. Null on environments
+            provisioned automatically by the platform; descriptions set through the
+            UI or API are strings. When writing, send a string or omit the field.
+          x-celigo-ai-guidance:
+            - |-
+              Enter a clear description of the environment.
+              You can include details like who should use the environment,
+              the purpose of the environment, and common usage examples.
+          examples:
+            - Pre-production testing environment
+        apim:
+          type: object
+          description: API Management metadata linking this environment to its APIM counterpart. Typically managed by APIM workflows.
+          x-celigo-ai-guidance:
+            - |-
+              This links the integrator.io environment to its corresponding environment and
+              configuration in the API management system.
+              In most cases these values are created/managed by APIM workflows;
+              only set them if you are explicitly configuring APIM integration for the environment.
+          properties:
+            environmentId:
+              type: string
+              description: APIM environment identifier.
+              x-celigo-ai-guidance:
+                - The APIM environment identifier associated with this integrator.io environment.
+              examples:
+                - 0b893522-51b3-482f-8935-2251b3b82f28
+            environmentHRID:
+              type: string
+              description: Human-readable APIM environment slug used in URLs.
+              examples:
+                - sandbox
+            groupId:
+              type: string
+              description: APIM group identifier for access control.
+              x-celigo-ai-guidance:
+                - The APIM group identifier used for access control/role assignments within this environment.
+              examples:
+                - 0b37df28-5543-40dc-b7df-28554310dc1b
+    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
+    Environment:
+      type: object
+      required:
+        - _id
+        - _envUserId
+        - name
+        - enabled
+        - createdAt
+        - lastModified
+      description: Environment object as returned by the API.
+      allOf:
+        - $ref: '#/components/schemas/EnvironmentBase'
+        - $ref: '#/components/schemas/ResourceResponse'
+        - type: object
+          properties:
+            _envUserId:
+              type: string
+              format: objectId
+              readOnly: true
+              description: Account user ID that owns this environment.
+              x-celigo-refModel: users
+              examples:
+                - 624cb0346309dc3a543733a2
+            enabled:
+              type: boolean
+              readOnly: true
+              description: When true, the environment is currently enabled. Controlled via the toggle endpoint, not create/update.
+              x-celigo-ai-guidance:
+                - Whether the environment is enabled. This is managed via the UI (and/or a dedicated enable/disable operation), not via the standard create/update request body.
+            isMigrated:
+              type: boolean
+              readOnly: true
+              description: When true, the environment has been migrated from legacy sandbox. Present only on enterprise accounts.
+    Request:
+      type: object
+      description: Fields for creating or updating an environment.
+      x-celigo-ai-guidance:
+        - Fields that can be sent when creating or updating a environment
+      required:
+        - name
+      allOf:
+        - $ref: '#/components/schemas/EnvironmentBase'
+    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
+  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.
+x-enable-proxy: true
+x-internal: false