@celigo/api-specs 0.2.1

package/dist/apim.yml

@@ -0,0 +1,1286 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: APIM
+  description: API for managing Celigo API Management (APIM) — publishing integrator.io resources and configuring APIM account settings.
+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: APIM
+    description: |-
+      APIM management endpoints for publishing integrator.io APIs, exports, and
+      imports to the APIM platform, retrieving console
+      redirect URLs, and configuring APIM account settings.
+
+      Most routes require the `apim:operations` permission and an enabled APIM
+      license. Setup, validate, HRID validate, and resume routes are
+      production-environment only.
+
+      ## APIM schema
+
+      {% openapi-schemas spec="apim" schemas="ManageApiResponse" grouped="true" %}
+paths:
+  /v1/apim/redirect:
+    get:
+      x-internal: false
+      summary: Get APIM console redirect URL
+      description: Returns a signed URL that opens the APIM console home page for the account.
+      operationId: getApimRedirect
+      tags:
+        - APIM
+      responses:
+        '200':
+          description: Redirect URL.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RedirectUrl'
+              examples:
+                default:
+                  value:
+                    url: https://subdomain.apim.integrator.io/management/auth/external?token=eyJhbGciOiJSUzI1NiJ9...
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '500':
+          description: Failed to generate APIM console JWT token.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /v1/apim/redirect/analytics:
+    get:
+      x-internal: false
+      summary: Get APIM analytics redirect URL
+      description: |-
+        Returns a signed URL that opens the APIM analytics dashboard for the account.
+        Optionally scope the dashboard to a time range with `from` and `to`.
+      operationId: getApimRedirectAnalytics
+      tags:
+        - APIM
+      parameters:
+        - name: from
+          in: query
+          description: Start timestamp in milliseconds for the analytics window.
+          schema:
+            type: number
+            examples:
+              - 1763023108167
+        - name: to
+          in: query
+          description: End timestamp in milliseconds for the analytics window.
+          schema:
+            type: number
+            examples:
+              - 1763023408167
+      responses:
+        '200':
+          description: Redirect URL.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RedirectUrl'
+              examples:
+                default:
+                  value:
+                    url: https://subdomain.console.apim.integrator.io/#!/production/analytics/dashboard?from=1763023108167&to=1763023408167
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+  /v1/apim/{apiId}/{modelPlural}/{_id}/view:
+    get:
+      x-internal: false
+      summary: Get APIM resource view URL
+      description: Returns a signed URL that opens a published resource in the APIM console.
+      operationId: getApimResourceView
+      tags:
+        - APIM
+      parameters:
+        - name: apiId
+          in: path
+          description: APIM API identifier.
+          required: true
+          schema:
+            type: string
+            examples:
+              - 123e4567-e89b-12d3-a456-426614174000
+        - name: modelPlural
+          in: path
+          description: Integrator.io resource collection name.
+          required: true
+          schema:
+            type: string
+            enum:
+              - exports
+              - imports
+              - apis
+            x-enumDescriptions:
+              exports: Export resource published to APIM
+              imports: Import resource published to APIM
+              apis: Builder-mode API resource published to APIM
+            examples:
+              - exports
+        - name: _id
+          in: path
+          description: Integrator.io resource identifier.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 6756aceea7929d3f29126e6e
+      responses:
+        '200':
+          description: Redirect URL.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RedirectUrl'
+              examples:
+                default:
+                  value:
+                    url: https://subdomain.console.apim.integrator.io/#!/production/apis/6a6201f6-9142-4137-a201-f69142f137f8
+        '400':
+          description: Resource is not published to APIM.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/apim/apis:
+    get:
+      x-internal: false
+      summary: List APIM APIs
+      description: |-
+        Returns APIs published in the APIM platform for the account.
+        Results are paginated with `page` and `perPage`.
+      operationId: listApimApis
+      tags:
+        - APIM
+      parameters:
+        - name: page
+          in: query
+          description: Page number for APIM API search results.
+          schema:
+            type: integer
+            default: 1
+            examples:
+              - 1
+        - name: perPage
+          in: query
+          description: Number of APIs to return per page.
+          schema:
+            type: integer
+            default: 10
+            examples:
+              - 10
+      responses:
+        '200':
+          description: Paginated APIM API list.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApimApisListResponse'
+              examples:
+                default:
+                  value:
+                    apis:
+                      data:
+                        - id: 6a6201f6-9142-4137-a201-f69142f137f8
+                          name: my-export
+                          description: Customer data export API
+                          apiVersion: 1.0.0
+                          definitionVersion: V4
+                          state: STARTED
+                          deploymentState: DEPLOYED
+                          visibility: PUBLIC
+                          lifecycleState: PUBLISHED
+                          createdAt: '2026-04-24T16:52:05.607Z'
+                          updatedAt: '2026-05-07T15:22:16.985Z'
+                      pagination:
+                        page: 1
+                        perPage: 10
+                        pageCount: 1
+                        pageItemsCount: 1
+                        totalCount: 1
+                      links:
+                        self: https://subdomain.apim.integrator.io/apis/_search?page=1&perPage=10
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+  /v1/apim/{modelPlural}/{_id}/manageAPI:
+    post:
+      x-internal: false
+      summary: Publish resource to new APIM API
+      description: |-
+        Publishes an integrator.io resource to APIM as a new API.
+
+        Requires `apim:operations` permission and an enabled APIM license.
+        Custom webhooks (non-integrator-extension) are rejected with 400.
+        Upstream API management errors may be returned with the upstream HTTP status.
+      operationId: publishResourceToApim
+      tags:
+        - APIM
+      parameters:
+        - name: modelPlural
+          in: path
+          description: Integrator.io resource collection name.
+          required: true
+          schema:
+            type: string
+            enum:
+              - exports
+              - imports
+              - apis
+            x-enumDescriptions:
+              exports: Export resource published to APIM
+              imports: Import resource published to APIM
+              apis: Builder-mode API resource published to APIM
+            examples:
+              - exports
+        - name: _id
+          in: path
+          description: Integrator.io resource identifier.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 6756aceea7929d3f29126e6e
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ManageApiCreateRequest'
+            examples:
+              default:
+                value:
+                  contextPath: my-export
+                  flowName: my-flow
+                  method: POST
+                  definitionVersion: v4
+      responses:
+        '200':
+          description: Published APIM API.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ManageApiResponse'
+              examples:
+                default:
+                  value:
+                    id: 123e4567-e89b-12d3-a456-426614174000
+                    environmentId: 123e4567-e89b-12d3-a456-426614174001
+                    name: my-export
+                    version: 1.0.0
+                    context_path: /my-export
+                    state: STARTED
+                    visibility: PUBLIC
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    put:
+      x-internal: false
+      summary: Publish resource to existing APIM API
+      description: |-
+        Publishes an integrator.io resource to an existing APIM API.
+
+        Requires `apim:operations` permission and an enabled APIM license.
+        Upstream API management errors may be returned with the upstream HTTP status.
+      operationId: updateResourceInApim
+      tags:
+        - APIM
+      parameters:
+        - name: modelPlural
+          in: path
+          description: Integrator.io resource collection name.
+          required: true
+          schema:
+            type: string
+            enum:
+              - exports
+              - imports
+              - apis
+            x-enumDescriptions:
+              exports: Export resource published to APIM
+              imports: Import resource published to APIM
+              apis: Builder-mode API resource published to APIM
+            examples:
+              - exports
+        - name: _id
+          in: path
+          description: Integrator.io resource identifier.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 6756aceea7929d3f29126e6e
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ManageApiUpdateRequest'
+            examples:
+              default:
+                value:
+                  apiId: 123e4567-e89b-12d3-a456-426614174000
+                  flowName: my-flow
+                  method: POST
+      responses:
+        '200':
+          description: Updated APIM API.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ManageApiResponse'
+              examples:
+                default:
+                  value:
+                    id: 123e4567-e89b-12d3-a456-426614174000
+                    environmentId: 123e4567-e89b-12d3-a456-426614174001
+                    name: my-export
+                    version: 1.0.0
+                    context_path: /my-export
+                    state: STARTED
+                    visibility: PUBLIC
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/apim/{apiId}/{modelPlural}/{_id}/openAPIspec:
+    post:
+      x-internal: false
+      summary: Publish OpenAPI spec to APIM API
+      description: |-
+        Publishes an OpenAPI specification to an existing APIM API.
+
+        When a signed URL is not required for the resource type, the server
+        generates the OpenAPI document from the resource. The resource must
+        already be published to the given `apiId` (400 if not).
+
+        Upstream API management errors may be returned with the upstream HTTP status.
+      operationId: publishOpenApiSpecToApim
+      tags:
+        - APIM
+      parameters:
+        - name: apiId
+          in: path
+          description: APIM API identifier.
+          required: true
+          schema:
+            type: string
+            examples:
+              - 123e4567-e89b-12d3-a456-426614174000
+        - name: modelPlural
+          in: path
+          description: Integrator.io resource collection name.
+          required: true
+          schema:
+            type: string
+            enum:
+              - exports
+              - imports
+              - apis
+            x-enumDescriptions:
+              exports: Export resource published to APIM
+              imports: Import resource published to APIM
+              apis: Builder-mode API resource published to APIM
+            examples:
+              - exports
+        - name: _id
+          in: path
+          description: Integrator.io resource identifier.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 6756aceea7929d3f29126e6e
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/OpenApiSpecPublishRequest'
+            examples:
+              signedUrl:
+                summary: Publish from a signed S3 URL
+                value:
+                  signedUrl: https://s3.amazonaws.com/bucket/spec.yml?signature=...
+              autoGenerated:
+                summary: Auto-generated spec (no signed URL)
+                value: {}
+      responses:
+        '200':
+          description: Published OpenAPI document.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OpenApiSpecPublishResponse'
+              examples:
+                default:
+                  value:
+                    id: 123e4567-e89b-12d3-a456-426614174000
+                    name: openapi-spec
+                    type: SWAGGER
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/apim/setup:
+    post:
+      x-internal: false
+      summary: Set up APIM account
+      description: |-
+        Provisions APIM for the account with a subdomain and service account email.
+        Processing is asynchronous and returns `202 Accepted` with an empty body.
+
+        Production environment only. Requires `apim:operations` permission.
+      operationId: setupApim
+      tags:
+        - APIM
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ApimSetupRequest'
+            examples:
+              default:
+                value:
+                  subdomain: production-subdomain
+                  serviceAccountEmail: apim-service@example.com
+      responses:
+        '202':
+          $ref: '#/components/responses/202-accepted'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '409':
+          $ref: '#/components/responses/409-conflict'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    put:
+      x-internal: false
+      summary: Update APIM account settings
+      description: |-
+        Updates the service account email for an existing APIM account configuration.
+
+        Production environment only. Requires `apim:operations` permission.
+      operationId: updateApimSetup
+      tags:
+        - APIM
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ApimSetupUpdateRequest'
+            examples:
+              default:
+                value:
+                  serviceAccountEmail: apim-service@example.com
+      responses:
+        '200':
+          description: Updated service account email.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApimSetupUpdateResponse'
+              examples:
+                default:
+                  value:
+                    serviceAccountEmail: apim-service@example.com
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/apim/validate:
+    put:
+      x-internal: false
+      summary: Validate APIM subdomain
+      description: |-
+        Checks whether a subdomain is available for APIM account setup.
+
+        Production environment only.
+      operationId: validateApimSubdomain
+      tags:
+        - APIM
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - subdomain
+              properties:
+                subdomain:
+                  type: string
+                  description: Subdomain to validate.
+                  examples:
+                    - production-subdomain
+            examples:
+              default:
+                value:
+                  subdomain: production-subdomain
+      responses:
+        '200':
+          description: Subdomain is available.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ValidationResult'
+              examples:
+                default:
+                  value:
+                    valid: true
+        '400':
+          description: Invalid subdomain format.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApimValidationFailure'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '409':
+          description: Subdomain is not available.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApimValidationFailure'
+  /v1/apim/hrid/validate:
+    put:
+      x-internal: false
+      summary: Validate APIM environment HRID
+      description: |-
+        Checks whether an environment HRID is available for APIM configuration.
+
+        Production environment only.
+      operationId: validateApimEnvironmentHrid
+      tags:
+        - APIM
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - environmentHRID
+              properties:
+                environmentHRID:
+                  type: string
+                  description: Environment HRID to validate.
+                  examples:
+                    - production
+            examples:
+              default:
+                value:
+                  environmentHRID: production
+      responses:
+        '200':
+          description: Environment HRID is available.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ValidationResult'
+              examples:
+                default:
+                  value:
+                    valid: true
+        '400':
+          description: Invalid environment HRID format.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApimValidationFailure'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '409':
+          description: Environment HRID is not available.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApimValidationFailure'
+  /v1/apim/settings:
+    get:
+      x-internal: false
+      summary: Get APIM settings
+      description: Returns the APIM subdomain and service account email configured for the account.
+      operationId: getApimSettings
+      tags:
+        - APIM
+      responses:
+        '200':
+          description: APIM settings.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApimSettings'
+              examples:
+                default:
+                  value:
+                    subdomain: production-subdomain
+                    serviceAccountEmail: apim-service@example.com
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+  /v1/resumeAPIM:
+    put:
+      x-internal: false
+      summary: Resume APIM
+      description: |-
+        Resumes APIM for the account after it has been paused or suspended.
+
+        Production environment only. Requires `manage:license` permission (not
+        `apim:operations`). Returns `204` even when APIM is not yet provisioned
+        (no `orgId` on the user).
+      operationId: resumeApim
+      tags:
+        - APIM
+      responses:
+        '204':
+          description: APIM resumed successfully, or APIM was not provisioned.
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    RedirectUrl:
+      type: object
+      description: Signed redirect URL for the APIM console.
+      required:
+        - url
+      properties:
+        url:
+          type: string
+          description: Fully qualified URL to open in the APIM console.
+          examples:
+            - https://subdomain.console.apim.integrator.io/#!/production/home/overview
+    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
+    ApimApiSummary:
+      type: object
+      description: An API record returned by the APIM platform.
+      properties:
+        id:
+          type: string
+          description: APIM API identifier.
+          examples:
+            - 6a6201f6-9142-4137-a201-f69142f137f8
+        crossId:
+          type: string
+          description: Identifier that links the same API across environments.
+          examples:
+            - df83b2a4-cc3e-3f80-9f0d-c138c106c076
+        name:
+          type: string
+          description: API display name.
+          examples:
+            - my-export
+        description:
+          type: string
+          description: Short description of the API.
+          examples:
+            - Customer data export API
+        apiVersion:
+          type: string
+          description: API version label shown in the developer portal.
+          examples:
+            - 1.0.0
+        definitionVersion:
+          type: string
+          enum:
+            - V1
+            - V2
+            - V4
+            - FEDERATED
+          x-enumDescriptions:
+            V1: Legacy v1 API definition format
+            V2: v2 API definition format
+            V4: v4 API definition format
+            FEDERATED: Federated API definition
+          description: API definition format version.
+          examples:
+            - V4
+        state:
+          type: string
+          enum:
+            - CLOSED
+            - INITIALIZED
+            - STARTED
+            - STOPPED
+            - STOPPING
+          x-enumDescriptions:
+            CLOSED: API is closed
+            INITIALIZED: API is initialized but not started
+            STARTED: API is running on the gateway
+            STOPPED: API is stopped
+            STOPPING: API is stopping
+          description: Runtime state of the API on the gateway.
+          examples:
+            - STARTED
+        deploymentState:
+          type: string
+          enum:
+            - DEPLOYED
+            - NEED_REDEPLOY
+          x-enumDescriptions:
+            DEPLOYED: Latest changes are deployed
+            NEED_REDEPLOY: There are undeployed changes
+          description: Deployment state relative to the gateway.
+          examples:
+            - DEPLOYED
+        visibility:
+          type: string
+          enum:
+            - PUBLIC
+            - PRIVATE
+          x-enumDescriptions:
+            PUBLIC: Visible to all users
+            PRIVATE: Visible only to members
+          description: Visibility of the API in the developer portal.
+          examples:
+            - PUBLIC
+        lifecycleState:
+          type: string
+          enum:
+            - CREATED
+            - PUBLISHED
+            - UNPUBLISHED
+            - DEPRECATED
+            - ARCHIVED
+          x-enumDescriptions:
+            CREATED: Created but not published
+            PUBLISHED: Published to the portal
+            UNPUBLISHED: Removed from the portal
+            DEPRECATED: Marked as deprecated
+            ARCHIVED: Archived
+          description: Portal lifecycle state of the API.
+          examples:
+            - PUBLISHED
+        groups:
+          type: array
+          description: Group identifiers granting team access to the API.
+          items:
+            type: string
+        labels:
+          type: array
+          description: Free-form labels associated with the API.
+          items:
+            type: string
+        tags:
+          type: array
+          description: Sharding tags associated with the API.
+          items:
+            type: string
+        deployedAt:
+          type: string
+          format: date-time
+          description: Timestamp when the API was last deployed.
+        createdAt:
+          type: string
+          format: date-time
+          description: Timestamp when the API was created.
+        updatedAt:
+          type: string
+          format: date-time
+          description: Timestamp when the API was last updated.
+      additionalProperties: true
+    ApimApisPagination:
+      type: object
+      description: Pagination metadata for an APIM API search result.
+      properties:
+        page:
+          type: integer
+          description: The current page number.
+          examples:
+            - 1
+        perPage:
+          type: integer
+          description: The number of items requested per page.
+          examples:
+            - 10
+        pageCount:
+          type: integer
+          description: The total number of pages.
+          examples:
+            - 1
+        pageItemsCount:
+          type: integer
+          description: The number of items on the current page.
+          examples:
+            - 1
+        totalCount:
+          type: integer
+          format: int64
+          description: The total number of matching APIs.
+          examples:
+            - 1
+    ApimApisLinks:
+      type: object
+      description: Pagination links for an APIM API search result.
+      properties:
+        self:
+          type: string
+          description: Link to the current page.
+        first:
+          type: string
+          description: Link to the first page.
+        last:
+          type: string
+          description: Link to the last page.
+        previous:
+          type: string
+          description: Link to the previous page; absent on the first page.
+        next:
+          type: string
+          description: Link to the next page; absent on the last page.
+    ApimApisListResponse:
+      type: object
+      description: Paginated list of APIs published in the APIM platform.
+      properties:
+        apis:
+          type: object
+          description: APIM API search result.
+          properties:
+            data:
+              type: array
+              description: APIM API records for the current page.
+              items:
+                $ref: '#/components/schemas/ApimApiSummary'
+            pagination:
+              $ref: '#/components/schemas/ApimApisPagination'
+            links:
+              $ref: '#/components/schemas/ApimApisLinks'
+    ManageApiUpdateRequest:
+      type: object
+      description: Payload for publishing an integrator.io resource to an existing APIM API.
+      required:
+        - apiId
+        - flowName
+      properties:
+        apiId:
+          type: string
+          description: APIM API identifier to publish the resource into.
+          examples:
+            - 123e4567-e89b-12d3-a456-426614174000
+        flowName:
+          type: string
+          description: Flow name to associate with the published API.
+          examples:
+            - my-flow
+        method:
+          type: string
+          description: HTTP method exposed by the published API endpoint.
+          examples:
+            - POST
+    ManageApiResponse:
+      type: object
+      description: API object returned after publishing a resource to APIM.
+      properties:
+        id:
+          type: string
+          description: APIM API identifier.
+          examples:
+            - 123e4567-e89b-12d3-a456-426614174000
+        environmentId:
+          type: string
+          description: APIM environment identifier.
+          examples:
+            - 123e4567-e89b-12d3-a456-426614174001
+        name:
+          type: string
+          description: API display name in APIM.
+          examples:
+            - my-export
+        version:
+          type: string
+          description: API version string.
+          examples:
+            - 1.0.0
+        description:
+          type: string
+          description: API description in APIM.
+        context_path:
+          type: string
+          description: Published context path.
+          examples:
+            - /my-export
+        state:
+          type: string
+          description: Runtime state of the API in APIM.
+          examples:
+            - STARTED
+        visibility:
+          type: string
+          description: API visibility in APIM.
+          examples:
+            - PUBLIC
+      additionalProperties: true
+    ManageApiCreateRequest:
+      type: object
+      description: Payload for publishing an integrator.io resource to APIM as a new API.
+      required:
+        - contextPath
+        - flowName
+      properties:
+        contextPath:
+          type: string
+          description: Context path for the new APIM API (without leading slash).
+          examples:
+            - my-export
+        flowName:
+          type: string
+          description: Flow name to associate with the published API.
+          examples:
+            - my-flow
+        method:
+          type: string
+          description: HTTP method exposed by the published API endpoint. Defaults to POST.
+          examples:
+            - POST
+        definitionVersion:
+          type: string
+          enum:
+            - v2
+            - v4
+          x-enumDescriptions:
+            v2: Legacy v2 API definition format
+            v4: Version 4 API definition format
+          description: API definition version; omit for legacy v2 behavior.
+          examples:
+            - v4
+    OpenApiSpecPublishRequest:
+      type: object
+      description: Payload for publishing an OpenAPI specification to an APIM API.
+      properties:
+        signedUrl:
+          type: string
+          description: Signed S3 URL containing the OpenAPI specification to publish.
+          examples:
+            - https://s3.amazonaws.com/bucket/spec.yml?signature=...
+      x-celigo-ai-guidance:
+        - |-
+          `signedUrl` is required only when the resource type needs a signed S3 URL:
+          integrator-extension webhooks, imports, untyped exports, and builder-mode APIs.
+          For other resources, omit `signedUrl` — the server generates the OpenAPI document
+          from the resource. Requiredness depends on path `modelPlural` and the resource
+          document shape, not the request body alone.
+    OpenApiSpecPublishResponse:
+      type: object
+      description: APIM document record created after publishing an OpenAPI specification.
+      properties:
+        id:
+          type: string
+          description: APIM document identifier.
+          examples:
+            - 123e4567-e89b-12d3-a456-426614174000
+        name:
+          type: string
+          description: Document name in APIM.
+          examples:
+            - openapi-spec
+        type:
+          type: string
+          description: Document type in APIM.
+          examples:
+            - SWAGGER
+        content:
+          type: string
+          description: OpenAPI specification content uploaded to APIM.
+      additionalProperties: true
+    ApimSetupUpdateRequest:
+      type: object
+      description: Update payload for an existing APIM account configuration.
+      required:
+        - serviceAccountEmail
+      properties:
+        serviceAccountEmail:
+          type: string
+          format: email
+          description: Updated service account email for APIM management operations.
+          examples:
+            - apim-service@example.com
+    ApimSetupUpdateResponse:
+      type: object
+      description: Response after updating APIM service account email.
+      required:
+        - serviceAccountEmail
+      properties:
+        serviceAccountEmail:
+          type: string
+          format: email
+          description: Updated service account email for APIM management operations.
+          examples:
+            - apim-service@example.com
+    ApimSetupRequest:
+      type: object
+      description: Initial APIM account setup payload.
+      required:
+        - subdomain
+        - serviceAccountEmail
+      properties:
+        subdomain:
+          type: string
+          description: Requested APIM subdomain for the account.
+          examples:
+            - production-subdomain
+        serviceAccountEmail:
+          type: string
+          format: email
+          description: Service account email for APIM management operations.
+          examples:
+            - apim-service@example.com
+    ValidationResult:
+      type: object
+      description: Result of an APIM subdomain or environment HRID availability check.
+      required:
+        - valid
+      properties:
+        valid:
+          type: boolean
+          description: When true, the submitted value is available for use.
+    ApimValidationFailure:
+      type: object
+      description: Validation failure for APIM subdomain or environment HRID checks.
+      required:
+        - valid
+        - errors
+      properties:
+        valid:
+          type: boolean
+          enum:
+            - false
+          description: Always false when validation failed.
+        errors:
+          type: array
+          description: Validation errors.
+          items:
+            type: object
+            properties:
+              code:
+                type: string
+                description: Machine-readable error code.
+              message:
+                type: string
+                description: Human-readable error message.
+            required:
+              - message
+    ApimSettings:
+      type: object
+      description: APIM account configuration for the current user.
+      properties:
+        subdomain:
+          type: string
+          description: APIM subdomain assigned to the account.
+          examples:
+            - production-subdomain
+        serviceAccountEmail:
+          type: string
+          format: email
+          description: Service account email used for APIM management operations.
+          examples:
+            - apim-service@example.com
+  responses:
+    401-unauthorized:
+      description: |-
+        Unauthorized. The request lacks a valid bearer token, or the provided token
+        failed to authenticate.
+
+        Note: the 401 response is produced by the auth middleware **before** the
+        request reaches the endpoint handler, so it does **not** follow the
+        standard `{errors: [...]}` envelope. Instead the body is a bare
+        `{message: string}` object with no `code`, no `errors` array. Callers
+        handling 401s should key off the HTTP status and the `message` string,
+        not try to destructure an `errors[]`.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                description: |-
+                  Human-readable description of the auth failure. Known values:
+                  - `"Unauthorized"` — no `Authorization` header on the request.
+                  - `"Bearer Authentication Failed"` — header present but token
+                    is invalid, revoked, or expired.
+            required:
+              - message
+          examples:
+            missing_token:
+              summary: No Authorization header sent
+              value:
+                message: Unauthorized
+            invalid_token:
+              summary: Bearer token invalid or revoked
+              value:
+                message: Bearer Authentication Failed
+    403-forbidden:
+      description: |
+        Forbidden. The authenticated caller does not have permission to perform this operation.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: forbidden
+                    message: You do not have permission to access this resource.
+    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-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.
+    202-accepted:
+      description: Request accepted for asynchronous processing. Response has no body.
+    409-conflict:
+      description: Conflict — the submitted value is already in use.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: apim_subdomain_unavailable
+                    message: The requested subdomain is not available.
+x-enable-proxy: true
+x-internal: false