openapi: 3.0.3

info:
  title: Decodable Control Plane
  description: Decodable Control Plane API specification.
  version: v1alpha2

servers:
  - url: https://{account}.api.decodable.co/{version}
    description: Production API server for all operations in context of an account.
    variables:
      account:
        description: Decodable account name. Required.
        default: "replace-with-account"
      version:
        description: The API version. Required.
        default: v1alpha2

  - url: http://{account}.localhost{port}/{version}
    description: Local testing and development API server.
    variables:
      account:
        description: Decodable account name. Required.
        default: "replace-with-account"
      version:
        description: The API version. Required.
        default: v1alpha2
      port:
        description: |
          An optional port.

          This is strictly for testing. When used, a colon must be prepended.
        default: ""

  - url: https://prod.cell.decodable.co/{version}
    description: Production API server for non-account operations.
    variables:
      version:
        description: The API version. Required.
        default: v1alpha2

tags:
  - name: Declarative Operations
  - name: Pipeline Operations
  - name: Connection Operations
  - name: Stream Operations
  - name: Account Operations
  - name: Cell Operations
  - name: Preview Operations
  - name: Data Plane Tokens
  - name: "Access Management: User Operations"
  - name: "Access Management: Group Operations"
  - name: "Access Management: Role Operations"

security:
  - bearerAuth: [ ]

