@celigo/api-specs 0.2.1

package/dist/agent.yml

@@ -0,0 +1,908 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: On-premise Agents
+  description: API for managing Celigo on-premise agents — locally installed programs that tunnel firewall-protected systems to integrator.io.
+  x-celigo-ai-guidance:
+    - |-
+      API for managing on-premise agents in Celigo.
+      On-premise agents are software programs that run on your server and establish a
+      secure tunnel for connecting to 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: On-premise Agents
+    description: |-
+      On-premise agents are software programs installed on a local server that
+      establish a secure tunnel back to integrator.io. Connections configured
+      with an `_agentId` route traffic through the agent, enabling integrations
+      with databases and applications behind a firewall without opening
+      inbound ports.
+
+      ## Agent schema
+
+      {% openapi-schemas spec="agent" schemas="Agent" grouped="true" %}
+paths:
+  /v1/agents:
+    get:
+      x-internal: false
+      summary: List on-premise agents
+      description: |-
+        Returns all on-premise agents configured in the account. Check `offline`
+        to determine agent health — `true` means the platform has not received a
+        heartbeat recently.
+      operationId: listAgents
+      tags:
+        - On-premise Agents
+      parameters:
+        - $ref: '#/components/parameters/Include'
+        - $ref: '#/components/parameters/Exclude'
+        - name: limit
+          in: query
+          required: false
+          description: Maximum number of agents to return per page.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            default: 1000
+            examples:
+              - 100
+        - name: sort_by
+          in: query
+          required: false
+          description: Field to sort the agent list by (for example `name`).
+          schema:
+            type: string
+            examples:
+              - name
+        - name: after
+          in: query
+          required: false
+          description: |-
+            Opaque pagination cursor from a previous page's `Link` header;
+            returns results after that position. Invalid cursor values return
+            400 `invalid_query_param`.
+          schema:
+            type: string
+        - name: before
+          in: query
+          required: false
+          description: |-
+            Opaque pagination cursor from a previous page's `Link` header;
+            returns results before that position. Invalid cursor values return
+            400 `invalid_query_param`.
+          schema:
+            type: string
+        - name: permissions
+          in: query
+          required: false
+          description: |-
+            When true, each returned agent additionally carries `_accessLevel` —
+            the calling user's effective access to that agent.
+          schema:
+            type: boolean
+            examples:
+              - true
+      responses:
+        '200':
+          description: Array of agent objects.
+          x-celigo-ai-guidance:
+            - Successfully retrieved list of agents
+          headers:
+            Link:
+              description: |-
+                RFC 5988 pagination links. Includes `<...>; rel="next"` when more
+                pages remain; absent on the final page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Agent'
+              examples:
+                default:
+                  value:
+                    - _id: 62e1387939dc306a3806eab5
+                      name: Production DB Server
+                      createdAt: '2024-01-15T10:30:00.000Z'
+                      lastModified: '2026-04-23T01:52:12.086Z'
+                      offline: false
+                      version: 5.3.0
+                      _agentExtensionId: 68fb235610b42b2eaa6525c2
+                      port: '7020'
+                      lastHeartbeatAt: '2026-05-15T12:00:00.000Z'
+                    - _id: 5ecd2c3ce1ec9c4fcaf60b10
+                      name: Staging Server
+                      createdAt: '2023-06-01T08:00:00.000Z'
+                      lastModified: '2026-03-10T14:22:33.000Z'
+                      offline: true
+        '204':
+          description: No agents exist in the account.
+        '400':
+          description: Invalid pagination cursor in `after` or `before`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_cursor:
+                  value:
+                    errors:
+                      - code: invalid_query_param
+                        message: Please provide a valid cursor(i.e after or before query param) to encode or decode.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+    post:
+      x-internal: false
+      summary: Create an on-premise agent
+      description: |-
+        Creates a new on-premise agent. Only `name` is required. The response
+        includes the agent record but not the access token — call
+        `GET /v1/agents/{_id}/display-token` to retrieve the token needed for
+        the agent installer.
+      operationId: createAgent
+      tags:
+        - On-premise Agents
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              minimal:
+                summary: Minimal agent
+                value:
+                  name: Production DB Server
+              with-description:
+                summary: Agent with description
+                value:
+                  name: Staging Server
+                  description: Runs on staging-db-01, accesses PostgreSQL and Redis.
+      responses:
+        '201':
+          description: Created agent.
+          x-celigo-ai-guidance:
+            - agent created successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Agent'
+              examples:
+                created:
+                  summary: Newly created agent (server sets offline to true)
+                  value:
+                    _id: 62e1387939dc306a3806eab5
+                    name: Production DB Server
+                    createdAt: '2024-01-15T10:30:00.000Z'
+                    lastModified: '2024-01-15T10:30:00.000Z'
+                    offline: true
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          description: |-
+            Validation failed. A missing, empty, or non-string `name` returns
+            `required_field_missing` (the server maps a non-string `name` to
+            "missing"). A `name` longer than 100 characters, or a `description`
+            longer than 5120, returns `size_limit_exceeded`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                missing_name:
+                  value:
+                    errors:
+                      - code: required_field_missing
+                        message: 'required field: name is missing'
+                name_too_long:
+                  value:
+                    errors:
+                      - field: name
+                        code: size_limit_exceeded
+                        message: 'The maximum size of the field: name in the Agent document should be 100 characters.'
+  /v1/agents/{_id}:
+    get:
+      x-internal: false
+      summary: Get an on-premise agent
+      operationId: getAgent
+      tags:
+        - On-premise Agents
+      description: Returns a single on-premise agent.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Agent resource ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: agents
+      responses:
+        '200':
+          description: Agent object.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Agent'
+              examples:
+                connected:
+                  summary: Connected agent
+                  value:
+                    _id: 62e1387939dc306a3806eab5
+                    name: Production DB Server
+                    description: Runs on prod-db-01, accesses PostgreSQL.
+                    createdAt: '2024-01-15T10:30:00.000Z'
+                    lastModified: '2026-04-23T01:52:12.086Z'
+                    offline: false
+                    version: 5.3.0
+                    _agentExtensionId: 68fb235610b42b2eaa6525c2
+                    port: '7020'
+                    lastHeartbeatAt: '2026-05-15T12:00:00.000Z'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    put:
+      x-internal: false
+      summary: Update an on-premise agent
+      operationId: updateAgent
+      tags:
+        - On-premise Agents
+      description: |-
+        Replaces an on-premise agent's mutable fields. Only `name` and
+        `description` are mutable — system-managed fields (`version`, `offline`,
+        `port`, etc.) are ignored on PUT.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Agent resource ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: agents
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              update-description:
+                summary: Update the agent description
+                value:
+                  name: Production DB Server
+                  description: Runs on prod-db-01, accesses PostgreSQL and Redis.
+      responses:
+        '200':
+          description: Updated agent.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Agent'
+              examples:
+                updated:
+                  summary: Agent with updated description
+                  value:
+                    _id: 62e1387939dc306a3806eab5
+                    name: Production DB Server
+                    description: Runs on prod-db-01, accesses PostgreSQL and Redis.
+                    createdAt: '2024-01-15T10:30:00.000Z'
+                    lastModified: '2026-04-23T01:52:12.086Z'
+                    offline: false
+                    version: 5.3.0
+                    _agentExtensionId: 68fb235610b42b2eaa6525c2
+                    port: '7020'
+                    lastHeartbeatAt: '2026-05-15T12:00:00.000Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    delete:
+      x-internal: false
+      summary: Delete an on-premise agent
+      operationId: deleteAgent
+      tags:
+        - On-premise Agents
+      description: |-
+        Deletes an on-premise agent. Soft-deleted and retained in the recycle bin
+        for 30 days. Does not uninstall the agent software on the host.
+        Connections using this agent's `_agentId` will block deletion with 422
+        — check dependencies first.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Agent resource ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: agents
+      responses:
+        '204':
+          description: Agent deleted.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-dependency-conflict'
+  /v1/agents/{_id}/display-token:
+    get:
+      x-internal: false
+      summary: Display on-premise agent access token
+      description: |-
+        Returns the current unmasked access token for an agent. The agent process
+        needs this token to authenticate its tunnel back to integrator.io. The
+        access token is not included in normal GET/PUT responses — this is the
+        only way to retrieve it.
+      operationId: displayAgentToken
+      tags:
+        - On-premise Agents
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Agent resource ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: agents
+      responses:
+        '200':
+          description: Access token.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AccessTokenResponse'
+              examples:
+                default:
+                  value:
+                    accessToken: 894a7c82655d47b4940444f540e8f7b7
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/agents/{_id}/change-token:
+    put:
+      x-internal: false
+      summary: Rotate on-premise agent access token
+      description: |-
+        Regenerates the access token and returns the new value. The previous
+        token is immediately invalidated — the running agent process will
+        disconnect, so update the agent's configuration with the new token
+        before it attempts to reconnect. This is irreversible.
+      operationId: changeAgentToken
+      tags:
+        - On-premise Agents
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Agent resource ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: agents
+      responses:
+        '200':
+          description: New access token.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AccessTokenResponse'
+              examples:
+                rotated:
+                  summary: Newly generated access token (previous token invalidated)
+                  value:
+                    accessToken: e21ccad765da4378bf296007c17b96a8
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/agents/{_id}/installer/signedURL:
+    get:
+      x-internal: false
+      summary: Get on-premise agent installer download URL
+      description: |
+        Returns a short-lived presigned S3 URL for downloading the on-premise
+        agent installer binary. The URL is pre-signed for roughly 15 minutes.
+
+        The `os` query parameter selects which installer to return:
+        - `linux` → `agent-linux.run`
+        - `windows` → `agent-windows.exe`
+      operationId: getAgentInstallerUrl
+      tags:
+        - On-premise Agents
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: agents
+          description: On-premise agent id.
+        - name: os
+          in: query
+          required: true
+          schema:
+            type: string
+            enum:
+              - linux
+              - windows
+            x-enumDescriptions:
+              linux: Download the Linux installer binary.
+              windows: Download the Windows installer executable.
+          description: Operating system to download the installer for.
+      responses:
+        '200':
+          description: Presigned installer download URL.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/InstallerSignedUrlResponse'
+              examples:
+                linux:
+                  summary: Linux installer URL (os=linux)
+                  value:
+                    signedURL: https://integrator-agents.s3.us-east-1.amazonaws.com/agent-linux.run?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&...
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/agents/{_id}/dependencies:
+    get:
+      x-internal: false
+      operationId: listAgentDependencies
+      tags:
+        - On-premise Agents
+      summary: List dependencies of an agent
+      description: |-
+        Returns resources that depend on this agent. Keys are resource types
+        (e.g. `connections`); values are arrays of dependency entries.
+
+        Check dependencies before deleting — the DELETE endpoint is blocked if
+        dependents exist. Returns `{}` for both zero-dependency and nonexistent IDs.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Agent resource ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: agents
+      responses:
+        '200':
+          description: |
+            Dependency map. Keys are resource-type strings; values are arrays
+            of dependency entries. Returns `{}` when no dependents exist.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DependencyResponse'
+              examples:
+                none:
+                  summary: No dependents (also returned for a nonexistent ID)
+                  value: {}
+        '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:
+    AgentBase:
+      type: object
+      description: Fields for creating or updating an on-premise agent.
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 100
+          description: Display name identifying where the agent is installed and what it accesses.
+          x-celigo-ai-guidance:
+            - |-
+              Give your agent a name so that users in your integrator.io account know where it
+              is installed and what it has access to.
+          examples:
+            - Acme DC1 host — SQL Server + SFTP
+        description:
+          type: string
+          maxLength: 5120
+          description: Optional note about the agent's purpose or host environment.
+          x-celigo-ai-guidance:
+            - |-
+              Provide an optional description,
+              or any information you like that will help you keep track of this agent.
+              This information is displayed when viewing/editing an agent or in the Agent List page.
+          examples:
+            - Runs on prod-db-01, accesses PostgreSQL and Redis.
+    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
+    Agent:
+      type: object
+      required:
+        - _id
+        - name
+        - createdAt
+        - lastModified
+      description: On-premise agent object as returned by the API.
+      allOf:
+        - $ref: '#/components/schemas/AgentBase'
+        - $ref: '#/components/schemas/ResourceResponse'
+        - type: object
+          properties:
+            version:
+              type: string
+              readOnly: true
+              description: Agent software version running on the host.
+              examples:
+                - 5.3.0
+            _agentExtensionId:
+              type: string
+              format: objectId
+              readOnly: true
+              description: Reference to the agent extension installation metadata.
+              examples:
+                - 68fb235610b42b2eaa6525c2
+            port:
+              type: string
+              readOnly: true
+              description: Local port the agent uses for its tunnel listener.
+              examples:
+                - '7020'
+            lastHeartbeatAt:
+              type: string
+              format: date-time
+              readOnly: true
+              description: Timestamp of the most recent heartbeat from the agent.
+              examples:
+                - '2026-05-15T12:00:00.000Z'
+            offline:
+              type: boolean
+              readOnly: true
+              description: When true, the platform considers this agent offline based on heartbeat state.
+            _accessLevel:
+              type: string
+              readOnly: true
+              description: |-
+                The calling user's effective access level for this agent.
+                Present only when the list request sets `permissions=true`.
+              examples:
+                - manage
+    Error:
+      type: object
+      description: Standard error response envelope returned by integrator.io APIs.
+      properties:
+        errors:
+          type: array
+          description: List of errors that occurred while processing the request.
+          items:
+            type: object
+            properties:
+              code:
+                oneOf:
+                  - type: string
+                  - type: integer
+                description: |-
+                  Machine-readable error code. Usually a string like
+                  `invalid_ref`, `missing_required_field`, or `unauthorized`;
+                  may be an **integer** when the error mirrors an upstream HTTP
+                  status (e.g. `500`) — most commonly returned by connection-ping
+                  and adaptor-proxy responses.
+              message:
+                type: string
+                description: Human-readable description of the error.
+              field:
+                type: string
+                description: |-
+                  Optional pointer to the document field that caused the error.
+                  Used by structural validation errors (`missing_required_field`,
+                  `invalid_ref`) to indicate which field is at fault
+                  (e.g. `_id`, `type`, `http.baseURI`).
+              source:
+                type: string
+                description: |-
+                  Optional origin layer for the error — e.g. `application` when
+                  the error came from the remote system the adaptor called,
+                  `connector` when the adaptor itself rejected the request.
+            required:
+              - message
+      required:
+        - errors
+    Request:
+      type: object
+      description: Fields for creating or updating an on-premise agent.
+      x-celigo-ai-guidance:
+        - Fields that can be sent when creating or updating a agent
+      required:
+        - name
+      allOf:
+        - $ref: '#/components/schemas/AgentBase'
+    AccessTokenResponse:
+      type: object
+      description: |
+        Response containing the access token used by an on-premise agent to
+        authenticate its secure tunnel back to integrator.io.
+      properties:
+        accessToken:
+          type: string
+          description: The agent's current access token value.
+          examples:
+            - 894a7c82655d47b4940444f540e8f7b7
+          x-celigo-ai-guidance:
+            - Value is automatically generated in integrator.io, and needs to be set in the on-premise agent to establish a secure tunnel.
+    InstallerSignedUrlResponse:
+      type: object
+      description: |
+        Presigned S3 download URL for the on-premise agent installer binary
+        (Linux `.run` or Windows `.exe`). The URL is short-lived (~15 minutes).
+      properties:
+        signedURL:
+          type: string
+          format: uri
+          description: Presigned S3 URL the client should follow to download the installer.
+          examples:
+            - https://integrator-agents.s3.us-east-1.amazonaws.com/agent-linux.run?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&...
+    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.
+    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
+    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.
+x-enable-proxy: true
+x-internal: false