@celigo/api-specs 0.2.1

package/dist/stack.yml

@@ -0,0 +1,1291 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: Stacks
+  description: Manage stack execution environments for integrations.
+  x-celigo-ai-guidance:
+    - |-
+      API for managing stacks (server stacks and AWS Lambda stacks) used to run extension code (hooks,
+      wrappers, scripts) in integrator.io.
+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: Stacks
+    description: |-
+      Stacks are execution environments that run custom extension code for integrations. Two types are supported: **server** (self-hosted) and **lambda** (AWS Lambda).
+
+      ## Stack schema
+
+      {% openapi-schemas spec="stack" schemas="Stack" grouped="true" %}
+paths:
+  /v1/stacks:
+    get:
+      x-internal: false
+      summary: List stacks
+      description: Returns all stacks configured in the account.
+      x-celigo-ai-guidance:
+        - Returns a list of stacks configured in the account (server stacks and lambda stacks).
+      operationId: listStacks
+      tags:
+        - Stacks
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          description: Maximum number of stacks to return per page.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            default: 1000
+            examples:
+              - 100
+        - $ref: '#/components/parameters/Include'
+        - $ref: '#/components/parameters/Exclude'
+      responses:
+        '200':
+          description: Array of stack objects.
+          x-celigo-ai-guidance:
+            - Successfully retrieved list of stacks.
+          headers:
+            Link:
+              description: |-
+                RFC 5988 pagination links. When more pages remain, includes a
+                `<...>; rel="next"` entry with an `after` cursor; absent on the
+                final page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Stack'
+              examples:
+                mixed:
+                  value:
+                    - _id: 62100ec7abb76c310718b0f0
+                      name: Realtime-ify Stack
+                      type: server
+                      lastModified: '2022-02-18T21:25:27.903Z'
+                      createdAt: '2022-02-18T21:25:27.864Z'
+                      server:
+                        systemToken: '******'
+                        hostURI: https://my-stack-server.example.com:3000
+                    - _id: 62b4e242bffb3066e9e0a80d
+                      name: Order Processing Lambda
+                      type: lambda
+                      lastModified: '2025-08-10T14:22:33.000Z'
+                      createdAt: '2022-06-23T21:59:30.448Z'
+                      lambda:
+                        accessKeyId: AKIAIOSFODNN7EXAMPLE
+                        secretAccessKey: '******'
+                        awsRegion: us-east-1
+                        functionName: processOrders
+                        language: Node.js
+        '204':
+          description: No stacks exist in the account.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    post:
+      x-internal: false
+      summary: Create a stack
+      description: |-
+        Creates a new stack. For server stacks, retrieve the system token
+        after creation via `GET /v1/stacks/{_id}/systemToken`.
+      x-celigo-ai-guidance:
+        - |-
+          - For `type=server`, provide `server.hostURI` (and optional `server.ipRanges`).
+          - For `type=lambda`, provide AWS credentials and function details under `lambda`.
+      operationId: createStack
+      tags:
+        - Stacks
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              serverStack:
+                summary: Server stack
+                value:
+                  name: Production Server Stack
+                  type: server
+                  server:
+                    hostURI: https://my-stack-server.example.com:3000
+              lambdaStack:
+                summary: Lambda stack
+                value:
+                  name: Order Processing Lambda
+                  type: lambda
+                  lambda:
+                    accessKeyId: AKIAIOSFODNN7EXAMPLE
+                    secretAccessKey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+                    awsRegion: us-east-1
+                    functionName: processOrders
+      responses:
+        '201':
+          description: Created stack.
+          x-celigo-ai-guidance:
+            - Stack created successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Stack'
+              examples:
+                serverStack:
+                  summary: Created server stack
+                  value:
+                    _id: 673e35899096693f4572c83c
+                    name: Production Server Stack
+                    type: server
+                    lastModified: '2024-11-20T19:16:25.412Z'
+                    createdAt: '2024-11-20T19:16:25.412Z'
+                    server:
+                      systemToken: '******'
+                      hostURI: https://my-stack-server.example.com:3000
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/stacks/{_id}:
+    get:
+      x-internal: false
+      summary: Get a stack
+      description: Returns a single stack by ID.
+      operationId: getStackById
+      tags:
+        - Stacks
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: stacks
+          description: Stack ID.
+      responses:
+        '200':
+          description: Stack object.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Stack'
+              examples:
+                serverStack:
+                  summary: Server stack
+                  value:
+                    _id: 62100ec7abb76c310718b0f0
+                    name: Realtime-ify Stack
+                    type: server
+                    lastModified: '2022-02-18T21:25:27.903Z'
+                    createdAt: '2022-02-18T21:25:27.864Z'
+                    server:
+                      systemToken: '******'
+                      hostURI: https://my-stack-server.example.com:3000
+                lambdaStack:
+                  summary: Lambda stack
+                  value:
+                    _id: 62b4e242bffb3066e9e0a80d
+                    name: Order Processing Lambda
+                    type: lambda
+                    lastModified: '2025-08-10T14:22:33.000Z'
+                    createdAt: '2022-06-23T21:59:30.448Z'
+                    lambda:
+                      accessKeyId: AKIAIOSFODNN7EXAMPLE
+                      secretAccessKey: '******'
+                      awsRegion: us-east-1
+                      functionName: processOrders
+                      language: Node.js
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    put:
+      x-internal: false
+      summary: Update a stack
+      description: |-
+        Updates a stack. Omitting the config object clears optional fields
+        like `framework`. To rotate a server stack's system token, use
+        `DELETE /v1/stacks/{_id}/systemToken` instead.
+      operationId: updateStack
+      tags:
+        - Stacks
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: stacks
+          description: Stack ID.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              serverStack:
+                summary: Update server stack
+                value:
+                  name: Production Server Stack
+                  type: server
+                  server:
+                    hostURI: https://my-stack-server.example.com:3000
+              lambdaStack:
+                summary: Update lambda stack
+                value:
+                  name: Order Processing Lambda
+                  type: lambda
+                  lambda:
+                    accessKeyId: AKIAIOSFODNN7EXAMPLE
+                    secretAccessKey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+                    awsRegion: us-east-1
+                    functionName: processOrders
+      responses:
+        '200':
+          description: Updated stack.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Stack'
+              examples:
+                serverStack:
+                  summary: Renamed server stack
+                  value:
+                    _id: 62100ec7abb76c310718b0f0
+                    name: Production Server Stack
+                    type: server
+                    lastModified: '2025-09-04T08:17:42.901Z'
+                    createdAt: '2022-02-18T21:25:27.864Z'
+                    server:
+                      systemToken: '******'
+                      hostURI: https://my-stack-server.example.com:3000
+        '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'
+      x-celigo-ai-guidance:
+        - |-
+          - You can update `name`, `framework`, and the config object for the active `type`.
+          - Secrets are write-only: provide a new secret value in the request to replace it; responses return masked values.
+    delete:
+      x-internal: false
+      summary: Delete a stack
+      description: |-
+        Deletes a stack. Soft-deleted and retained in the recycle bin for
+        30 days.
+      operationId: deleteStack
+      tags:
+        - Stacks
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: stacks
+          description: Stack ID.
+      responses:
+        '204':
+          description: Stack deleted.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-dependency-conflict'
+  /v1/stacks/{_id}/systemToken:
+    get:
+      x-internal: false
+      summary: Get stack system token (server stacks only)
+      description: Returns the unmasked system token for a server stack.
+      operationId: getStackSystemToken
+      tags:
+        - Stacks
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: stacks
+          description: Stack ID.
+      responses:
+        '200':
+          description: System token object.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SystemTokenResponse'
+              examples:
+                default:
+                  value:
+                    systemToken: 465f5c448f434bc5ae3753bc83d96feb
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            Stack not found, or the stack is not a server stack. The error
+            message is "Stack of type server not found." in both cases.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not_server_stack:
+                  value:
+                    errors:
+                      - message: Stack of type server not found.
+      x-celigo-ai-guidance:
+        - |-
+          Returns the **actual** `systemToken` for a server stack.
+          Note: `server.systemToken` on the normal stack response is masked (`******`). Use this endpoint to retrieve the real token.
+    delete:
+      x-internal: false
+      summary: Recycle stack system token (server stacks only)
+      description: |-
+        Rotates (recycles) the server stack's system token. The old token is
+        immediately invalidated. Retrieve the new token via
+        `GET /v1/stacks/{_id}/systemToken`.
+      operationId: recycleStackSystemToken
+      tags:
+        - Stacks
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: stacks
+          description: Stack ID.
+      responses:
+        '204':
+          description: Token recycled.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: Stack not found, or the stack is not a server stack.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not_server_stack:
+                  value:
+                    errors:
+                      - message: Stack of type server not found.
+      x-celigo-ai-guidance:
+        - |-
+          Rotates (recycles) the server stack's system token.
+          After this operation, any clients using the old token must be updated to use the new token.
+  /v1/stacks/{_id}/audit:
+    get:
+      x-internal: false
+      summary: Get audit log for a stack
+      description: |-
+        Returns the change history for a stack. Each entry records a mutation
+        event with who made the change, when, and which fields were affected.
+      tags:
+        - Stacks
+      operationId: getStackAudit
+      parameters:
+        - name: _id
+          in: path
+          description: Stack ID.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: stacks
+            examples:
+              - 62b4e242bffb3066e9e0a80d
+        - name: limit
+          in: query
+          description: Maximum number of audit entries to return per page.
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            default: 1000
+            examples:
+              - 100
+        - name: after
+          in: query
+          required: false
+          description: |-
+            Opaque pagination cursor for the next page. Take it from the `after` value in the `Link`
+            response header's `rel="next"` URL rather than constructing it.
+          schema:
+            type: string
+            examples:
+              - W3siJGRhdGUiOiIyMDI2LTA1LTAxVDAwOjAwOjAwLjAwMFoifSwiNjAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwIl0
+        - name: from
+          in: query
+          required: false
+          description: Only return entries at or after this timestamp.
+          schema:
+            type: string
+            format: date-time
+            examples:
+              - '2026-05-01T00:00:00.000Z'
+        - name: to
+          in: query
+          required: false
+          description: Only return entries at or before this timestamp.
+          schema:
+            type: string
+            format: date-time
+            examples:
+              - '2026-05-31T23:59:59.999Z'
+        - name: action
+          in: query
+          required: false
+          description: Filter by the change type. Maps to the `event` field on each entry.
+          schema:
+            type: string
+            enum:
+              - create
+              - update
+              - delete
+              - view
+              - restore
+              - purge
+              - signin
+              - signout
+              - purgelogs
+            examples:
+              - update
+            x-enumDescriptions:
+              create: A resource was created.
+              update: A resource was modified.
+              delete: A resource was deleted (moved to recycle bin).
+              view: A resource was viewed or accessed.
+              restore: A resource was restored from the recycle bin.
+              purge: A resource was permanently purged from the recycle bin.
+              signin: A user signed in to the account.
+              signout: A user signed out of the account.
+              purgelogs: Execution logs were purged for a resource.
+        - name: source
+          in: query
+          required: false
+          description: Filter by how the change was initiated.
+          schema:
+            type: string
+            enum:
+              - ui
+              - api
+              - system
+              - connector
+              - script
+              - sso
+            examples:
+              - ui
+            x-enumDescriptions:
+              ui: Change made through the Celigo web UI.
+              api: Change made via the REST API.
+              system: Change made automatically by the platform.
+              connector: Change made by an Integration App (connector) process.
+              script: Change made by a custom script execution.
+              sso: Change triggered by an SSO authentication event.
+        - name: _byUserId
+          in: query
+          required: false
+          description: Filter to changes performed by a single user.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: users
+            examples:
+              - 624cb0346309dc3a543733a2
+      responses:
+        '200':
+          description: Array of audit entries, newest first.
+          headers:
+            Link:
+              description: |-
+                RFC 5988 pagination link. Includes `<...>; rel="next"` with an
+                `after` cursor when more entries exist; absent on the final page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    _id:
+                      type: string
+                      format: objectId
+                      description: Unique identifier for this audit entry.
+                      examples:
+                        - 69f63dd77009ea11abf0bce3
+                    resourceType:
+                      type: string
+                      description: Always `stack` for this endpoint.
+                      examples:
+                        - stack
+                    _resourceId:
+                      type: string
+                      format: objectId
+                      x-celigo-refModel: stacks
+                      description: ID of the stack this entry belongs to.
+                      examples:
+                        - 62b4e242bffb3066e9e0a80d
+                    event:
+                      type: string
+                      description: Type of change that occurred.
+                      enum:
+                        - create
+                        - update
+                        - delete
+                      x-enumDescriptions:
+                        create: Stack was created.
+                        update: Stack was modified.
+                        delete: Stack was soft-deleted (moved to recycle bin).
+                    source:
+                      type: string
+                      description: How the change was initiated.
+                      enum:
+                        - api
+                        - ui
+                        - system
+                      x-enumDescriptions:
+                        api: Change made via the REST API.
+                        ui: Change made through the Celigo UI.
+                        system: Change made by an automated platform process.
+                    time:
+                      type: string
+                      format: date-time
+                      description: When the change occurred.
+                      examples:
+                        - '2026-05-02T18:09:26.975Z'
+                    byUser:
+                      type: object
+                      description: User who made the change.
+                      properties:
+                        _id:
+                          type: string
+                          format: objectId
+                          x-celigo-refModel: users
+                          description: User ID.
+                          examples:
+                            - 624cb0346309dc3a543733a2
+                        email:
+                          type: string
+                          format: email
+                          description: User email address.
+                          examples:
+                            - user@example.com
+                        name:
+                          type: string
+                          description: User display name.
+                          examples:
+                            - Tyler Lamparter
+                    fieldChanges:
+                      type: array
+                      description: Fields that were modified.
+                      items:
+                        type: object
+                        properties:
+                          fieldPath:
+                            type: string
+                            description: Dot-notation path of the changed field.
+                            examples:
+                              - name
+                          oldValue:
+                            description: Previous value (absent on create).
+                          newValue:
+                            description: New value (absent on delete).
+                    deletedInfo:
+                      type: object
+                      description: Metadata about the deleted resource. Present on `delete` events.
+                      properties:
+                        name:
+                          type: string
+                          description: Name of the resource at the time of deletion.
+                          examples:
+                            - Order Processing Lambda
+              examples:
+                default:
+                  value:
+                    - _id: 69f63dd77009ea11abf0bce3
+                      resourceType: stack
+                      _resourceId: 62b4e242bffb3066e9e0a80d
+                      source: api
+                      event: update
+                      time: '2026-05-02T18:09:26.975Z'
+                      byUser:
+                        _id: 624cb0346309dc3a543733a2
+                        email: user@example.com
+                        name: Tyler Lamparter
+                      fieldChanges:
+                        - fieldPath: name
+                          oldValue: AWS test
+                          newValue: AWS
+        '204':
+          description: No audit entries exist for this stack.
+        '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/stacks/{_id}/dependencies:
+    get:
+      x-internal: false
+      operationId: listStackDependencies
+      tags:
+        - Stacks
+      summary: List dependencies of a stack
+      description: Returns the set of resources that depend on the specified stack.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Stack ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: stacks
+      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:
+                withDependents:
+                  summary: Stack with dependent resources
+                  value:
+                    connections:
+                      - id: 673f806d0f9d0c860dcfab1e
+                        name: Wrapper Connection
+                        paths:
+                          - wrapper._stackId
+                        accessLevel: manage
+                        dependencyIds:
+                          stack:
+                            - 673e35899096693f4572c83c
+                    flows:
+                      - id: 673e486ac12b3453ea0ba99a
+                        name: Login flow
+                        paths:
+                          - pageGenerators[*]._exportId
+                        accessLevel: manage
+                        dependencyIds:
+                          export:
+                            - 673e486adc497ab5e649f1ca
+                empty:
+                  summary: No dependents
+                  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:
+    Stack:
+      type: object
+      description: Stack resource as returned by the API.
+      x-celigo-ai-guidance:
+        - |-
+          Response schema for stack operations: Contains the complete stack configuration.
+          Secrets (system token,
+          AWS secret access key) are masked as "******" in responses.
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: stacks
+          description: Unique identifier for the stack.
+          examples:
+            - 62100ec7abb76c310718b0f0
+        name:
+          type: string
+          maxLength: 1024
+          description: Human-readable display name for the stack.
+          examples:
+            - Production Server Stack
+        type:
+          type: string
+          enum:
+            - server
+            - lambda
+          x-enumDescriptions:
+            server: A self-hosted server that Celigo calls to execute custom code.
+            lambda: An AWS Lambda function that Celigo invokes to execute custom code.
+          description: Execution environment type that determines which configuration block is present.
+        framework:
+          type: string
+          enum:
+            - twoDotZero
+          x-enumDescriptions:
+            twoDotZero: Version 2.0 of the stack framework.
+          description: Framework version. Currently only `twoDotZero` is supported.
+        server:
+          type: object
+          description: |-
+            Configuration for server-type stacks. Present when `type` is `server`.
+            Legacy lambda-type stacks may also carry a vestigial empty `server`
+            object (`{"ipRanges": []}`).
+          x-celigo-ai-guidance:
+            - |-
+              Server stack configuration.
+              Only present when `type` is "server" and `hostURI` is set.
+          required:
+            - hostURI
+            - systemToken
+          properties:
+            hostURI:
+              type: string
+              maxLength: 1024
+              description: Base URI of the server hosting the stack.
+              examples:
+                - https://my-stack-server.example.com:3000
+            systemToken:
+              type: string
+              readOnly: true
+              description: |-
+                System token for authenticating with the server stack.
+                Always masked as "******" in standard responses. Use the
+                dedicated `/stacks/{_id}/systemToken` endpoint to retrieve
+                the actual value.
+              examples:
+                - '******'
+        lambda:
+          type: object
+          description: Configuration for AWS Lambda-type stacks. Present when `type` is `lambda`.
+          required:
+            - accessKeyId
+            - secretAccessKey
+            - awsRegion
+            - functionName
+          properties:
+            accessKeyId:
+              type: string
+              maxLength: 1024
+              description: |-
+                AWS access key ID for invoking the Lambda function. Unlike
+                `secretAccessKey`, it is returned in plaintext in responses.
+              examples:
+                - AKIAIOSFODNN7EXAMPLE
+            secretAccessKey:
+              type: string
+              maxLength: 511
+              description: AWS secret access key. Write-only — responses mask it as "******".
+              x-celigo-ai-guidance:
+                - AWS secret access key. Always masked as "******".
+              examples:
+                - '******'
+            awsRegion:
+              type: string
+              enum:
+                - us-east-1
+                - us-east-2
+                - us-west-1
+                - us-west-2
+                - ap-northeast-2
+                - ap-southeast-1
+                - ap-southeast-2
+                - ap-northeast-1
+                - ap-south-1
+                - eu-central-1
+                - eu-west-1
+              x-enumDescriptions:
+                us-east-1: US East (N. Virginia).
+                us-east-2: US East (Ohio).
+                us-west-1: US West (N. California).
+                us-west-2: US West (Oregon).
+                ap-northeast-2: Asia Pacific (Seoul).
+                ap-southeast-1: Asia Pacific (Singapore).
+                ap-southeast-2: Asia Pacific (Sydney).
+                ap-northeast-1: Asia Pacific (Tokyo).
+                ap-south-1: Asia Pacific (Mumbai).
+                eu-central-1: Europe (Frankfurt).
+                eu-west-1: Europe (Ireland).
+              description: AWS region where the Lambda function is deployed.
+              examples:
+                - us-east-1
+            functionName:
+              type: string
+              maxLength: 1024
+              description: Name or ARN of the AWS Lambda function.
+              examples:
+                - my-integration-function
+            language:
+              type: string
+              enum:
+                - Node.js
+                - C#
+                - Java
+                - Other
+              x-enumDescriptions:
+                Node.js: Lambda function written in Node.js (JavaScript/TypeScript).
+                C#: Lambda function written in C# (.NET).
+                Java: Lambda function written in Java.
+                Other: Lambda function written in another programming language.
+              default: Node.js
+              description: Programming language of the Lambda function.
+              examples:
+                - Node.js
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the stack was created.
+          examples:
+            - '2022-02-18T21:25:27.864Z'
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the stack was last modified.
+          examples:
+            - '2022-02-18T21:25:27.903Z'
+      required:
+        - _id
+        - name
+        - type
+        - createdAt
+        - lastModified
+      if:
+        properties:
+          type:
+            const: server
+      then:
+        required:
+          - server
+      else:
+        required:
+          - lambda
+    Error:
+      type: object
+      description: Standard error response envelope returned by integrator.io APIs.
+      properties:
+        errors:
+          type: array
+          description: List of errors that occurred while processing the request.
+          items:
+            type: object
+            properties:
+              code:
+                oneOf:
+                  - type: string
+                  - type: integer
+                description: |-
+                  Machine-readable error code. Usually a string like
+                  `invalid_ref`, `missing_required_field`, or `unauthorized`;
+                  may be an **integer** when the error mirrors an upstream HTTP
+                  status (e.g. `500`) — most commonly returned by connection-ping
+                  and adaptor-proxy responses.
+              message:
+                type: string
+                description: Human-readable description of the error.
+              field:
+                type: string
+                description: |-
+                  Optional pointer to the document field that caused the error.
+                  Used by structural validation errors (`missing_required_field`,
+                  `invalid_ref`) to indicate which field is at fault
+                  (e.g. `_id`, `type`, `http.baseURI`).
+              source:
+                type: string
+                description: |-
+                  Optional origin layer for the error — e.g. `application` when
+                  the error came from the remote system the adaptor called,
+                  `connector` when the adaptor itself rejected the request.
+            required:
+              - message
+      required:
+        - errors
+    Request:
+      type: object
+      description: Request body for creating or updating a stack.
+      x-celigo-ai-guidance:
+        - |-
+          Stacks provide execution environments for custom scripts, hooks, and wrappers
+          in integrator.io. Two types are supported:
+
+          - **server**: A self-hosted server stack with a system token for authentication
+          - **lambda**: An AWS Lambda function stack with AWS credentials
+      required:
+        - name
+        - type
+      properties:
+        name:
+          type: string
+          maxLength: 1024
+          description: Human-readable display name for the stack.
+          x-celigo-ai-guidance:
+            - Name the stack after the server or function deployment and its environment (e.g. "Production Hooks Server", "Hooks Lambda (us-east-1)"), not after one flow or use case — a stack hosts custom code shared by many scripts and flows.
+          examples:
+            - Production Server Stack
+            - Hooks Lambda (us-east-1)
+        type:
+          type: string
+          enum:
+            - server
+            - lambda
+          x-enumDescriptions:
+            server: Celigo calls a self-hosted server over HTTP to execute custom code; uses a system token for authentication
+            lambda: Celigo invokes an AWS Lambda function directly via the AWS SDK to execute custom code
+          description: Execution environment type.
+          examples:
+            - server
+            - lambda
+        framework:
+          type: string
+          enum:
+            - twoDotZero
+          x-enumDescriptions:
+            twoDotZero: Version 2.0 of the stack framework.
+          description: |-
+            Framework version. Currently only `twoDotZero` is supported.
+            Optional — if omitted on create, the field is absent from the
+            response. If omitted on PUT, a previously set value is cleared.
+          examples:
+            - twoDotZero
+        server:
+          type: object
+          description: |-
+            Configuration for server-type stacks. Required when `type` is `server`.
+            Omit when `type` is `lambda` — a `server` object sent on a lambda-type
+            write is accepted but discarded.
+          x-celigo-ai-guidance:
+            - |-
+              Required when `type` is "server".
+              The system token is auto-generated on creation and cannot be set directly.
+          required:
+            - hostURI
+          properties:
+            hostURI:
+              type: string
+              maxLength: 1024
+              description: Base URI of the server hosting the stack.
+              x-celigo-ai-guidance:
+                - Must be a valid, reachable HTTP(S) endpoint.
+              examples:
+                - https://my-stack-server.example.com:3000
+        lambda:
+          type: object
+          description: Configuration for AWS Lambda-type stacks. Required when `type` is `lambda`.
+          required:
+            - accessKeyId
+            - secretAccessKey
+            - awsRegion
+            - functionName
+          properties:
+            accessKeyId:
+              type: string
+              maxLength: 1024
+              description: AWS access key ID for invoking the Lambda function.
+              examples:
+                - AKIAIOSFODNN7EXAMPLE
+            secretAccessKey:
+              type: string
+              maxLength: 511
+              description: AWS secret access key. Write-only — responses mask it as "******".
+              examples:
+                - wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+            awsRegion:
+              type: string
+              enum:
+                - us-east-1
+                - us-east-2
+                - us-west-1
+                - us-west-2
+                - ap-northeast-2
+                - ap-southeast-1
+                - ap-southeast-2
+                - ap-northeast-1
+                - ap-south-1
+                - eu-central-1
+                - eu-west-1
+              x-enumDescriptions:
+                us-east-1: US East (N. Virginia).
+                us-east-2: US East (Ohio).
+                us-west-1: US West (N. California).
+                us-west-2: US West (Oregon).
+                ap-northeast-2: Asia Pacific (Seoul).
+                ap-southeast-1: Asia Pacific (Singapore).
+                ap-southeast-2: Asia Pacific (Sydney).
+                ap-northeast-1: Asia Pacific (Tokyo).
+                ap-south-1: Asia Pacific (Mumbai).
+                eu-central-1: Europe (Frankfurt).
+                eu-west-1: Europe (Ireland).
+              description: AWS region where the Lambda function is deployed.
+              examples:
+                - us-east-1
+            functionName:
+              type: string
+              maxLength: 1024
+              description: Name or ARN of the AWS Lambda function.
+              examples:
+                - my-integration-function
+                - arn:aws:lambda:us-east-1:123456789012:function:my-function
+            language:
+              type: string
+              enum:
+                - Node.js
+                - C#
+                - Java
+                - Other
+              x-enumDescriptions:
+                Node.js: Lambda function written in Node.js (JavaScript/TypeScript).
+                C#: Lambda function written in C# (.NET).
+                Java: Lambda function written in Java.
+                Other: Lambda function written in another programming language.
+              default: Node.js
+              description: Programming language of the Lambda function.
+              examples:
+                - Node.js
+      if:
+        properties:
+          type:
+            const: server
+      then:
+        required:
+          - server
+      else:
+        required:
+          - lambda
+    SystemTokenResponse:
+      type: object
+      description: Response containing the actual system token value for a server stack.
+      x-celigo-ai-guidance:
+        - |-
+          This endpoint returns the unmasked token,
+          unlike the standard stack response which always masks it as "******".
+      properties:
+        systemToken:
+          type: string
+          description: The actual system token value for authenticating with the server stack.
+          examples:
+            - a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
+    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
+    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.
+    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.
+    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-internal: false
+x-enable-proxy: true