paths:

  # Declarative APIs

  /apply:

    post:
      operationId: DeclarativeApply
      summary: Apply (create/update) a series of resources
      description: |
        See: [`apply` command docs](https://docs.decodable.co/declarative/apply.html) for usage details.
        
        Requires appropriate permissions matching resources involved.
      tags:
        - Declarative Operations
      requestBody:
        $ref: "#/components/requestBodies/DeclarativeApplyRequest"
      responses:
        200:
          $ref: "#/components/responses/DeclarativeApplyResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        409:
          $ref: "#/components/responses/ErrorResourceExistsResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2: []

  /query:

    post:
      operationId: DeclarativeQuery
      summary: Query existing resources
      description: |
        See: [`query` command docs](https://docs.decodable.co/declarative/query.html) for usage details.
        
        Requires appropriate permissions matching resources involved.

        See [`query` options reference](https://docs.decodable.co/declarative/query.html#options) for more details on each field in request body YAML object (query specifier).
      tags:
        - Declarative Operations
      requestBody:
        $ref: "#/components/requestBodies/DeclarativeQueryRequest"
      responses:
        200:
          $ref: "#/components/responses/DeclarativeQueryResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        409:
          $ref: "#/components/responses/ErrorResourceExistsResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2: []

  # Pipeline APIs

  /pipelines:
    get:
      summary: Get a list of pipelines.
      description: |
        Result only includes resources for which the requesting user has permission matching:
        `pipeline:read:default.<name>`.
      operationId: ListPipelines
      tags:
        - Pipeline Operations
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
        - $ref: "#/components/parameters/ResourceView"
      responses:
        200:
          $ref: "#/components/responses/ListPipelinesResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - read:pipeline

    post:
      operationId: CreatePipeline
      summary: Create a pipeline.
      description: |
        Requires permissions matching: 
        - `pipeline:write:default.<name>`
        - `stream:read-data:default.<stream-name>` on input streams
        - `stream:write-data:default.<stream-name>` on output streams
      tags:
        - Pipeline Operations
      requestBody:
        $ref: "#/components/requestBodies/CreatePipelineRequest"
      responses:
        201:
          $ref: "#/components/responses/CreatePipelineResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        409:
          $ref: "#/components/responses/ErrorResourceExistsResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - write:pipeline

  /pipelines/outputStream:
    post:
      operationId: GetPipelineOutputStream
      summary: Get the output stream given a pipeline sql.
      description: |
        Requires permission matching: `stream:read:default.<name>`, but only for real (not inferred) stream.
      tags:
        - Pipeline Operations
      parameters:
        - $ref: "#/components/parameters/ResponseSchemaV"
      requestBody:
        $ref: "#/components/requestBodies/PipelineOutputStreamRequest"
      responses:
        200:
          $ref: "#/components/responses/GetStreamResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - read:pipeline

  /pipelines/{id}:
    parameters:
      - $ref: "#/components/parameters/ResourceId"

    get:
      operationId: GetPipeline
      parameters:
        - $ref: "#/components/parameters/ResourceView"
        - $ref: "#/components/parameters/ResourceVersion"
      summary: Get pipeline information by id.
      description: |
        Requires permission matching: `pipeline:read:default.<name>`.
      tags:
        - Pipeline Operations
      responses:
        200:
          $ref: "#/components/responses/GetPipelineResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - read:pipeline

    patch:
      operationId: UpdatePipeline
      summary: Update an existing pipeline by id.
      description: |
        Requires permissions matching: 
        - `pipeline:write:default.<name>` for both old and new `name`
        - `stream:read-data:default.<stream-name>` on input streams
        - `stream:write-data:default.<stream-name>` on output streams
      tags:
        - Pipeline Operations
      requestBody:
        $ref: "#/components/requestBodies/UpdatePipelineRequest"
      responses:
        200:
          $ref: "#/components/responses/UpdatePipelineResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        409:
          $ref: "#/components/responses/ErrorResourceConflictResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - write:pipeline

    delete:
      operationId: DeletePipeline
      summary: Delete an existing pipeline by id.
      description: |
        Requires permission matching: `pipeline:write:default.<name>`.
      tags:
        - Pipeline Operations
      responses:
        200:
          description: Pipeline successfully deleted.
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        409:
          $ref: "#/components/responses/ErrorResourceConflictResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - write:pipeline

  /pipelines/{id}/metrics/token:
    parameters:
      - $ref: "#/components/parameters/ResourceId"
    post:
      operationId: GetPipelineMetricsToken
      summary: Create a JWT token to get pipeline metrics in the data plane
      description: Retrieve a token for pipeline metrics in the data plane
      tags:
        - Data Plane Tokens
      responses:
        200:
          $ref: "#/components/responses/DataPlaneRequestAndToken"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  /pipelines/{id}/flink-ui/token:
    parameters:
      - $ref: "#/components/parameters/ResourceId"
    post:
      operationId: GetPipelineFlinkUiToken
      summary: Create a JWT token to authorize Flink Web Dashboard requests in the data plane
      description: |
        Requires permission matching: `pipeline:read:default.<name>`.
      tags:
        - Data Plane Tokens
      responses:
        200:
          $ref: "#/components/responses/DataPlaneRequestAndToken"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  /pipelines/{id}/activate:
    post:
      operationId: ActivatePipeline
      parameters:
        - $ref: "#/components/parameters/ResourceId"
        - $ref: "#/components/parameters/ResourceVersion"
        - $ref: "#/components/parameters/ForceFlag"
        - $ref: "#/components/parameters/ActivationTasks"
      summary: Activate a pipeline by id.
      description: |
        Requires permission matching: `pipeline:activate:default.<name>`.
      tags:
        - Pipeline Operations
      requestBody:
        $ref: "#/components/requestBodies/ActivatePipelineRequest"
      responses:
        200:
          $ref: "#/components/responses/ActivationDeactivationResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        409:
          $ref: "#/components/responses/ErrorResourceConflictResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - activate:pipeline

  /pipelines/{id}/deactivate:
    parameters:
      - $ref: "#/components/parameters/ResourceId"
      - $ref: "#/components/parameters/ResourceVersion"
      - $ref: "#/components/parameters/DeprecatedForceFlag"
    post:
      operationId: DeactivatePipeline
      summary: Deactivate a pipeline by id.
      description: |
        Requires permission matching: `pipeline:activate:default.<name>`.
      tags:
        - Pipeline Operations
      responses:
        200:
          $ref: "#/components/responses/ActivationDeactivationResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        409:
          $ref: "#/components/responses/ErrorResourceConflictResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - activate:pipeline

  /pipelines/{id}/streams:
    parameters:
      - $ref: "#/components/parameters/ResourceId"
    get:
      operationId: GetPipelineStreams
      summary: Get streams linked to a pipeline.
      description: |
        Requires permission matching: `pipeline:read:default.<name>`.

        Deprecated: please prefer `/pipelines/{id}/dependencies` instead.
      tags:
        - Pipeline Operations
      responses:
        200:
          $ref: "#/components/responses/PipelineStreamsResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - read:pipeline

  /pipelines/{id}/dependencies:
    parameters:
      - $ref: "#/components/parameters/ResourceId"
      - $ref: "#/components/parameters/ResourceVersion"
    get:
      operationId: GetPipelineDependencies
      summary: Get dependencies linked to a pipeline.
      description: |
        Requires permission matching: `pipeline:read:default.<name>`.
      tags:
        - Pipeline Operations
      responses:
        200:
          $ref: "#/components/responses/DependencyResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - read:pipeline

  /pipelines/custom:
    post:
      operationId: CreateCustomPipeline
      summary: Create a pipeline using a custom job file.
      description: |
        Requires permission matching: `pipeline:write:default.<name>`.
        Account must be eligible for custom jobs.
      tags:
        - Pipeline Operations
      requestBody:
        $ref: "#/components/requestBodies/CreateCustomPipelineRequest"

      responses:
        201:
          $ref: "#/components/responses/CreatePipelineResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        409:
          $ref: "#/components/responses/ErrorResourceExistsResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - write:pipeline

  /pipelines/custom/{id}:
    parameters:
      - $ref: "#/components/parameters/ResourceId"

    patch:
      operationId: UpdateCustomPipeline
      summary: Update a pipeline using a custom job file.
      description: |
        Requires permission matching: `pipeline:write:default.<name>`.
        Account must be eligible for custom jobs.
      tags:
        - Pipeline Operations
      requestBody:
        $ref: "#/components/requestBodies/UpdateCustomPipelineRequest"
      responses:
        200:
          $ref: "#/components/responses/UpdatePipelineResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        409:
          $ref: "#/components/responses/ErrorResourceConflictResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - write:pipeline

  /pipelines/custom/flink-versions:
    get:
      operationId: GetCustomPipelineFlinkVersions
      summary: Get a list of supported Flink versions for custom pipelines.
      tags:
        - Pipeline Operations
      responses:
        200:
          $ref: "#/components/responses/CustomPipelineFlinkVersionsResponse"
        401:
          $ref: "#/components/responses/ErrorUnauthenticatedResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  /pipelines/{id}/snapshots:
    parameters:
      - $ref: "#/components/parameters/ResourceId"
    get:
      operationId: ListPipelineSnapshots
      summary: Get a list of snapshots for a pipeline by pipeline id
      tags:
        - Pipeline Operations
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        200:
          $ref: "#/components/responses/SnapshotsResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - read:pipeline
    post:
      operationId: CreatePipelineSnapshot
      summary: Create a one-time snapshot for a pipeline by pipeline id
      tags:
        - Pipeline Operations
      responses:
        201:
          $ref: "#/components/responses/SnapshotResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      requestBody:
        $ref: "#/components/requestBodies/SnapshotRequest"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - write:pipeline

  /pipelines/{id}/snapshot/{snapshot_id}:
    parameters:
      - $ref: "#/components/parameters/ResourceId"
      - $ref: "#/components/parameters/SnapshotId"
    get:
      operationId: GetPipelineSnapshot
      summary: Get a snapshot for a pipeline by pipeline id and snapshot id
      tags:
        - Pipeline Operations
      responses:
        200:
          $ref: "#/components/responses/SnapshotResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - read:pipeline

    delete:
      operationId: DeletePipelineSnapshot
      summary: Delete a snapshot for a pipeline by pipeline id and snapshot id
      tags:
        - Pipeline Operations
      responses:
        204:
          description: Snapshot successfully deleted.
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - write:pipeline

  /pipelines/{id}/logs/token:
    parameters:
      - $ref: "#/components/parameters/ResourceId"
      - $ref: "#/components/parameters/TaskIndex"
      - $ref: "#/components/parameters/NumLines"
      - $ref: "#/components/parameters/Follow"
    post:
      operationId: GetPipelineLogsToken
      summary: Create a JWT token to get pipeline logs in the data plane
      description: Retrieve a token for pipeline logs in the data plane
      tags:
        - Data Plane Tokens
      responses:
        200:
          $ref: "#/components/responses/DataPlaneRequestAndToken"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  # Connection APIs

  /connections:
    get:
      operationId: ListConnections
      summary: Get a list of connections.
      description: |
        Result only includes resources for which the requesting user has permission matching:
        `connection:read:default.<name>`.
      tags:
        - Connection Operations
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
        - $ref: "#/components/parameters/ResourceView"
      responses:
        200:
          $ref: "#/components/responses/ListConnectionsResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - read:connection

    post:
      operationId: CreateConnection
      summary: Create a connection.
      description: |
        Requires permissions matching: 
        - `connection:write:default.<name>`
        - `stream:read-data:default.<stream-name>` on attached streams for sink connections
        - `stream:write-data:default.<stream-name>` on attached streams for source connections
      tags:
        - Connection Operations
      parameters:
        - name: stream_name
          description: If a stream_id is not specified in the body, a new stream will be created with this name. Otherwise a default name will be generated.
          in: query
          required: false
          schema:
            type: string
        - name: stream_description
          description: If a stream_id is not specified in the body, a new stream will be created with this description. Otherwise a default description will be generated.
          in: query
          required: false
          schema:
            type: string
        - name: enable_experimental
          description: Enable connections to be created using experimental connectors
          in: query
          required: false
          schema:
            type: boolean
        - $ref: "#/components/parameters/ResponseSchemaV"
      requestBody:
        $ref: "#/components/requestBodies/CreateConnectionRequest"
      responses:
        200:
          description: Connectivity was successfully established but the connection was not created.
        201:
          $ref: "#/components/responses/CreateConnectionResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        409:
          $ref: "#/components/responses/ErrorResourceExistsResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - write:connection

  /connections/{id}:
    parameters:
      - $ref: "#/components/parameters/ResourceId"

    get:
      operationId: GetConnection
      parameters:
        - $ref: "#/components/parameters/ResourceView"
        - $ref: "#/components/parameters/ResponseSchemaV"
      summary: Get connection information by id.
      description: |
        Requires permission matching: `connection:read:default.<name>`.
        Response will only include `stream_mappings` when `?view=full`.
      tags:
        - Connection Operations
      responses:
        200:
          $ref: "#/components/responses/GetConnectionResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - read:connection

    patch:
      operationId: UpdateConnection
      summary: Update an existing connection by id.
      description: |
        Requires permissions matching: 
        - `connection:write:default.<name>` for both old and new `name`
        - `stream:read-data:default.<stream-name>` on attached streams for sink connections
        - `stream:write-data:default.<stream-name>` on attached streams for source connections
      tags:
        - Connection Operations
      parameters:
        - $ref: "#/components/parameters/ResponseSchemaV"
      requestBody:
        $ref: "#/components/requestBodies/UpdateConnectionRequest"
      responses:
        200:
          $ref: "#/components/responses/UpdateConnectionResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        409:
          $ref: "#/components/responses/ErrorResourceConflictResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - write:connection

    delete:
      operationId: DeleteConnection
      summary: Delete an existing connection by id.
      description: |
        Requires permission matching: `connection:write:default.<name>`.
      tags:
        - Connection Operations
      responses:
        200:
          description: Connection successfully deleted.
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        409:
          $ref: "#/components/responses/ErrorResourceConflictResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - write:connection

  /connections/{id}/activate:
    post:
      operationId: ActivateConnection
      parameters:
        - $ref: "#/components/parameters/ResourceId"
        - $ref: "#/components/parameters/ForceFlag"
        - $ref: "#/components/parameters/ActivationTasks"
        - $ref: "#/components/parameters/ResponseSchemaV"
      summary: Activate a connection by id.
      description: |
        Requires permission matching: `connection:activate:default.<name>`.
      tags:
        - Connection Operations
      requestBody:
        $ref: '#/components/requestBodies/ActivateConnectionRequest'
      responses:
        200:
          $ref: "#/components/responses/UpdateConnectionResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        409:
          $ref: "#/components/responses/ErrorResourceConflictResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - activate:connection

  /connections/{id}/deactivate:
    parameters:
      - $ref: "#/components/parameters/ResourceId"
      - $ref: "#/components/parameters/DeprecatedForceFlag"
      - $ref: "#/components/parameters/ResponseSchemaV"
    post:
      operationId: DeactivateConnection
      summary: Deactivate a connection by id.
      description: |
        Requires permission matching: `connection:activate:default.<name>`.
      tags:
        - Connection Operations
      responses:
        200:
          $ref: "#/components/responses/UpdateConnectionResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        409:
          $ref: "#/components/responses/ErrorResourceConflictResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - activate:connection

  /connections/{id}/events:
    post:
      operationId: PostEvents
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      summary: Send events to a REST connection.
      description: |
        Given a well-formatted payload, write given events to the output stream attached to this connection.
        Note that the `id` specified must correspond to a connection configured with the `rest` connector
        type, otherwise an HTTP 409 error will be returned.

        Requires permission matching: `stream:write:default.<name>`, where `name` is of this connection's output stream.
      tags:
        - Connection Operations
      requestBody:
        $ref: "#/components/requestBodies/PostConnectionEventsRequest"
      responses:
        202:
          $ref: "#/components/responses/PostConnectionEventsResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        409:
          $ref: "#/components/responses/ErrorResourceConflictResponse"
        429:
          $ref: "#/components/responses/ErrorTooManyRequestsResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - write:stream

  /connections/{id}/dependencies:
    parameters:
      - $ref: "#/components/parameters/ResourceId"
    get:
      operationId: GetConnectionDependencies
      summary: Get dependencies linked to a connection.
      description: |
        Requires permission matching: `connection:read:default.<name>`.
      tags:
        - Connection Operations
      responses:
        200:
          $ref: "#/components/responses/DependencyResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - read:connection

  /connections/{id}/connectivity-check/token:
    parameters:
      - $ref: "#/components/parameters/ResourceId"
    post:
      operationId: ExistingConnectivityCheck
      summary: Create a JWT token to perform a connectivity check for given connection in the data plane
      description: Perform a connectivity check on the connection with optional modifications in the request body.
      tags:
        - Data Plane Tokens
      requestBody:
        $ref: "#/components/requestBodies/OptionallyModifyConnectionRequest"
      responses:
        200:
          $ref: "#/components/responses/DataPlaneRequestAndToken"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  /connectivity-check/token:
    post:
      operationId: UncreatedConnectivityCheck
      summary: Create a JWT token to perform a connectivity check in the data plane
      description: Perform a one-off connectivity check.
      tags:
        - Data Plane Tokens
      requestBody:
        $ref: "#/components/requestBodies/CreateConnectionRequest"
      responses:
        200:
          $ref: "#/components/responses/DataPlaneRequestAndToken"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  /connections/{id}/metrics/token:
    parameters:
      - $ref: "#/components/parameters/ResourceId"
    post:
      operationId: GetConnectionMetricsToken
      summary: Create a JWT token to get connection metrics in the data plane
      description: Retrieve a token for connection metrics in the data plane
      tags:
        - Data Plane Tokens
      responses:
        200:
          $ref: "#/components/responses/DataPlaneRequestAndToken"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]


  # Stream APIs

  /streams:
    get:
      operationId: ListStreams
      summary: Get a list of streams.
      description: |
        Result only includes resources for which the requesting user has permission matching:
        `stream:read:default.<name>`.
      tags:
        - Stream Operations
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
        - $ref: "#/components/parameters/ResourceView"
        - $ref: "#/components/parameters/ResponseSchemaV"
        - name: name_inclusion_filter
          description: A POSIX regular expression pattern used to filter the fetched streams by name.
          in: query
          required: false
      responses:
        200:
          $ref: "#/components/responses/ListStreamsResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - read:stream

    post:
      operationId: CreateStream
      summary: Create a stream.
      description: |
        Requires permission matching: `stream:write:default.<name>`.
      tags:
        - Stream Operations
      requestBody:
        $ref: "#/components/requestBodies/CreateStreamRequest"
      parameters:
        - name: allow_equivalent
          description: |
            When `true`, if a Stream with the same name and an equivalent schema already exists,
            instead of creating a new Stream, return the existing Stream, with status code `200 OK`.
          in: query
          required: false
          schema:
            type: boolean
            default: false
        - name: allow_evolution
          description: |
            When `true`, if a Stream with the same name exists, add any new fields (fields in the 
            request schema but not the existing Stream schema) to the existing Stream, ignoring
            any other differences.
          in: query
          required: false
          schema:
            type: boolean
            default: false
        - $ref: "#/components/parameters/ResponseSchemaV"
      responses:
        200:
          $ref: "#/components/responses/CreateStreamResponse"
        201:
          $ref: "#/components/responses/CreateStreamResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        409:
          $ref: "#/components/responses/ErrorResourceExistsResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - write:stream

  /streams/{id}:
    parameters:
      - $ref: "#/components/parameters/ResourceId"

    get:
      operationId: GetStream
      parameters:
        - $ref: "#/components/parameters/ResourceView"
        - $ref: "#/components/parameters/SchemaType"
        - $ref: "#/components/parameters/ResponseSchemaV"
      summary: Get stream information by id.
      description: |
        Requires permission matching: `stream:read:default.<name>`.
      tags:
        - Stream Operations
      responses:
        200:
          $ref: "#/components/responses/GetStreamResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - read:stream

    patch:
      operationId: UpdateStream
      summary: Update an existing stream by id.
      description: |
        Requires permission matching: `stream:write:default.<name>`.
      tags:
        - Stream Operations
      parameters:
        - $ref: "#/components/parameters/ResponseSchemaV"
      requestBody:
        $ref: "#/components/requestBodies/UpdateStreamRequest"
      responses:
        200:
          $ref: "#/components/responses/UpdateStreamResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        409:
          $ref: "#/components/responses/ErrorResourceConflictResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - write:stream

    delete:
      operationId: DeleteStream
      summary: Delete an existing stream by id.
      description: |
        Requires permission matching: `stream:write:default.<name>`.
      tags:
        - Stream Operations
      responses:
        200:
          description: Stream successfully deleted.
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        409:
          $ref: "#/components/responses/ErrorResourceConflictResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - write:stream

  /streams/{id}/compatibility:
    parameters:
      - $ref: "#/components/parameters/ResourceId"
    post:
      operationId: CheckSchemaCompatibilityWithStream
      summary: Check if a given schema is compatible with a stream.
      description: |
        Requires permission matching: `stream:read:default.<name>`.
      tags:
        - Stream Operations
      requestBody:
        $ref: "#/components/requestBodies/StreamCompatibilityRequest"
      responses:
        200:
          $ref: "#/components/responses/StreamCompatibilityResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - write:preview

  /streams/{id}/dependencies:
    parameters:
      - $ref: "#/components/parameters/ResourceId"
    get:
      operationId: GetStreamDependencies
      summary: Get dependencies linked to a stream.
      description: |
        Requires permission matching: `stream:read:default.<name>`.
      tags:
        - Stream Operations
      responses:
        200:
          $ref: "#/components/responses/DependencyResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - read:stream

  /streams/{id}/preview/token:
    parameters:
      - $ref: "#/components/parameters/ResourceId"
    post:
      operationId: CreateStreamPreviewToken
      summary: Create a JWT token to preview the data on the stream using the data plane API.
      description: |
        Requires permission matching: `preview:write:default.<name>`.
      tags:
        - Data Plane Tokens
      responses:
        200:
          $ref: "#/components/responses/DataPlaneRequestAndToken"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  /streams/{id}/clear/token:
    parameters:
      - $ref: "#/components/parameters/ResourceId"
    post:
      operationId: CreateStreamClearToken
      summary: Create a JWT token to clear the data on the stream using the data plane API.
      description: |
        Requires permission matching: `preview:write:default.<name>`.
      tags:
        - Data Plane Tokens
      responses:
        200:
          $ref: "#/components/responses/DataPlaneRequestAndToken"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  # Secret APIs

  /secrets:
    get:
      operationId: ListSecrets
      summary: Get a list of secrets.
      description: |
        Result only includes resources for which the requesting user has permission matching:
        `secret:read:default.<name>`.
      tags:
        - Secret Operations
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        200:
          $ref: "#/components/responses/ListSecretsResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

    post:
      operationId: CreateSecret
      summary: Create a secret.
      description: |
        Requires permission matching: `secret:write:default.<name>`.
      tags:
        - Secret Operations
      requestBody:
        $ref: "#/components/requestBodies/CreateSecretRequest"
      responses:
        201:
          $ref: "#/components/responses/CreateSecretResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        409:
          $ref: "#/components/responses/ErrorResourceExistsResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  /secrets/{id}:
    parameters:
      - $ref: "#/components/parameters/ResourceId"

    get:
      operationId: GetSecret
      summary: Get secret information by id.
      description: |
        Requires permission matching: `secret:read:default.<name>`.
      tags:
        - Secret Operations
      responses:
        200:
          $ref: "#/components/responses/GetSecretResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

    patch:
      operationId: UpdateSecret
      summary: Update an existing secret by id.
      description: |
        Requires permission matching: `secret:write:default.<name>`.
      tags:
        - Secret Operations
      requestBody:
        $ref: "#/components/requestBodies/UpdateSecretRequest"
      responses:
        200:
          $ref: "#/components/responses/UpdateSecretResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        409:
          $ref: "#/components/responses/ErrorResourceConflictResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

    delete:
      operationId: DeleteSecret
      summary: Delete an existing secret by id.
      description: |
        Requires permission matching: `secret:write:default.<name>`.
      tags:
        - Secret Operations
      responses:
        204:
          description: Secret successfully deleted.
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  /secrets/{id}/plaintext/token:
    parameters:
      - $ref: "#/components/parameters/ResourceId"

    post:
      operationId: GetWriteSecretPlaintextToken
      summary: Get a token to write secret plaintext to the data plane API.
      description: |
        Requires permission matching: `secret:write:default.<name>`.
      tags:
        - Data Plane Tokens
      responses:
        200:
          $ref: "#/components/responses/DataPlaneRequestAndToken"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        409:
          $ref: "#/components/responses/ErrorResourceExistsResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  # File APIs

  /files/{sha}:
    parameters:
      - name: sha
        description: The sha512 hash of the file.
        in: path
        required: true
        schema:
          type: string

    get:
      operationId: GetFile
      parameters:
        - name: type
          description: The file type
          in: query
          required: true
          schema:
            type: string
            enum:
              - JOB_FILE
              - CONFIG_FILE
      summary: Get metadata for a file, identified by sha.
      description: |
        Requires permission matching: `file:read:default.<file-name>`.
      tags:
        - Files
      responses:
        200:
          $ref: "#/components/responses/GetFileResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
      security:
        - bearerAuth: [ ]

  /files/upload-token:
    post:
      operationId: GetFileUploadToken
      summary: Get a token to upload files to the data plane API.
      description: |
        Requires permission matching: `file:write:default.<file-name>`, for each name included in the request.
      tags:
        - Data Plane Tokens
      parameters:
        - name: token-validity-seconds
          description: Validity of the token in seconds. The upload to the data plane must be completed by the time the token expires. Defaults to 300 seconds.
          in: query
          required: false
          schema:
            type: number
            minimum: 1
            maximum: 900
      requestBody:
        $ref: "#/components/requestBodies/UploadFileRequest"
      responses:
        200:
          $ref: "#/components/responses/DataPlaneRequestAndToken"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
      security:
        - bearerAuth: [ ]

  # Account APIs

  /accounts:
    get:
      operationId: ListUserAccounts
      summary: Get a list of Decodable Accounts of which the authenticated user is a member.
      description: |
        Any authenticated user (or app client) has permission to list Accounts of which they are a Member.
      tags:
        - Account Operations
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
        - $ref: "#/components/parameters/ResourceView"
      responses:
        200:
          $ref: "#/components/responses/ListAccountsResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2: [ ]

    post:
      operationId: CreateAccount
      summary: Create a Decodable Account.
      description: |
        Any authenticated user (not app client) has permission to create an Account.
      tags:
        - Account Operations
      requestBody:
        $ref: "#/components/requestBodies/CreateAccountRequest"
      responses:
        201:
          $ref: "#/components/responses/CreateAccountResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        409:
          $ref: "#/components/responses/ErrorResourceExistsResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2: [ ]

  /accounts/metadata:
    get:
      operationId: GetAccountMetadata
      summary: Gets metadata for the account.
      description: |
        Requires permission matching: `account:read:<name>`, where `name` is the account name.
      tags:
        - Account Operations
      responses:
        200:
          $ref: "#/components/responses/AccountMetadataResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2: [ ]

  /accounts/{name}:
    parameters:
      - $ref: "#/components/parameters/AccountName"

    get:
      operationId: GetAccountInformation
      summary: Gets information for the account.
      description: |
        Requires permission matching: `account:read:<name>`, where `name` is the account name.
      tags:
        - Account Operations
      responses:
        200:
          $ref: "#/components/responses/AccountInfoResponse"
        401:
          $ref: "#/components/responses/ErrorUnauthenticatedResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2: [ ]

    patch:
      operationId: UpdateAccount
      summary: Update a Decodable Account.
      description: |
        Requires permission matching: `account:write:<name>`, where `name` is the account name.
      tags:
        - Account Operations
      requestBody:
        $ref: "#/components/requestBodies/UpdateAccountRequest"
      responses:
        201:
          $ref: "#/components/responses/CreateAccountResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        409:
          $ref: "#/components/responses/ErrorResourceExistsResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2: [ ]

  # Certificates APIs
  /accounts/{name}/certificate_signing_request:
    post:
      operationId: CreateCertificateSignRequest
      summary: Upload a Certificate Signing Request (CSR) for a BYOC deployment.
      description: |
        Requires permission matching: `account:write:<name>`, where `name` is the account name.
        
        Uploads a CSR to set up a BYOC deployment of Decodable. Contact [Decodable support](mailto:support@decodable.co) 
        if you would like to set up a BYOC deployment of Decodable. See [Managed Cloud vs BYOC docs](https://docs.decodable.co/administer/managed-cloud-vs-byoc.html) for deployment details.
      tags:
        - Account Operations
      requestBody:
        $ref: "#/components/requestBodies/PostCertificateSignRequest"
      responses:
        202:
          description: The file was accepted and is being processed.
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        401:
          $ref: "#/components/responses/ErrorUnauthenticatedResponse"
        409:
          $ref: "#/components/responses/ErrorResourceExistsResponse"
        415:
          $ref: "#/components/responses/ErrorUnsupportedMediaTypeResponse"
  /accounts/{name}/certificate:
    get:
      operationId: SignedCertificate
      summary: Fetch a Signed Certificate for a BYOC deployment.
      description: |
        Requires permission matching: `account:read:<name>`, where `name` is the account name.
        
        Fetches a signed certificate for a BYOC deployment of Decodable. Contact [Decodable support](mailto:support@decodable.co) 
        if you would like to set up a BYOC deployment of Decodable. See [Managed Cloud vs BYOC docs](https://docs.decodable.co/administer/managed-cloud-vs-byoc.html) for deployment details.
      tags:
        - Account Operations
      responses:
        200:
          $ref: "#/components/responses/GetSignedCertificateResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        401:
          $ref: "#/components/responses/ErrorUnauthenticatedResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"


  # Cell APIs

  /cells/available:
    get:
      operationId: GetCellsAvailable
      summary: Get new-account-available Cell IDs by Region by Cloud.
      description: |
        Any authenticated user (not app client) has permission to perform this operation.
      tags:
        - Cell Operations
      responses:
        200:
          $ref: "#/components/responses/GetCellsResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2: [ ]

  # Preview APIs

  /preview/dependencies:
    post:
      operationId: GetPreviewDependencies
      summary: Get dependencies for preview sql.
      description: |
        Requires permission matching: `preview:write:default.<name>`, where `name` is that of _each_ stream referenced as input in the given `sql`.
      requestBody:
        $ref: "#/components/requestBodies/PreviewDependencyRequest"
      tags:
        - Preview Operations
      responses:
        200:
          $ref: "#/components/responses/DependencyResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]
        - oauth2:
            - write:preview

  /preview/tokens:
    post:
      operationId: CreatePreviewTokens
      summary: Create JWT tokens to start and fetch a preview using the data plane API.
      description: |
        Requires permission matching: `preview:write:default.<name>`, where `name` is that of _each_ stream referenced as input in the given `sql`.
      tags:
        - Data Plane Tokens
      requestBody:
        $ref: "#/components/requestBodies/PreviewTokensRequest"
      responses:
        200:
          $ref: "#/components/responses/DataPlaneSqlPreviewRequestAndTokens"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  /schema/compile:
    post:
      operationId: CompileSchema
      summary: Compile a schema.
      description: |
        Any authenticated user has permission to perform this operation.
      tags:
        - Schema Operations
      requestBody:
        $ref: "#/components/requestBodies/SchemaRequest"
      responses:
        201:
          $ref: "#/components/responses/SchemaResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  /tasks/sizes:
    get:
      operationId: GetTasks
      summary: Get available task sizes.
      description: |
        Any authenticated user has permission to perform this operation.
      tags:
        - Tasks Operations
      responses:
        200:
          $ref: "#/components/responses/TaskSizesResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  # Access management: User APIs

  /access/users:
    get:
      operationId: ListUsers
      summary: Get a list of users.
      description: |
        Result only includes resources for which the requesting user has permission matching:
        `user:read:<id>`.
      tags:
        - "Access Management: User Operations"
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        200:
          $ref: "#/components/responses/ListUsersResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  /access/users/{user_id}:
    parameters:
      - $ref: "#/components/parameters/UserId"

    get:
      operationId: GetUser
      summary: Get user information by id.
      description: |
        Requires permission matching: `user:read:<id>`.
      tags:
        - "Access Management: User Operations"
      responses:
        200:
          $ref: "#/components/responses/GetUserResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  /access/users/{user_id}/groups:
    parameters:
      - $ref: "#/components/parameters/UserId"

    get:
      operationId: ListUserAssociatedGroups
      summary: Get a list of groups associated with user.
      description: |
        Requires permission matching: `user:read:<id>`.

        Result only includes resources for which the requesting user has permission matching:
        `group:read:<name>`, where `name` is the group name.
      tags:
        - "Access Management: User Operations"
        - "Access Management: Group Operations"
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        200:
          $ref: "#/components/responses/ListGroupsResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  # Access management: Group APIs

  /access/groups:
    get:
      operationId: ListGroups
      summary: Get a list of groups.
      description: |
        Result only includes resources for which the requesting user has permission matching:
        `group:read:<name>`.
      tags:
        - "Access Management: Group Operations"
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        200:
          $ref: "#/components/responses/ListGroupsResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

    post:
      operationId: PostGroup
      summary: Write a group.
      description: |
        Create new if no id; modify existing with a given id.

        Requires permission matching: `group:write:<name>`.
      tags:
        - "Access Management: Group Operations"
      requestBody:
        $ref: "#/components/requestBodies/PostGroupRequest"
      responses:
        200:
          $ref: "#/components/responses/PostGroupResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        409:
          $ref: "#/components/responses/ErrorResourceExistsResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  /access/groups/{group_id}:
    parameters:
      - $ref: "#/components/parameters/GroupId"

    get:
      operationId: GetGroup
      summary: Get group information by id.
      description: |
        Requires permission matching: `group:read:<name>`.
      tags:
        - "Access Management: Group Operations"
      responses:
        200:
          $ref: "#/components/responses/GetGroupResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

    delete:
      operationId: DeleteGroup
      summary: Delete an existing group by id.
      description: |
        Requires permission matching: `group:write:<name>`.
      tags:
        - "Access Management: Group Operations"
      responses:
        204:
          description: Group was deleted.
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  /access/groups/{group_id}/users:
    parameters:
      - $ref: "#/components/parameters/GroupId"

    get:
      operationId: ListGroupAssociatedUsers
      summary: Get a list of users associated with group.
      description: |
        Requires permission matching: `group:read:<name>`.

        Result only includes resources for which the requesting user has permission matching:
        `user:read:<id>`, where `id` is the user ID.
      tags:
        - "Access Management: User Operations"
        - "Access Management: Group Operations"
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        200:
          $ref: "#/components/responses/ListUsersResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  /access/groups/{group_id}/users/{user_id}:
    parameters:
      - $ref: "#/components/parameters/GroupId"
      - $ref: "#/components/parameters/UserId"

    put:
      operationId: PutGroupUserAssociation
      summary: Add user to group.
      description: |
        Requires permissions matching: `group:write:<name>` and `user:read:<id>`.
      tags:
        - "Access Management: User Operations"
        - "Access Management: Group Operations"
      responses:
        204:
          description: User is now in group.
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

    delete:
      operationId: DeleteGroupUserAssociation
      summary: Remove user from group.
      description: |
        Requires permissions matching: `group:write:<name>` and `user:read:<id>`.
      tags:
        - "Access Management: User Operations"
        - "Access Management: Group Operations"
      responses:
        204:
          description: User is now not in group.
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  /access/groups/{group_id}/roles/{role_id}:
    parameters:
      - $ref: "#/components/parameters/GroupId"
      - $ref: "#/components/parameters/RoleId"

    put:
      operationId: PutGroupRoleAssociation
      summary: Add role to group.
      description: |
        Requires permissions matching: `group:write:<name>` and `role:read:<name>`.
      tags:
        - "Access Management: Group Operations"
        - "Access Management: Role Operations"
      responses:
        204:
          description: Role is now in group.
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

    delete:
      operationId: DeleteGroupRoleAssociation
      summary: Remove role from group.
      description: |
        Requires permissions matching: `group:write:<name>` and `role:read:<name>`.
      tags:
        - "Access Management: Group Operations"
        - "Access Management: Role Operations"
      responses:
        204:
          description: Role is now not in group.
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  /access/groups/{group_id}/roles:
    parameters:
      - $ref: "#/components/parameters/GroupId"

    get:
      operationId: ListGroupAssociatedRoles
      summary: Get a list of roles associated with group.
      description: |
        Requires permission matching: `group:read:<name>`.

        Result only includes resources for which the requesting user has permission matching:
        `role:read:<name>`, where `name` is the role name.
      tags:
        - "Access Management: Group Operations"
        - "Access Management: Role Operations"
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        200:
          $ref: "#/components/responses/ListRolesResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  # Access management: Role APIs

  /access/roles:
    get:
      operationId: ListRoles
      summary: Get a list of roles.
      description: |
        Result only includes resources for which the requesting user has permission matching:
        `role:read:<name>`
      tags:
        - "Access Management: Role Operations"
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        200:
          $ref: "#/components/responses/ListRolesResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

    post:
      operationId: PostRole
      summary: Write a role.
      description: |
        Create new if no id; modify existing with a given id.

        Requires permission matching: `role:write:<name>`.
      tags:
        - "Access Management: Role Operations"
      requestBody:
        $ref: "#/components/requestBodies/PostRoleRequest"
      responses:
        200:
          $ref: "#/components/responses/PostRoleResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        409:
          $ref: "#/components/responses/ErrorResourceExistsResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  /access/roles/{role_id}:
    parameters:
      - $ref: "#/components/parameters/RoleId"

    get:
      operationId: GetRole
      summary: Get role information by id.
      description: |
        Requires permission matching: `role:read:<name>`.
      tags:
        - "Access Management: Role Operations"
      responses:
        200:
          $ref: "#/components/responses/GetRoleResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

    delete:
      operationId: DeleteRole
      summary: Delete an existing role by id.
      description: |
        Requires permission matching: `role:write:<name>`.
      tags:
        - "Access Management: Role Operations"
      responses:
        204:
          description: Role was deleted.
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  /access/roles/{role_id}/groups:
    parameters:
      - $ref: "#/components/parameters/RoleId"

    get:
      operationId: ListRoleAssociatedGroups
      summary: Get a list of groups associated with role.
      description: |
        Requires permission matching: `role:read:<name>`.

        Result only includes resources for which the requesting user has permission matching:
        `group:read:<name>`, where `name` is the group name.
      tags:
        - "Access Management: Group Operations"
        - "Access Management: Role Operations"
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        200:
          $ref: "#/components/responses/ListGroupsResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

  /access/roles/{role_id}/permissions:
    parameters:
      - $ref: "#/components/parameters/RoleId"

    get:
      operationId: GetRolePermissions
      summary: List role permissions by role id.
      description: |
        Requires permission matching: `role:read:<name>`.
      tags:
        - "Access Management: Role Operations"
      responses:
        200:
          $ref: "#/components/responses/ListRolePermissionsResponse"
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

    put:
      operationId: PutRolePermissions
      summary: Put role permissions by role id.
      description: |
        Requires permission matching: `role:write:<name>`.
      tags:
        - "Access Management: Role Operations"
      requestBody:
        $ref: "#/components/requestBodies/PutRolePermissionsRequest"
      responses:
        200:
          description: Role permissions successfully put.
        400:
          $ref: "#/components/responses/ErrorBadRequestResponse"
        403:
          $ref: "#/components/responses/ErrorForbiddenResponse"
        404:
          $ref: "#/components/responses/ErrorResourceDoesNotExistResponse"
        default:
          $ref: "#/components/responses/ErrorGenericResponse"
      security:
        - bearerAuth: [ ]

components:

  schemas:

    ResourceId:
      description: An opaque ID, created by Decodable, that uniquely identifies a resource.
      type: string
      example: abcd1234

    AccountName:
      description: The Decodable Account name, globally unique, hostname segment compliant.
      type: string
      minLength: 3
      maxLength: 50
      pattern: "[a-z][a-z0-9]*(-[a-z0-9]+)*"

    # NB: Resource view is the view=basic|full parameter, not a SQL view.
    ResourceView:
      description: |
        The amount of data to return for the resource(s).

        A value of `basic` returns the standard properties of the resource. It may also produce data that is
        considered "computationally cheap" to return. Specifying `basic` is the same as omitting this parameter.

        The behavior of `full` is service-dependent, but generally includes more fields. This can mean additional status
        or version data, or even expanding references to contained resources. This should be used when the cost of an
        additional API roundtrip is greater than the overhead of the request.
      type: string
      enum:
        - basic
        - full

    ResourceTimestamps:
      type: object
      properties:
        create_time:
          description: The date and time the resource was created.
          type: string
          format: date-time
        update_time:
          description: The date and time the resource was updated.
          type: string
          format: date-time

    ResourceVersionNumber:
      description: A version number of a resource
      type: integer
      example: 1

    ResourceIsLatestFlag:
      description: describe if a versioned resource is the latest version
      type: boolean

    ResourceVersionSelector:
      description: A version tag of a resource
      type: string
      enum: [ active, latest, all ]

    RecordSchema:
      description: Record schema.
      type: array
      items:
        type: object
        properties:
          name:
            description: The field name.
            type: string
          type:
            description: The field type.
            type: string

    PhysicalField:
      description: A physical field.
      type: object
      required:
        - kind
      properties:
        kind:
          type: string
          enum: [ physical ]
        name:
          type: string
        type:
          type: string

    ComputedField:
      description: A computed field.
      type: object
      required:
        - kind
      properties:
        kind:
          type: string
          enum: [ computed ]
        name:
          type: string
        expression:
          type: string

    MetadataField:
      description: A metadata field.
      type: object
      required:
        - kind
      properties:
        kind:
          type: string
          enum: [ metadata ]
        name:
          type: string
        type:
          type: string
        key:
          type: string

    SchemaV2:
      description: Record schema, version 2.
      type: object
      properties:
        fields:
          description: The fields in this schema.
          type: array
          items:
            oneOf:
              - $ref: "#/components/schemas/PhysicalField"
              - $ref: "#/components/schemas/ComputedField"
              - $ref: "#/components/schemas/MetadataField"
            discriminator:
              propertyName: kind
              mapping:
                physical: "#/components/schemas/PhysicalField"
                computed: "#/components/schemas/ComputedField"
                metadata: "#/components/schemas/MetadataField"
        watermarks:
          description: Watermark expressions for this stream. At this time only one expression is supported.
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              expression:
                type: string
        constraints:
          type: object
          properties:
            primary_key:
              description: Column names to use for primary key.
              type: array
              items:
                type: string

    ActualSystemFlinkConfiguration:
      description: This field is only present when the job is `RUNNING` and shows the current Flink configurations applied to the running job.
      type: object
      nullable: true
      additionalProperties:
        type: string
        nullable: true
      example:
        operator-chaining: "true"

    SystemFlinkConfiguration:
      description: The latest Flink configurations defined for this job. When this differs from `actual_system_flink_configuration`, restart the job to apply the latest configurations.
      type: object
      nullable: true
      additionalProperties:
        type: string
        nullable: true
      example:
        operator-chaining: "true"

    RuntimeError:
      description: The pipeline last runtime error.
      type: object
      properties:
        message:
          description: last runtime error message
          type: string
        raw_exception:
          description: raw exception from the underlying system
          type: string
        timestamp:
          description: last runtime error timestamp
          type: string
          format: date-time

    Error:
      description: |
        Information about an error that occurred.

        Note that most of the field values are not guaranteed to be stable and are not to be considered part of the
        API contract. In most cases, they are for informational purposes and to aid in reporting errors to Decodable.
      type: object
      required:
        - code
        - message
        - time
      properties:
        request_id:
          description: A unique request ID for support.
          type: string
        message:
          description: A human readable description of the error.
          type: string
        code:
          description: A code describing the exact source of the error.
          type: integer
        time:
          description: The time the error occurred, according to the service.
          type: string
          format: date-time
        details:
          description: Additional error-specific key/value pairs.
          type: object
          additionalProperties:
            type: string

    DeclarativeWithKind:
      type: object
      properties:
        kind:
          description: The resource `kind`.
          type: string
          enum:
            - secret
            - stream
            - connection
            - pipeline

    DeclarativeDefinition:
      description: The declarative resource definition format.
      type: object
      required:
        - kind
        - metadata
        - spec_version
      allOf:
        - $ref: "#/components/schemas/DeclarativeWithKind"
        - properties:
            metadata:
              description: Identifying and labeling information for the resource.
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                description:
                  type: string
                id:
                  type: string
                tags:
                  type: object
                  maxProperties: 20
                  additionalProperties:
                    type: string
                    maxLength: 255
            spec_version:
              description: The `spec` version for this resource definition.
              type: string
              enum:
                - v1
            spec:
              description: Resource configuration, per `kind` and `spec_version`.
              type: object
              oneOf:
                - $ref: "#/components/schemas/SecretV1Spec"
                - $ref: "#/components/schemas/StreamV1Spec"
                - $ref: "#/components/schemas/ConnectionV1Spec"
                - $ref: "#/components/schemas/SqlPipelineV1Spec"
                - $ref: "#/components/schemas/CustomPipelineV1Spec"

    DeclarativeDefinitionWithStatus:
      description: The declarative resource definition format.
      type: object
      required:
        - kind
        - metadata
        - spec_version
      allOf:
        - $ref: "#/components/schemas/DeclarativeDefinition"
        - properties:
            status:
              description: Resource status, per `kind` and `spec_version`.
              type: object
              oneOf:
                - $ref: "#/components/schemas/SecretV1Status"
                - $ref: "#/components/schemas/StreamV1Status"
                - $ref: "#/components/schemas/ConnectionV1Status"
                - $ref: "#/components/schemas/SqlPipelineV1Status"
                - $ref: "#/components/schemas/CustomPipelineV1Status"

    DeclarativeQuerySpecifier:
      description: |
        A declarative `query` specifier.
        See [`query` options reference](https://docs.decodable.co/declarative/query.html#options) for more details.
      type: object
      properties:
        operation:
          type: string
          enum: [ get, list, activate, deactivate, delete ]
          nullable: true
          description: |
            Query operation: one of:
            
            | operation             | description |
            | ---------             | ----------- |
            | `get` <br>(_default_) | Fetch all matched resources. <br>Include associated values in each resource: schema, properties, etc. |
            | `list`                | Fetch all matched resources. <br>Include only scalar values. This can be faster in some cases. |
            | `activate`            | Activate all matched resources. |
            | `deactivate`          | Deactivate all matched resources. |
            | `delete`              | Delete all matched resources. |
        kinds:
          type: array
          items:
            type: string
          nullable: true
          description: |
            Include in response only resources whose `kind` is one of these values.
        names:
          type: array
          items:
            type: string
          nullable: true
          description: |
            Include in response only resources whose `name` matches one of these values.

            Values for this option may include the `*` wildcard, which matches any string in a name. For example: `demo_*`.
        ids:
          type: array
          items:
            type: string
          nullable: true
          description: |
            Include in response only resources whose `id` is one of these values.
        resources:
          type: array
          items:
            type: object
            required:
              - kind
              - name
            properties:
              kind:
                type: string
              name:
                type: string
          nullable: true
          description: |
            Include in response only resources whose `kind` and `name` equal those in one of these values.
            Sort response resources to match.
        active:
          type: boolean
          nullable: true
          description: |
            When present, include in response: 
            - When `true`: only active resources.
            - When `false`: only not-active resources.
            - Only Connection and Pipeline resources.
        stable:
          type: boolean
          nullable: true
          description: |
            When present, include in response: 
            - When `true`: only stable resources.
            - When `false`: only not-stable resources.
            - Only Connection and Pipeline resources.
        no_status:
          type: boolean
          nullable: true
          description: |
            Return resources without `status` section, suitable for export for source control.
        no_spec:
          type: boolean
          nullable: true
          description: |
            Return resources without `spec` section.
        keep_ids:
          type: boolean
          nullable: true
          description: |
            Return resources with IDs in `metadata` and `spec` sections.
        include_immutables:
          type: boolean
          nullable: true
          description: |
            Include in the response built-in immutable resources, such as `_events` and `_metrics` Streams.

            *Important:* These resources can't be `apply`'d (or otherwise changed). _Not_ appropriate for export to source control or `apply`.
        spec_versions:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: |
            - key: `kind` value
            - value: `spec_version` value (per-`kind`)
            
            Select the `spec_version` for one or more `kind`s.
  
            Allows your custom tooling to choose the contract (object shape) for `spec` sections of resource definition YAML docs in the `query` response.
            Note that `spec` shapes won't be compatible across `spec_version`s, and `spec_version` is per-`kind`.
            
            The _default_ `spec_version` is the latest for each `kind`.
        tag_expression:
          type: string
          nullable: true
          description: |
            A SQL-like expression used to query resources by their tags. The expression filters resources based on tag key and value pairs.
            
            The expression format is `key=value`, where both the key and value are case-sensitive. Use logical operators like `AND`, `OR`, and parentheses for more complex queries.
            
            Tag queries require values to be enclosed in single quotes. For multi-part queries, double-quote the entire expression to avoid issues with process substitution.

    DeclarativeResult:
      description: A result object from a declarative `apply` or mutating `query` operation.
      type: object
      required:
        - kind
        - name
        - id
        - result
      allOf:
        - $ref: "#/components/schemas/DeclarativeWithKind"
        - properties:
            name:
              description: The resource name.
              type: string
            id:
              description: The resource ID.
              type: string
            result:
              type: string
              enum:
                - created
                - updated
                - unchanged
                - deleted
            dry_run:
              description: When `true`, this was a dry run, and no actual changes were made.
              type: boolean

    Pipeline:
      description: A pipeline.
      type: object
      required:
        - id
        - version
        - name
        - create_time
        - type
      allOf:
        - properties:
            id:
              $ref: "#/components/schemas/ResourceId"
            name:
              description: The pipeline name.
              type: string
            description:
              description: The pipeline description.
              type: string
            type:
              $ref: '#/components/schemas/PipelineType'
        - $ref: "#/components/schemas/SqlPipelineV1Spec"
        - $ref: "#/components/schemas/CustomPipelineV1Spec"
        - $ref: "#/components/schemas/PipelineV1CommonStatus"

    PipelineV1CommonStatus:
      type: object
      allOf:
        - properties:
            version:
              $ref: "#/components/schemas/ResourceVersionNumber"
            is_latest:
              $ref: "#/components/schemas/ResourceIsLatestFlag"
            active_version:
              description: The active version of the pipeline
              type: integer
              nullable: true
            latest_version:
              description: The latest version of the pipeline
              type: integer
            last_runtime_error:
              $ref: "#/components/schemas/RuntimeError"
        - $ref: "#/components/schemas/ObjectState"
        - $ref: "#/components/schemas/ResourceTimestamps"
        - $ref: "#/components/schemas/ObjectTasks"
        - $ref: "#/components/schemas/ActualSystemFlinkConfiguration"
        - $ref: "#/components/schemas/SystemFlinkConfiguration"

    SqlPipelineV1Status:
      type: object
      title: "pipeline @ v1 (sql)"
      allOf:
        - properties:
            type:
              $ref: '#/components/schemas/SqlPipelineType'
        - $ref: "#/components/schemas/PipelineV1CommonStatus"

    CustomPipelineV1Status:
      type: object
      title: "pipeline @ v1 (custom)"
      allOf:
        - $ref: "#/components/schemas/PipelineV1CommonStatus"

    PipelineType:
      description: The type of the pipeline. Consumers should be able to gracefully handle new values in future API versions.
      type: string
      enum: [ JAVA, PYTHON, SQL ]

    SqlPipelineType:
      description: The type of the SQL pipeline.
      type: string
      enum: [ SQL ]

    CustomPipelineType:
      description: The type of the custom pipeline. Consumers should be able to gracefully handle new values in future API versions.
      type: string
      enum: [ JAVA, PYTHON ]

    SqlPipelineCommon:
      description: Common pipeline fields in requests and responses.
      type: object
      allOf:
        - properties:
            name:
              description: The pipeline name.
              type: string
            description:
              description: The pipeline description.
              type: string
        - $ref: '#/components/schemas/SqlPipelineV1Spec'

    SqlPipelineV1Spec:
      type: object
      title: "pipeline @ v1 (sql)"
      description: |
        `kind: pipeline`, `spec_version: v1`. SQL pipeline fields only.
      properties:
        sql:
          description: The pipeline SQL.
          type: string
          example: |
            INSERT INTO stream_out
            SELECT ...
            FROM stream_in
        snapshot_configuration:
          $ref: '#/components/schemas/SnapshotConfiguration'
        autoscale_configuration:
          $ref: '#/components/schemas/AutoscaleConfiguration'
        properties:
          $ref: '#/components/schemas/SQLPipelineProperties'

    CustomPipelineRequestCommon:
      description: Common pipeline fields in requests and responses.
      type: object
      allOf:
        - properties:
            name:
              description: The pipeline name.
              type: string
            description:
              description: The pipeline description.
              type: string
        - $ref: '#/components/schemas/CustomPipelineV1Spec'

    CustomPipelineV1Spec:
      type: object
      title: "pipeline @ v1 (custom)"
      description: |
        `kind: pipeline`, `spec_version: v1`. Custom pipeline fields only.
      properties:
        type:
          $ref: '#/components/schemas/CustomPipelineType'
        job_file_sha:
          description: |
            SHA512 hash of the job file. Must reference a file that was previously uploaded using the `/files` endpoints.
          type: string
        job_arguments:
          description: |
            Argument string input to the custom pipeline program.
          type: string
        entry_class:
          description: |
            Name of the entry class to run for this custom Java-based pipeline (optional). 
            If not present, the class to run must be specified in the file `META-INF/MANIFEST.MF` 
            within the job's JAR file, using the `Main-Class` property key.
          type: string
        properties:
          $ref: "#/components/schemas/CustomPipelineProperties"
        snapshot_configuration:
          $ref: '#/components/schemas/SnapshotConfiguration'

    SQLPipelineProperties:
      type: object
      properties:
        secrets:
          type: array
          items:
            description: Decodable secret ids to make available to the SQL pipeline.
            type: string

    CustomPipelineProperties:
      type: object
      properties:
        secrets:
          type: array
          items:
            description: Decodable secret id's to make available to the custom pipeline.
            type: string
        flink_version:
          type: string
          description: The Flink version to run this custom pipeline on.
        additional_metrics:
          type: array
          items:
            description: |
              Additional Flink metrics to expose in the `_metrics` stream for the custom pipeline.
            type: string
        flink_configuration:
          type: object
          additionalProperties:
            type: string
          description: A key-value pair of additional Flink configuration to apply to the job

    SnapshotConfiguration:
      description: The pipeline snapshot configuration.
      type: object
      properties:
        enabled:
          description: Whether or not to take snapshots.
          type: boolean
        cron:
          description: A cron expression for scheduling the snapshot
          type: string
        retention_period_seconds:
          description: A retention period for the created snapshots, in seconds.
          type: number

    AutoscaleConfiguration:
      description: The configuration for autoscale conditions.
      type: object
      nullable: true
      properties:
        pause_conditions:
          type: object
          description: A map of pause conditions and their given setting values.
          nullable: true
          additionalProperties:
            type: string
            nullable: true
        resume_conditions:
          type: object
          description: A map of resume conditions and their given setting values.
          nullable: true
          additionalProperties:
            type: string
            nullable: true
      example:
        pause_conditions:
          max_record_read_rate:
            record_count: "100"
            duration_seconds: "300"
          max_job_runtime:
            duration_seconds: "3600"
        resume_conditions:
          schedule:
            cron_expression: "0 8 * * *"

    PipelineStream:
      description: Stream connected to a pipeline
      type: object
      properties:
        pipeline_id:
          description: The pipeline id.
          type: string
        version:
          description: The version of the pipeline.
          type: integer
        is_source:
          description: Whether this stream is a source for the pipeline. Otherwise it is a sink.
          type: boolean
        stream_id:
          description: The id of the linked stream
          type: string

    TargetObjectState:
      description: describe a target state of an object
      type: object
      properties:
        target_state:
          type: string
          enum: [ RUNNING, STOPPED ]

    ActualObjectState:
      description: describe an actual state of an object
      type: object
      properties:
        actual_state:
          type: string
          enum: [ UNKNOWN, STARTING, RUNNING, FAILED, FINISHED, STOPPED, PAUSING, PAUSED ]

    ObjectState:
      description: describe a state of an object
      type: object
      properties:
        last_activated_time:
          type: string
          description: The date and time this object was last activated.
          format: date-time
      allOf:
        - $ref: '#/components/schemas/TargetObjectState'
        - $ref: '#/components/schemas/ActualObjectState'

    RequestedTasks:
      description: the number of tasks to be allocated to an object when it is activated
      type: integer

    ActualTasks:
      description: the number of tasks actively in use by an object
      type: integer

    RequestedTaskSize:
      description: the task size to be allocated to an object when it is activated
      type: string
      nullable: true

    ActualTaskSize:
      description: the task size actively in use by an object
      type: string
      nullable: true

    ObjectTasks:
      description: the number of tasks used when an object is activated
      type: object
      properties:
        requested_tasks:
          $ref: '#/components/schemas/RequestedTasks'
        actual_tasks:
          $ref: '#/components/schemas/ActualTasks'
        requested_task_size:
          $ref: '#/components/schemas/RequestedTaskSize'
        actual_task_size:
          $ref: '#/components/schemas/ActualTaskSize'

    PipelineVersionState:
      description: describe a state of a pipeline
      type: object
      allOf:
        - properties:
            id:
              $ref: "#/components/schemas/ResourceId"
            version:
              $ref: "#/components/schemas/ResourceVersionNumber"
        - $ref: "#/components/schemas/ObjectState"

    PipelineStatus:
      description: describe a state of a pipeline
      type: object
      properties:
        latest:
          $ref: '#/components/schemas/PipelineVersionState'
        active:
          $ref: '#/components/schemas/PipelineVersionState'

    Connection:
      description: A connection.
      type: object
      required:
        - id
        - name
        - connector
        - type
        - create_time
      anyOf:
        - required: [ schema ]
        - required: [ schema_v2 ]
      allOf:
        - properties:
            id:
              $ref: "#/components/schemas/ResourceId"
        - $ref: "#/components/schemas/ConnectionCommon"
        - $ref: "#/components/schemas/ConnectionV1Status"

    ConnectionCommon:
      description: Common connection fields in requests and responses.
      type: object
      allOf:
        - properties:
            name:
              description: The connection name.
              type: string
            description:
              description: The connection description.
              type: string
        - $ref: "#/components/schemas/ConnectionV1Spec"

    ConnectionV1Spec:
      type: object
      title: "connection @ v1"
      description: |
        `kind: connection`, `spec_version: v1`.
      properties:
        connector:
          description: The connector used by the connection.
          type: string
          enum:
            - astra-streaming
            - clickhouse
            - confluent-cloud
            - datadog
            - datagen
            - delta-lake
            - druid
            - dynamodb-cdc
            - elasticsearch
            - gcp-pubsub
            - hudi
            - influxdb
            - kafka
            - kinesis
            - mongodb
            - mongodb-cdc
            - ms-sql
            - mysql-cdc
            - oracle
            - oracle-cdc
            - pinot
            - polaris
            - postgres
            - postgres-cdc
            - pulsar
            - redis
            - redpanda
            - redshift
            - rest
            - rockset
            - s3
            - s3-lambda
            - s3-v2
            - singlestore-db
            - snowflake
            - startree
            - streamnative
            - timescale
        type:
          description: The connection type.
          type: string
          enum:
            - source
            - sink
        stream_mappings:
          description: |
            The connection stream mappings.  If present, `schema` and `stream_id` must be `null`.
          type: array
          items:
            type: object
            properties:
              stream_id:
                $ref: "#/components/schemas/ResourceId"
              external_resource_specifier:
                additionalProperties:
                  type: string
                  nullable: true
        stream_id:
          $ref: "#/components/schemas/ResourceId"
        schema:
          $ref: "#/components/schemas/RecordSchema"
        schema_v2:
          $ref: "#/components/schemas/SchemaV2"
        properties:
          description: The connection properties.
          type: object
          additionalProperties:
            type: string
            nullable: true
        autoscale_configuration:
          $ref: '#/components/schemas/AutoscaleConfiguration'

    ConnectionV1Status:
      type: object
      title: "connection @ v1"
      description: |
        `kind: connection`, `spec_version: v1`.
      allOf:
        - properties:
            last_runtime_error:
              $ref: "#/components/schemas/RuntimeError"
        - $ref: "#/components/schemas/ObjectState"
        - $ref: "#/components/schemas/ActualSystemFlinkConfiguration"
        - $ref: "#/components/schemas/SystemFlinkConfiguration"
        - $ref: "#/components/schemas/ObjectTasks"
        - $ref: "#/components/schemas/ResourceTimestamps"

    RestEvents:
      description: Events schema for the REST connector
      type: object
      required:
        - events
      properties:
        events:
          description: The events to be sent, formatted to the connection schema
          type: array
          items:
            description: Event records
            type: object

    Stream:
      description: A stream.
      type: object
      anyOf:
        - required: [ schema ]
        - required: [ schema_v2 ]
      required:
        - id
        - name
        - create_time
      allOf:
        - properties:
            id:
              $ref: "#/components/schemas/ResourceId"
            type:
              $ref: "#/components/schemas/StreamType"
        - $ref: "#/components/schemas/StreamCommon"
        - $ref: "#/components/schemas/StreamV1Status"

    StreamCommon:
      description: Common stream fields in requests and responses.
      type: object
      allOf:
        - properties:
            name:
              description: The stream name.
              type: string
            description:
              description: The stream description.
              type: string
        - $ref: "#/components/schemas/StreamV1Spec"

    StreamV1Spec:
      type: object
      title: "stream @ v1"
      description: |
        `kind: stream`, `spec_version: v1`.
      properties:
        watermark:
          description: The stream watermark strategy.
          type: string
        schema:
          $ref: "#/components/schemas/RecordSchema"
        schema_v2:
          $ref: "#/components/schemas/SchemaV2"
        properties:
          description: The stream properties.
          type: object
          additionalProperties:
            type: string
            nullable: true
        partition_key:
          description: The fields to use to partition data in the stream
          type: array
          items:
            type: string

    StreamV1Status:
      type: object
      title: "stream @ v1"
      description: |
        `kind: stream`, `spec_version: v1`.
      allOf:
        - $ref: "#/components/schemas/ResourceTimestamps"

    StreamCompatibility:
      description: A stream compatibility response.
      type: object
      required:
        - compatible
      properties:
        compatible:
          description: if the request schema is compatible
          type: boolean
        error:
          description: error message if the schema is not compatible
          type: string

    StreamPreview:
      description: A stream preview response.
      type: object
      required:
        - results
      properties:
        results:
          description: Result rows from preview.
          type: array
          items:
            description: Preview result row
            type: object
            required:
              - value
              - _timestamp
            properties:
              _timestamp:
                description: The processing time as a unix timestamp in milliseconds
                type: integer
              key:
                description: The record's primary key
                type: object
              value:
                description: The record value
                type: object

    StreamType:
      description: The stream type.
      type: string
      enum: [ APPEND, CHANGE ]
      default: APPEND

    Secret:
      description: A secret.
      type: object
      required:
        - id
        - name
      allOf:
        - properties:
            id:
              $ref: "#/components/schemas/ResourceId"
        - $ref: "#/components/schemas/SecretCommon"
        - $ref: "#/components/schemas/ResourceTimestamps"

    SecretCommon:
      description: Common secret fields in requests and responses.
      type: object
      properties:
        name:
          description: The secret name.
          type: string
        description:
          description: The secret description.
          type: string

    SecretV1Spec:
      type: object
      title: "secret @ v1"
      description: |
        `kind: secret`, `spec_version: v1`: no `spec`.
      nullable: true

    SecretV1Status:
      type: object
      title: "secret @ v1"
      description: |
        `kind: secret`, `spec_version: v1`.
      allOf:
        - $ref: "#/components/schemas/ResourceTimestamps"

    File:
      description: Metadata for a file.
      properties:
        sha:
          type: string
          description: The sha512 hash of the file
        type:
          type: string
          description: The type of the file
          enum:
            - JOB_FILE
            - CONFIG_FILE
        name:
          type: string
          description: The filename
        size:
          type: number
          description: The file size in bytes
        metadata:
          type: object
          description: Additional metadata for the file

    AccountCommon:
      description: Common fields of an Account.
      type: object
      required:
        - name
        - display_name
        - auth0_org_id
      properties:
        name:
          $ref: "#/components/schemas/AccountName"
        display_name:
          description: Unconstrained, for display.
          type: string
        auth0_org_id:
          description: The organization id from Auth0 for this account
          type: string

    Account:
      description: Account fields
      type: object
      allOf:
        - $ref: "#/components/schemas/AccountCommon"
        - $ref: "#/components/schemas/AccountSubscription"

    AccountResponse:
      description: Account fields, including derived properties
      type: object
      allOf:
        - $ref: "#/components/schemas/AccountCommon"
        - $ref: "#/components/schemas/SubscriptionResponse"

    AccountSubscription:
      description: Account Subscription Info
      type: object
      required:
        - subscription
        - deployment_type
      properties:
        subscription:
          description: Subscription information
          type: object
          properties:
            plan_id:
              type: string
              description: plan id
        deployment_type:
          description: Deployment type
          type: string

    SubscriptionResponse:
      description: Subscription properties, including derived fields
      type: object
      required:
        - subscription
      properties:
        subscription:
          $ref: '#/components/schemas/Subscription'

    AccountInfo:
      description: Account information
      type: object
      required:
        - subscription
        - deployment_type
        - account_id
        - data_plane_hostname
        - data_plane
      properties:
        subscription:
          $ref: '#/components/schemas/Subscription'
        deployment_type:
          $ref: "#/components/schemas/DeploymentType"
        data_plane_hostname:
          type: string
          description: The hostname of the data plane API.
        data_plane:
          description: data plane information
          type: object
          properties:
            data_plane_id:
              type: string
              format: string
              description: The ID of the data plane.
            hostname:
              type: string
              description: The hostname of the data plane API.
            last_registration_time:
              type: string
              format: date-time
              description: The last registration time of the data plane
            last_heart_beat_time:
              type: string
              format: date-time
              description: The last heart beat time of the data plane
            mtls_signing_state:
              type: string
              enum: [NONE, REQUESTED, AVAILABLE]
              description: The state of the mTLS certificate for authenticating the data plane

    Subscription:
      description: Subscription information
      type: object
      properties:
        plan_id:
          type: string
          description: plan id
        capabilities:
          type: array
          description: Describes which additional capabilities are enabled for this account. Possible values are "custom_pipelines". New values may be added in future API versions; consumers should be able to gracefully handle unknown values.
          items:
            type: string

    DeploymentType:
      description: The deployment type.
      type: string
      enum: [ managed, byoc ]
      default: managed

    AccountMetadata:
      description: Metadata for a Decodable account.
      type: object
      required:
        - cell_id
        - region
        - cloud
      properties:
        cell_id:
          description: The id of the Decodable cell in which the account resides.
          type: string
        region:
          description: The name of the region in which the account resides.
          type: string
        cloud:
          description: The name of the cloud in which the account resides.
          type: string

    PreviewCreateRequest:
      description: A preview creation request.
      type: object
      required:
        - sql
      properties:
        sql:
          description: The sql for the preview to run.
          type: string
        support_change_stream:
          description: If the client can support reading change stream
          type: boolean
          default: false
        start_positions:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/StartPosition"

    Preview:
      description: A preview response.
      type: object
      required:
        - id
      properties:
        id:
          $ref: "#/components/schemas/ResourceId"
        output_stream_type:
          type: string
          enum:
            - APPEND
            - CHANGE
        results:
          description: Result rows from preview.
          type: array
          items:
            description: Preview result row
            type: object
        next_token:
          description: A token used to fetch the next available results.
          type: string

    NestedMetrics:
      description: A nested metrics response.
      type: object
      properties:
        metrics:
          $ref: "#/components/schemas/Metrics"

    Metrics:
      description: A metrics response.
      type: object
      required:
        - sources
        - sinks
        - update_time
      properties:
        sources:
          type: object
          additionalProperties:
            type: object
            properties:
              bytes_in_total:
                type: number
                format: double
              bytes_in_per_second:
                type: number
                format: double
              records_in_total:
                type: number
                format: double
              records_in_per_second:
                type: number
                format: double
        sinks:
          type: object
          additionalProperties:
            type: object
            properties:
              bytes_out_total:
                type: number
                format: double
              bytes_out_per_second:
                type: number
                format: double
              records_out_total:
                type: number
                format: double
              records_out_per_second:
                type: number
                format: double
        additional:
          type: object
          additionalProperties:
            type: number
            format: double
        update_time:
          type: string
          format: date-time

    ResourceType:
      description: A resource type.
      type: string
      enum:
        - connection
        - pipeline
        - stream

    DataPlaneJwtToken:
      description: |
        A JWT token issued by the control plane API permitting a specific request to the data plane.
      type: string

    DependencyCommon:
      description: A dependency item.
      type: object
      required:
        - resource_type
        - resource_id
        - resource_name
      properties:
        resource_type:
          $ref: "#/components/schemas/ResourceType"
        resource_id:
          type: string
        resource_name:
          type: string
      discriminator:
        propertyName: resource_type

    ConnectionDependency:
      allOf:
        - $ref: "#/components/schemas/DependencyCommon"
        - type: object
          required:
            - connector
          properties:
            connector:
              type: string

    PipelineDependency:
      allOf:
        - $ref: "#/components/schemas/DependencyCommon"
        - type: object
          required:
            - version
          properties:
            version:
              type: integer

    StreamDependency:
      allOf:
        - $ref: "#/components/schemas/DependencyCommon"

    DependencyItem:
      description: A dependency item.
      oneOf:
        - $ref: "#/components/schemas/ConnectionDependency"
        - $ref: "#/components/schemas/PipelineDependency"
        - $ref: "#/components/schemas/StreamDependency"

    StartPosition:
      description: A descriptor of a start position on a stream
      type: object
      properties:
        type:
          type: string
        value:
          type: string

    User:
      description: A user.
      type: object
      required:
        - id
      allOf:
        - properties:
            id:
              $ref: "#/components/schemas/ResourceId"
        - $ref: "#/components/schemas/UserCommon"
        - $ref: "#/components/schemas/ResourceTimestamps"

    UserCommon:
      description: Common user fields in requests and responses.
      type: object
      properties:
        name:
          description: Full name, typically including both given_name and family_name
          type: string
        email:
          description: Email address
          type: string
        given_name:
          description: Given name
          type: string
        family_name:
          description: Family name
          type: string
        picture:
          description: URL to picture, photo, or avatar of this user
          type: string

    Group:
      description: A group.
      type: object
      required:
        - name
      allOf:
        - properties:
            id:
              $ref: "#/components/schemas/ResourceId"
        - $ref: "#/components/schemas/GroupCommon"
        - $ref: "#/components/schemas/ResourceTimestamps"

    GroupCommon:
      description: Common group fields in requests and responses.
      type: object
      properties:
        name:
          description: The group name.
          type: string
          minLength: 1
          maxLength: 63
          pattern: "^[a-zA-Z]([a-zA-Z0-9_-]){0,62}$"
        description:
          description: The group description.
          type: string

    Role:
      description: A role.
      type: object
      required:
        - name
      allOf:
        - properties:
            id:
              $ref: "#/components/schemas/ResourceId"
        - $ref: "#/components/schemas/RoleCommon"
        - $ref: "#/components/schemas/ResourceTimestamps"

    RoleCommon:
      description: Common role fields in requests and responses.
      type: object
      properties:
        name:
          description: The role name.
          type: string
          minLength: 1
          maxLength: 63
          pattern: "^[a-zA-Z]([a-zA-Z0-9_-]){0,62}$"
        description:
          description: The role description.
          type: string

    Permission:
      description: A role permission.
      type: object
      required:
        - effect
        - pattern
      properties:
        effect:
          description: allow or deny.
          type: string
          enum:
            - allow
            - deny
        pattern:
          description: "A three-part, colon(:)-delimited permission selector pattern, using asterisk (*) as wildcard.  Takes form: <type>:<action>:<qualified-name>"
          type: string
          pattern: "^[^:]*:[^:]*:[^:]$"
          example: "type:action:qualified-name"

    Snapshot:
      type: object
      properties:
        id:
          description: An identifier for the snapshot
          type: string
        job_id:
          description: The id of the pipeline or connection that initially created the snapshot.
          type: string
        name:
          description: The name of the snapshot.
          type: string
        type:
          $ref: '#/components/schemas/SnapshotType'
        start_time:
          description: The date and time the snapshot was started.
          type: string
          format: date-time
        end_time:
          description: The date and time the snapshot was completed.
          type: string
          format: date-time
        retention_time:
          description: The date and time the snapshot will be retained until.
          type: string
          format: date-time
        state:
          $ref: '#/components/schemas/SnapshotState'

    SnapshotType:
      description: The scheduling type of the snapshot.
      type: string
      enum:
        - "SCHEDULED"
        - "ONE_TIME"

    SnapshotState:
      description: The current state of the snapshot.
      type: string
      enum:
        - "SCHEDULED"
        - "FINISHED"
        - "FAILED"
        - "EXPIRED"
        - "DELETING"
        - "DELETED"
  parameters:

    AccountName:
      name: name
      description: The Decodable Account name, globally unique, hostname segment compliant.
      in: path
      required: true
      schema:
        type: string
        minLength: 3
        maxLength: 50
        pattern: "[a-z][a-z0-9]*(-[a-z0-9]+)*"

    ResourceId:
      name: id
      description: An ID that uniquely identifies a resource.
      in: path
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 256
        pattern: "[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*"
        example: abcd1234

    SnapshotId:
      name: snapshot_id
      description: An ID that uniquely identifies a snapshot.
      in: path
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 256
        pattern: "[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*"
        example: abcd1234

    UserId:
      name: user_id
      description: An ID that uniquely identifies a user.
      in: path
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 256
        pattern: "[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*"
        example: abcd1234

    GroupId:
      name: group_id
      description: An ID that uniquely identifies a group.
      in: path
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 256
        pattern: "[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*"
        example: abcd1234

    RoleId:
      name: role_id
      description: An ID that uniquely identifies a role.
      in: path
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 256
        pattern: "[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*"
        example: abcd1234

    # NB: Object view is the view=basic|full parameter, not a SQL view.
    ResourceView:
      description: |
        The amount of data to return for the resource(s).

        A value of `basic` returns the standard properties of the resource. It may also produce data that is
        considered "computationally cheap" to return. Specifying `basic` is the same as omitting this parameter.

        The behavior of `full` is service-dependent, but generally includes more fields. This can mean additional status
        or version data, or even expanding references to contained resources. This should be used when the cost of an
        additional API roundtrip is greater than the overhead of the request.
      name: view
      in: query
      schema:
        $ref: "#/components/schemas/ResourceView"

    ResourceVersion:
      name: version
      description: A version of a resource. It can be a version number or a version selector.
      in: query
      schema:
        oneOf:
          - $ref: "#/components/schemas/ResourceVersionNumber"
          - $ref: "#/components/schemas/ResourceVersionSelector"

    SchemaType:
      name: schema_type
      description: The type of resource's schema
      in: query
      schema:
        type: string
        enum: [ logical, physical ]
        default: logical

    ForceFlag:
      name: force
      description: Flags an operation is performed forcefully
      in: query
      schema:
        type: boolean
        default: false

    DeprecatedForceFlag:
      name: force
      description: This flag is deprecated and no longer has any effect. All deactivations are forced if graceful termination fails.
      in: query
      deprecated: true
      schema:
        type: boolean
        default: false

    ActivationTasks:
      name: tasks
      description: The number of tasks allocated to an object upon activation
      in: query
      schema:
        type: integer
        example: 1

    Version:
      name: version
      description: The API major version.
      in: path
      required: true
      schema:
        type: string
        pattern: "v[0-9]+(?:(?:(alpha)|(beta))[0-9]+)?"
        example: v1alpha2

    PageSize:
      description: The maximum number of items to return.
      name: page_size
      in: query
      schema:
        type: integer
        minimum: 0
        maximum: 500
        example: 100

    PageToken:
      description: A token that indicates the page to fetch.
      name: page_token
      in: query
      schema:
        type: string
        example: token1

    TaskIndex:
      description: An index for the task logs to query. 0 implies JobManager, 1+ are indices for TaskManagers
      name: task_index
      in: query
      schema:
        type: integer
        minimum: 0
        example: 0
        default: 0

    NumLines:
      description: The number of lines to return
      name: num_lines
      in: query
      schema:
        type: integer
        minimum: 1
        example: 20
        default: 20

    Follow:
      description: Whether the logging request should be made for following logs
      name: follow
      in: query
      schema:
        type: boolean
        default: false

    ResponseSchemaV:
      name: response_schema_v
      description: |
        The response schema version to use. Defaults to `v1`.
        When `v1`, the response will include the `schema` field. 
        When `v2`, the response will include the `schema_v2` field.
      in: query
      required: false
      schema:
        type: string
        enum: [ v1, v2 ]
        default: v1

  requestBodies:

    # Declarative Requests

    DeclarativeApplyRequest:
      description: |
        A declarative `apply` request: zero or more YAML docs, each with this schema.
      required: true
      content:
        application/x-yaml:
          schema:
            $ref: "#/components/schemas/DeclarativeDefinition"
          example: |
            ---
            kind: connection
            metadata:
              name: example_rest_connection
              description: Write messages to a stream.
              tags:
                example_key: example value
            spec_version: v2
            spec:
              connector: rest
              type: source
              stream_name: example_stream
              schema_v2:
                fields:
                  - kind: physical
                    name: message
                    type: STRING NOT NULL
              properties:
                format: json
                parse-error-policy: IGNORE
              execution:
                active: true
                task_count: 1
                task_size: M
            ---
            kind: stream
            metadata:
              name: example_stream
            spec_version: v1
            spec:
              type: APPEND
              schema_v2:
                fields:
                  - kind: physical
                    name: message
                    type: STRING NOT NULL

    DeclarativeQueryRequest:
      description: |
        A declarative `query` request: one YAML doc with this schema.
      required: true
      content:
        application/x-yaml:
          schema:
            $ref: "#/components/schemas/DeclarativeQuerySpecifier"
          example: |
            ---
            kinds:
              - connection
              - pipeline
            names:
              - demo_*
              - "*_tmp"
            ids: [83ed9491,ca64352b,044b98ff]
            resources:
              - kind: connection
                name: demo_1_input
              - kind: pipeline
                name: demo_1_processor
            no_status: true

    # Pipeline Requests

    CreatePipelineRequest:
      description: A pipeline creation request.
      required: true
      content:
        application/json:
          schema:
            required:
              - name
              - sql
            allOf: # This allOf allows us to add required with a $ref.
              - $ref: "#/components/schemas/SqlPipelineCommon"

    CreateCustomPipelineRequest:
      description: A custom pipeline creation request.
      required: true
      content:
        application/json:
          schema:
            required:
              - name
              - type
              - job_file_sha
            properties:
              type:
                description: The type of the pipeline.
                type: string
                enum: [ JAVA, PYTHON ]
            allOf:
              - $ref: "#/components/schemas/CustomPipelineRequestCommon"

    PipelineOutputStreamRequest:
      description: A request to get pipeline output stream
      required: true
      content:
        application/json:
          schema:
            description: A pipeline output stream request.
            type: object
            required:
              - sql
            properties:
              sql:
                description: The pipeline sql
                type: string

    UpdatePipelineRequest:
      description: A pipeline update request.
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SqlPipelineCommon"

    UpdateCustomPipelineRequest:
      description: A custom pipeline update request.
      required: true
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/CustomPipelineRequestCommon"

    ActivatePipelineRequest:
      description: A pipeline activation request.
      required: false
      content:
        application/json:
          schema:
            type: object
            properties:
              start_positions:
                type: object
                additionalProperties:
                  $ref: "#/components/schemas/StartPosition"
              task_size:
                description: A task size identifier.
                type: string
                nullable: true
              start_from_snapshot_id:
                description: A snapshot id to restore from.
                type: string
                nullable: true

    SnapshotRequest:
      description: A snapshot request.
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                description: The name of the snapshot.
                type: string
              retention_period_seconds:
                description: A retention period for the created snapshots, in seconds.
                type: number

    # Connection Requests

    CreateConnectionRequest:
      description: A connection creation request.
      required: true
      content:
        application/json:
          schema:
            required:
              - name
              - connector
              - type
            allOf: # This allOf allows us to add required with a $ref.
              - $ref: "#/components/schemas/ConnectionCommon"

    UpdateConnectionRequest:
      description: A connection update request.
      required: true
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ConnectionCommon"

    OptionallyModifyConnectionRequest:
      description: Optional changes to apply to a connection.
      required: false
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ConnectionCommon"

    PostConnectionEventsRequest:
      description: A post events request
      required: true
      content:
        application/json:
          schema:
            required:
              - events
            allOf:
              - $ref: "#/components/schemas/RestEvents"
          example:
            events:
              - field1: foo
                field2: bar
              - field1: baz
                field2: bot

    ActivateConnectionRequest:
      description: A connection activation request.
      required: false
      content:
        application/json:
          schema:
            type: object
            properties:
              start_position:
                $ref: "#/components/schemas/StartPosition"
              task_size:
                description: A task size identifier.
                type: string
                nullable: true

    # Stream Requests

    CreateStreamRequest:
      description: A stream creation request.
      required: true
      content:
        application/json:
          schema:
            required:
              - name
            anyOf:
              - required: [ schema ]
              - required: [ schema_v2 ]
            allOf: # This allOf allows us to add required with a $ref.
              - $ref: "#/components/schemas/StreamCommon"

    UpdateStreamRequest:
      description: A stream update request.
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StreamCommon"

    StreamCompatibilityRequest:
      description: A stream compatibility request
      required: true
      content:
        application/json:
          schema:
            required:
              - direction
            anyOf:
              - required: [ schema ]
              - required: [ schema_v2 ]
            properties:
              schema:
                $ref: "#/components/schemas/RecordSchema"
              schema_v2:
                $ref: "#/components/schemas/SchemaV2"
              side:
                type: string
                enum: [ LEFT, RIGHT ]

    # Secret Requests

    CreateSecretRequest:
      description: A secret creation request.
      required: true
      content:
        application/json:
          schema:
            required:
              - name
            allOf: # This allOf allows us to add required with a $ref.
              - $ref: "#/components/schemas/SecretCommon"

    UpdateSecretRequest:
      description: A secret update request.
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SecretCommon"

    # File Requests

    UploadFileRequest:
      description: An upload file request. Authorization is performed against the file names included in the request.
      required: true
      content:
        application/json:
          schema:
            required:
              - names
            properties:
              names:
                type: array
                items:
                  type: string


    # Account Requests

    CreateAccountRequest:
      description: A Decodable Account creation request.
      required: true
      content:
        application/json:
          schema:
            required:
              - name
              - display_name
              - region
            allOf: # This allOf allows us to add required with a $ref.
              - $ref: "#/components/schemas/Account"
              - properties:
                  region:
                    description: Cloud region in which the account should be created
                    type: string
                  invite_emails:
                    description: Emails to which invites to the new account should be sent
                    type: array
                    items:
                      type: string

    UpdateAccountRequest:
      description: A Decodable Account update request.
      required: true
      content:
        application/json:
          schema:
            required:
              - subscription
            allOf:
              - $ref: "#/components/schemas/AccountSubscription"

    # Preview Requests

    CreatePreviewRequest:
      description: A preview creation request.
      required: true
      content:
        application/json:
          schema:
            required:
              - sql
            allOf: # This allOf allows us to add required with a $ref.
              - $ref: "#/components/schemas/PreviewCreateRequest"

    PreviewDependencyRequest:
      description: A preview dependency request.
      required: true
      content:
        application/json:
          schema:
            required:
              - sql
            properties:
              sql:
                description: The sql to get dependencies for.
                type: string

    PreviewTokensRequest:
      description: |
        A request to generate the JWT tokens needed to start and fetch a preview using the data plane API.
      required: true
      content:
        application/json:
          schema:
            required:
              - sql
            properties:
              sql:
                description: The sql to execute as a preview.
                type: string
              start_positions:
                type: object
                additionalProperties:
                  $ref: "#/components/schemas/StartPosition"

    # Schema Requests

    SchemaRequest:
      description: A schema request.
      required: true
      content:
        application/json:
          schema:
            required:
              - content
              - type
            type: object
            properties:
              content:
                description: The schema object to compile
                type: string
              type:
                description: The type of schema to compile
                type: string
                enum: [ JSON, JSON_SAMPLE, AVRO, PROTOBUF ]

    # Access management: Group Requests

    PostGroupRequest:
      description: A group post request.
      required: true
      content:
        application/json:
          schema:
            required:
              - name
            allOf: # This allOf allows us to add required with a $ref.
              - properties:
                  id:
                    $ref: "#/components/schemas/ResourceId"
              - $ref: "#/components/schemas/GroupCommon"

    # Access management: Role Requests

    PostRoleRequest:
      description: A role post request.
      required: true
      content:
        application/json:
          schema:
            required:
              - name
            allOf: # This allOf allows us to add required with a $ref.
              - properties:
                  id:
                    $ref: "#/components/schemas/ResourceId"
              - $ref: "#/components/schemas/RoleCommon"

    PutRolePermissionsRequest:
      description: A role permissions put request.
      required: true
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/Permission"
    
    # Certificate Requests

    PostCertificateSignRequest:
      description: A CSR Upload request.
      required: true,
      content:
        multipart/form-data:
          schema:
            type: object
            properties:
              file:
                type: string
                format: binary
                description: The RFC 5967 `application/pkcs10` file to be uploaded
          encoding:
            file:
              contentType: application/octet-stream

  responses:

    # Declarative Responses

    DeclarativeApplyResponse:
      description: |
        Success: Zero or more YAML docs, each with this schema.
        
        Note that the response will be `application/x-yaml` by default (with one YAML doc per resource definition), but `application/json` may be selected via the `Accept:` request header.
      content:
        application/x-yaml:
          schema:
            $ref: "#/components/schemas/DeclarativeResult"
          example: |
            ---
            kind: connection
            name: example_rest_connection
            id: a0c4f4e7
            result: created
            ---
            kind: stream
            name: example_stream
            id: eb43aff8
            result: updated
        application/json:
          schema:
            $ref: "#/components/schemas/DeclarativeResult"
          example:
            items:
              - kind: connection
                name: example_rest_connection
                id: a0c4f4e7
                result: created
              - kind: stream
                name: example_stream
                id: eb43aff8
                result: updated
    DeclarativeQueryResponse:
      description: |
        A declarative `query` response: zero or more resource definitions, each with this schema.
        
        Note that the response will be `application/x-yaml` by default (with one YAML doc per resource definition), but `application/json` may be selected via the `Accept:` request header.
      content:

        application/x-yaml:
          schema:
            $ref: "#/components/schemas/DeclarativeDefinitionWithStatus"
          example: |
            ---
            kind: connection
            metadata:
              name: example_rest_connection
              description: Write messages to a stream.
              tags:
                example_key: example value
            spec_version: v2
            spec:
              connector: rest
              type: source
              stream_name: example_stream
              schema_v2:
                fields:
                  - kind: physical
                    name: message
                    type: STRING NOT NULL
              properties:
                format: json
                parse-error-policy: IGNORE
              execution:
                active: true
                task_count: 1
                task_size: M
            status:
              create_time: 2024-03-22T23:04:35.013+00:00
              update_time: 2024-03-22T23:04:35.013+00:00
              target_state: STOPPED
              actual_state: STOPPED
              requested_tasks: 1
              requested_task_size: M
              last_activated_time: 2024-03-22T23:13:48.738+00:00
              properties:
                endpoint: /v1alpha2/connections/abcd1234/events
                url: https://1.api.data.decodable.co/v1alpha2/connections/abcd1234/events
            ---
            kind: stream
            metadata:
              name: example_stream
            spec_version: v1
            spec:
              type: APPEND
              schema_v2:
                fields:
                  - kind: physical
                    name: message
                    type: STRING NOT NULL
            status:
              create_time: 2024-03-22T23:04:35.013+00:00
              update_time: 2024-03-22T23:04:35.013+00:00

        application/json:
          schema:
            $ref: "#/components/schemas/DeclarativeDefinitionWithStatus"
          example:
            items:
              - kind: connection
                metadata:
                  name: example_rest_connection
                  description: Write messages to a stream.
                spec_version: v2
                spec:
                  connector: rest
                  type: source
                  stream_name: example_stream
                  schema_v2:
                    fields:
                      - kind: physical
                        name: message
                        type: STRING NOT NULL
                  properties:
                    format: json
                    parse-error-policy: IGNORE
                  execution:
                    active: true
                    task_count: 1
                    task_size: M
                status:
                  create_time: "2024-03-22T23:04:35.013+00:00"
                  update_time: "2024-03-22T23:04:35.013+00:00"
                  target_state: STOPPED
                  actual_state: STOPPED
                  requested_tasks: 1
                  requested_task_size: M
                  last_activated_time: "2024-03-22T23:13:48.738+00:00"
                  properties:
                    endpoint: /v1alpha2/connections/abcd1234/events
                    url: https://1.api.data.decodable.co/v1alpha2/connections/abcd1234/events
              - kind: stream
                metadata:
                  name: example_stream
                spec_version: v1
                spec:
                  type: APPEND
                  schema_v2:
                    fields:
                      - kind: physical
                        name: message
                        type: STRING NOT NULL
                status:
                  create_time: "2024-03-22T23:04:35.013+00:00"
                  update_time: "2024-03-22T23:04:35.013+00:00"

    # Pipeline Responses

    CreatePipelineResponse:
      description: A pipeline creation response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Pipeline"

    GetPipelineResponse:
      description: |
        A pipeline get response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Pipeline"

    UpdatePipelineResponse:
      description: A pipeline update response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Pipeline"

    ActivationDeactivationResponse:
      description: A pipeline activation/deactivation response.
      content:
        application/json:
          schema:
            allOf:
              - properties:
                  id:
                    $ref: "#/components/schemas/ResourceId"
                  version:
                    $ref: "#/components/schemas/ResourceVersionNumber"
              - $ref: '#/components/schemas/TargetObjectState'
              - $ref: '#/components/schemas/RequestedTasks'

    ListPipelinesResponse:
      description: A list of pipelines.
      content:
        application/json:
          schema:
            required:
              - items
            type: object
            properties:
              next_page_token:
                description: |
                  A token that, that when passed to a subsequent call as page_token, will return the next page of
                  results.
                type: string
              items:
                description: An array of pipelines.
                type: array
                items:
                  $ref: "#/components/schemas/Pipeline"

    PipelineStreamsResponse:
      description: A list of streams linked to a pipeline.
      content:
        application/json:
          schema:
            required:
              - items
            type: object
            properties:
              next_page_token:
                description: |
                  A token that, that when passed to a subsequent call as page_token, will return the next page of
                  results.
                type: string
              items:
                description: An array of linked streams.
                type: array
                items:
                  $ref: "#/components/schemas/PipelineStream"

    PipelineStatusResponse:
      description: A pipeline status response
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PipelineStatus"

    # Connection Responses

    CreateConnectionResponse:
      description: A connection creation response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Connection"

    GetConnectionResponse:
      description: |
        A connection get response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Connection"

    UpdateConnectionResponse:
      description: A connection update response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Connection"

    ListConnectionsResponse:
      description: A list of connections.
      content:
        application/json:
          schema:
            required:
              - items
            type: object
            properties:
              next_page_token:
                description: |
                  A token that, that when passed to a subsequent call as page_token, will return the next page of
                  results.
                type: string
              items:
                description: An array of connections.
                type: array
                items:
                  $ref: "#/components/schemas/Connection"

    GetConnectionCertificateResponse:
      description: a connection certificate response.
      content:
        application/json:
          schema:
            type: object
            properties:
              pem:
                description: certificate string in pem format
                type: string

    PostConnectionEventsResponse:
      description: A post events response
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                description: number of written events
                type: integer

    # Stream Responses

    CreateStreamResponse:
      description: A stream creation response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Stream"

    GetStreamResponse:
      description: A stream get response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Stream"

    UpdateStreamResponse:
      description: A stream update response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Stream"

    ListStreamsResponse:
      description: A list of streams.
      content:
        application/json:
          schema:
            required:
              - items
            type: object
            properties:
              next_page_token:
                description: |
                  A token that, that when passed to a subsequent call as page_token, will return the next page of
                  results.
                type: string
              items:
                description: An array of streams.
                type: array
                items:
                  $ref: "#/components/schemas/Stream"

    StreamCompatibilityResponse:
      description: A stream compatibility response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StreamCompatibility"

    StreamPreviewResponse:
      description: A stream preview response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StreamPreview"

    # Secret Responses

    CreateSecretResponse:
      description: A secret creation response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Secret"

    GetSecretResponse:
      description: A secret get response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Secret"

    UpdateSecretResponse:
      description: A secret update response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Secret"

    ListSecretsResponse:
      description: A list of secrets.
      content:
        application/json:
          schema:
            required:
              - items
            type: object
            properties:
              next_page_token:
                description: |
                  A token that, that when passed to a subsequent call as page_token, will return the next page of
                  results.
                type: string
              items:
                description: An array of secrets.
                type: array
                items:
                  $ref: "#/components/schemas/Secret"

    # File Responses

    GetFileResponse:
      description: A file get response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/File"

    # Account Responses

    ListAccountsResponse:
      description: A list of Decodable Accounts.
      content:
        application/json:
          schema:
            required:
              - items
            type: object
            properties:
              next_page_token:
                description: |
                  A token that, that when passed to a subsequent call as page_token, will return the next page of
                  results.
                type: string
              items:
                description: An array of accounts.
                type: array
                items:
                  $ref: "#/components/schemas/AccountCommon"

    CreateAccountResponse:
      description: A Decodable Account creation response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AccountResponse"

    AccountMetadataResponse:
      description: Metadata for a Decodable Account.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AccountMetadata"

    AccountInfoResponse:
      description: Account information
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AccountInfo"


    GetCellsResponse:
      description: Cell IDs by Region by Cloud
      content:
        application/json:
          schema:
            type: object
            description: Keyed by Cloud code ("aws").
            additionalProperties:
              type: object
              description: Keyed by Region code ("us-west-2", etc).
              additionalProperties:
                type: array
                description: Cell IDs
                items:
                  type: string

    # Preview Responses

    CreatePreviewResponse:
      description: A preview creation response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Preview"

    GetPreviewResponse:
      description: A preview get response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Preview"

    # Data Plane Token Responses

    DataPlaneRequestAndToken:
      description: |
        A request and token issued by the control plane API for use with the data plane API.
      content:
        application/json:
          schema:
            type: object
            required:
              - token
            properties:
              token:
                $ref: "#/components/schemas/DataPlaneJwtToken"
              data_plane_request:
                type: string
                description: |
                  A stringified json request body for the data plane API which is permitted and signed by the associated JWT token.
                  It must be sent verbatim (including whitespace) in order to match the token signature.

    DataPlaneSqlPreviewRequestAndTokens:
      description: |
        A request and token issued by the control plane API for use with the data plane API.
      content:
        application/json:
          schema:
            type: object
            required:
              - post_token
              - get_token
              - data_plane_request
            properties:
              post_token:
                $ref: "#/components/schemas/DataPlaneJwtToken"
              get_token:
                $ref: "#/components/schemas/DataPlaneJwtToken"
              data_plane_request:
                type: string
                description: |
                  A stringified json request body for the data plane API which is permitted and signed by the associated JWT token.
                  It must be sent verbatim (including whitespace) in order to match the token signature.

    # Schema Responses

    SchemaResponse:
      description: A schema response.
      content:
        application/json:
          schema:
            type: object
            properties:
              schema:
                $ref: "#/components/schemas/RecordSchema"

    # Dependency Response

    DependencyResponse:
      description: A list of resource dependencies.
      content:
        application/json:
          schema:
            required:
              - inputs
              - outputs
            type: object
            properties:
              inputs:
                description: A list of resource dependencies.
                type: array
                items:
                  $ref: "#/components/schemas/DependencyItem"
              outputs:
                description: An array of resource dependencies.
                type: array
                items:
                  $ref: "#/components/schemas/DependencyItem"

    # Task Sizes Response

    TaskSizesResponse:
      description: A description of available task sizes.
      content:
        application/json:
          schema:
            type: object
            properties:
              sizes:
                description: A list of task sizes.
                type: array
                items:
                  description: A task size.
                  type: object
                  properties:
                    id:
                      description: An identifier for this task size.
                      type: string
                    name:
                      description: An user-readable name for this task size.
                      type: string
                    description:
                      description: An description of this task size.
                      type: string
                    resource_spec:
                      description: Specific resource allocations for this task size.
                      type: object
                      properties:
                        cpu:
                          description: The number of CPUs for this task size.
                          type: string
                        memory:
                          description: The amount of memory for this task size.
                          type: string
                    supported_plans:
                      description: The available plan types for this task size.
                      type: array
                      items:
                        type: string

    # Custom pipeline Flink versions response

    CustomPipelineFlinkVersionsResponse:
      description: A list of Flink versions supported for custom pipelines.
      content:
        application/json:
          schema:
            type: object
            properties:
              flink_versions:
                type: array
                description: A list of Flink versions.
                items:
                  description: A Flink version.
                  type: object
                  properties:
                    version_name:
                      description: The name of the version.
                      type: string
                    display_name:
                      description: The formatted name, for better readability.
                      type: string
                    supported_types:
                      description: Whether this is the default Flink version for custom pipelines.
                      type: array
                      items:
                        $ref: "#/components/schemas/PipelineType"
              defaults:
                description: The default Flink versions per pipeline type.
                type: object
                properties:
                  JAVA:
                    description: The default Flink version for Java-based pipelines.
                    type: string
                  PYTHON:
                    description: The default Flink version for Python-based pipelines.
                    type: string

    # Snapshot responses
    SnapshotsResponse:
      description: A list of snapshots.
      content:
        application/json:
          schema:
            type: object
            required:
              - items
            properties:
              next_page_token:
                description: |
                  A token that, that when passed to a subsequent call as page_token, will return the next page of results.
                type: string
              items:
                description: An array of snapshots.
                type: array
                items:
                  $ref: "#/components/schemas/Snapshot"

    SnapshotResponse:
      description: A single snapshot.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Snapshot"

    # Access management: User Responses

    GetUserResponse:
      description: A user get response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/User"

    ListUsersResponse:
      description: A list of users.
      content:
        application/json:
          schema:
            required:
              - items
            type: object
            properties:
              next_page_token:
                description: |
                  A token that, that when passed to a subsequent call as page_token, will return the next page of results.
                type: string
              items:
                description: An array of users.
                type: array
                items:
                  $ref: "#/components/schemas/User"

    # Access management: Group Responses

    GetGroupResponse:
      description: A group get response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Group"

    PostGroupResponse:
      description: A group post response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Group"

    ListGroupsResponse:
      description: A list of groups.
      content:
        application/json:
          schema:
            required:
              - items
            type: object
            properties:
              next_page_token:
                description: |
                  A token that, that when passed to a subsequent call as page_token, will return the next page of results.
                type: string
              items:
                description: An array of groups.
                type: array
                items:
                  $ref: "#/components/schemas/Group"

    # Access management: Role Responses

    GetRoleResponse:
      description: A role get response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Role"

    PostRoleResponse:
      description: A role post response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Role"

    ListRolesResponse:
      description: A list of roles.
      content:
        application/json:
          schema:
            required:
              - items
            type: object
            properties:
              next_page_token:
                description: |
                  A token that, that when passed to a subsequent call as page_token, will return the next page of results.
                type: string
              items:
                description: An array of roles.
                type: array
                items:
                  $ref: "#/components/schemas/Role"

    ListRolePermissionsResponse:
      description: A list of role permissions.
      content:
        application/json:
          schema:
            required:
              - items
            type: object
            properties:
              next_page_token:
                description: |
                  A token that, that when passed to a subsequent call as page_token, will return the next page of results.
                type: string
              items:
                description: An array of permissions.
                type: array
                items:
                  $ref: "#/components/schemas/Permission"

    # Certificate Responses

    GetSignedCertificateResponse:
      description: A signed certificate.
      headers:
        Content-Disposition:
          description: The disposition type and filename of the returned file.
          schema:
            type: string
            example: attachment; filename="signed-cert.pem"
      content:
        application/x-pem-file:
          schema:
            type: string
            format: binary
          example: |
            -----BEGIN CERTIFICATE-----
            MIIFSDCCBDCg...
            -----END CERTIFICATE-----

    # Error Responses
    ErrorUnsupportedMediaTypeResponse:
      description: Media type is not supported.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    ErrorResourceExistsResponse:
      description: A conflicting resource already exists.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    ErrorResourceDoesNotExistResponse:
      description: The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    ErrorResourceConflictResponse:
      description: A resource conflict has been detected.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    ErrorBadRequestResponse:
      description: An invalid request was received.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    ErrorUnauthenticatedResponse:
      description: "Access denied: Missing or invalid credentials"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    ErrorForbiddenResponse:
      description: "Access denied: requesting user lacks a required permission."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    ErrorTooManyRequestsResponse:
      description: Too many requests have been sent in a given amount of time
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    ErrorGenericResponse:
      description: An error has occurred.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: The access_token value found in ~/.decodable/auth after logging in with the Decodable CLI
    oauth2:
      type: oauth2
      description: OAuth2 authentication
      flows:
        authorizationCode:
          authorizationUrl: https://auth.decodable.co/authorize?audience=https://api.decodable.co/
          tokenUrl: https://auth.decodable.co/oauth/token
          scopes:
            openid: OpenID default profile
            offline_access: Request scope for offline access
            profile: Request scope for profile
            read:connection: Read connections
            write:connection: Update connections
            activate:connection: Activate or deactivate a connection
            read:stream: Read streams
            write:stream: Update streams
            read:pipeline: Read pipelines
            write:pipeline: Update pipelines
            activate:pipeline: Activate or deactivate a pipeline
            write:preview: Create a preview