openapi: 3.0.3
info:
  title: Integrate.io ELT & CDC REST API
  description: >
    The Integrate.io ELT & CDC REST API lets you list, create, update, start,
    stop, and archive

    ELT & CDC pipelines from outside the dashboard. Pipelines are described by a
    declarative

    definition document (YAML or JSON), so the same configuration can be
    version-controlled,

    reviewed, and reapplied across environments.


    ## Base URL

    All endpoints live under `/api/public/v1`.


    ## Authentication

    Requests are authenticated with a bearer API key:

    ```

    Authorization: Bearer fdk_<your-key>

    ```

    Every Integrate.io API key is prefixed with `fdk_`. The full key value is
    shown only once at

    creation time. Store it in a secret manager. If a key is lost or leaked,
    revoke it and mint a

    new one.


    **Create a key:** in the dashboard, go to **Settings > API Keys**, click
    **Create API key**,

    give it a name (for example `terraform-prod`), and optionally set an expiry.
    Copy the value from

    the confirmation dialog; it is not shown again. Only account admins can
    create or revoke keys.


    **Revoke a key:** from **Settings > API Keys**, open the action menu next to
    a key and choose

    **Revoke**. Revoked keys stop authenticating immediately and cannot be
    reactivated.


    ## Pipeline definition document

    Create, replace, and validate requests take a declarative definition
    document. For the full

    schema, supported transformation types, and examples, see

    [Pipeline definition import and
    export](/cdc/pipeline-definition-import-export#pipeline-definition-document).


    ## Errors

    Each endpoint documents its own responses. In general: `400` a definition
    failed validation

    (the body names the failing field), `401` missing or invalid API key, `403`
    the caller lacks

    admin privileges for key management, `404` the pipeline does not exist or
    belongs to another

    account (both return `404` to prevent enumeration), and `422` the request
    body has unknown keys

    or the wrong shape.
  version: '1.0'
  contact:
    name: Integrate.io Support
    url: https://www.integrate.io
servers:
  - url: https://{host}/api/public/v1
    variables:
      host:
        default: console.flydata.app
        description: >-
          API host. Confirm with the Integrate.io team; the API may instead be
          served from a dedicated host such as api.flydata.app. The public API
          lives under the /api/public/v1 base path.
tags:
  - name: Pipelines
    description: Manage ELT & CDC pipelines and their definitions.
security:
  - bearerAuth: []
paths:
  /pipelines:
    get:
      operationId: listPipelines
      tags:
        - Pipelines
      summary: List pipelines
      description: >-
        Returns the caller's pipelines as runtime metadata summaries, newest
        first. The response carries a `pagination` block. Page until `data` is
        short or empty rather than relying on a total count.
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: page_size
          in: query
          description: Defaults to 50, capped at 100.
          schema:
            type: integer
            default: 50
            maximum: 100
      responses:
        '200':
          description: A page of pipeline metadata.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PipelineMetadata'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createPipeline
      tags:
        - Pipelines
      summary: Create a pipeline
      description: >-
        Creates a pipeline from a definition document in the request body. The
        response is the new pipeline's metadata, including its `id`. Fetch the
        full definition from `GET /pipelines/{id}/definition` afterwards.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PipelineDefinition'
          application/yaml:
            schema:
              $ref: '#/components/schemas/PipelineDefinition'
      responses:
        '201':
          description: The created pipeline's metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelineMetadata'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /pipelines/validate:
    post:
      operationId: validateDefinition
      tags:
        - Pipelines
      summary: Validate a new pipeline definition
      description: >-
        Runs the same checks as create without persisting changes. Use this form
        for a new pipeline. A successful response is `{"valid": true}`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PipelineDefinition'
          application/yaml:
            schema:
              $ref: '#/components/schemas/PipelineDefinition'
      responses:
        '200':
          description: Validation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResult'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /pipelines/{id}:
    parameters:
      - $ref: '#/components/parameters/PipelineId'
    get:
      operationId: getPipeline
      tags:
        - Pipelines
      summary: Get pipeline metadata
      description: >-
        Returns the pipeline's runtime metadata (observed state, status, last
        sync timestamps).
      responses:
        '200':
          description: The pipeline's metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelineMetadata'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: archivePipeline
      tags:
        - Pipelines
      summary: Archive a pipeline
      description: >-
        Archives the pipeline. If the pipeline is deployed, it is stopped and
        torn down first.
      responses:
        '200':
          description: The pipeline was archived.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /pipelines/{id}/definition:
    parameters:
      - $ref: '#/components/parameters/PipelineId'
    get:
      operationId: getPipelineDefinition
      tags:
        - Pipelines
      summary: Get pipeline definition
      description: >-
        Returns the pipeline's declarative definition. Set `Accept:
        application/yaml` for YAML or `Accept: application/json` for JSON.
      responses:
        '200':
          description: The pipeline definition document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelineDefinition'
            application/yaml:
              schema:
                $ref: '#/components/schemas/PipelineDefinition'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: replacePipelineDefinition
      tags:
        - Pipelines
      summary: Replace a pipeline definition
      description: >-
        Reconciles the pipeline to match the supplied definition. The operation
        is idempotent: reapplying the same document is a no-op.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PipelineDefinition'
          application/yaml:
            schema:
              $ref: '#/components/schemas/PipelineDefinition'
      responses:
        '200':
          description: The pipeline was reconciled to the supplied definition.
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /pipelines/{id}/definition/validate:
    parameters:
      - $ref: '#/components/parameters/PipelineId'
    post:
      operationId: validatePipelineDefinition
      tags:
        - Pipelines
      summary: Validate a change to an existing pipeline
      description: >-
        Runs the same checks as replace without persisting changes. Use this
        form to dry-run a change to an existing pipeline. A successful response
        is `{"valid": true}`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PipelineDefinition'
          application/yaml:
            schema:
              $ref: '#/components/schemas/PipelineDefinition'
      responses:
        '200':
          description: Validation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResult'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /pipelines/{id}/start:
    parameters:
      - $ref: '#/components/parameters/PipelineId'
    post:
      operationId: startPipeline
      tags:
        - Pipelines
      summary: Start a pipeline
      description: Deploys the pipeline.
      responses:
        '200':
          description: The pipeline was deployed.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /pipelines/{id}/stop:
    parameters:
      - $ref: '#/components/parameters/PipelineId'
    post:
      operationId: stopPipeline
      tags:
        - Pipelines
      summary: Stop a pipeline
      description: >-
        Stops or pauses the pipeline. `force=true` skips the graceful-stop
        checks.
      parameters:
        - name: force
          in: query
          description: Skip the graceful-stop checks.
          schema:
            type: boolean
      responses:
        '200':
          description: The pipeline was stopped.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer API key, prefixed with fdk_.
  parameters:
    PipelineId:
      name: id
      in: path
      required: true
      schema:
        type: integer
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: >-
        The pipeline does not exist, or it belongs to another account. Unknown
        IDs and other-account IDs both return 404 to prevent enumeration.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: >-
        The definition parsed but failed validation (for example, conflicting
        `include` and `exclude`, or an unknown transformation type). The
        response body identifies the failing field.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: The request body contains unknown keys or has the wrong shape.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
      additionalProperties: true
    Pagination:
      type: object
      properties:
        page:
          type: integer
        page_size:
          type: integer
    ValidationResult:
      type: object
      properties:
        valid:
          type: boolean
          example: true
    PipelineMetadata:
      type: object
      description: >-
        Runtime metadata for a pipeline. Exact fields are subject to
        confirmation with the Integrate.io team.
      properties:
        id:
          type: integer
        name:
          type: string
        status:
          type: string
      additionalProperties: true
    PipelineDefinition:
      type: object
      description: >-
        A stable, customer-facing projection of the pipeline. It omits
        credentials, state backend configuration, region orchestration, and
        other internal fields. Unknown keys are rejected.
      required:
        - definition_version
        - name
        - source
        - destination
        - sync
        - tables
      properties:
        definition_version:
          type: integer
          description: Contract version. Currently 1.
          example: 1
        name:
          type: string
          example: orders-to-snowflake
        source:
          $ref: '#/components/schemas/ConnectionRef'
        destination:
          $ref: '#/components/schemas/ConnectionRef'
        sync:
          $ref: '#/components/schemas/Sync'
        tables:
          type: array
          items:
            $ref: '#/components/schemas/Table'
        transformations:
          type: array
          description: Field-level transforms applied to records.
          items:
            $ref: '#/components/schemas/Transformation'
        hooks:
          type: array
          description: Existing notification hooks to attach to pipeline events.
          items:
            $ref: '#/components/schemas/Hook'
      additionalProperties: false
    ConnectionRef:
      type: object
      required:
        - connection
      properties:
        connection:
          type: object
          required:
            - id
          properties:
            id:
              type: integer
              description: Existing connection ID.
    Sync:
      type: object
      description: >-
        Provide either `frequency` (which sets both source and destination) or
        both `source_frequency` and `destination_frequency`. Values are in
        minutes.
      properties:
        frequency:
          type: integer
        source_frequency:
          type: integer
        destination_frequency:
          type: integer
        auto_sync_new_tables:
          type: boolean
    Table:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          example: public.orders
        append_only:
          type: boolean
        columns:
          type: object
          description: Select columns with `include` or `exclude` (not both).
          properties:
            include:
              type: array
              items:
                type: string
            exclude:
              type: array
              items:
                type: string
    Transformation:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - exclude_fields
            - rename_fields
            - toggle_case
            - find_and_replace
            - replace_in_field_name
            - history_mode
        table:
          type: string
        config:
          type: object
          additionalProperties: true
    Hook:
      type: object
      required:
        - id
      properties:
        id:
          type: integer
        events:
          type: array
          items:
            type: string
          example:
            - pipeline_failed
            - pipeline_stopped