Skip to main content

​
Overview

The public 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 an API key

API keys are minted from the dashboard. Only account admins can create or revoke keys.
1
Go to Settings > API Keys.
2
Click Create API key, give the key a human-readable name (for example, terraform-prod or ci-pipeline), and optionally set an expiry.
3
Copy the key value from the confirmation dialog. The full value is not shown again.

​
Revoke an API 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.

​
Endpoints

​
List pipelines

GET /api/public/v1/pipelines?page=1&page_size=50
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. page_size defaults to 50 and is capped at 100.

​
Get pipeline metadata

GET /api/public/v1/pipelines/{id}
Returns the pipeline’s runtime metadata (observed state, status, last sync timestamps).

​
Get pipeline definition

GET /api/public/v1/pipelines/{id}/definition
Accept: application/yaml
Returns the pipeline’s declarative definition. Set Accept: application/yaml for YAML or Accept: application/json for JSON.

​
Create a pipeline

POST /api/public/v1/pipelines
Content-Type: application/yaml
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.

​
Replace a pipeline definition

PUT /api/public/v1/pipelines/{id}/definition
Content-Type: application/yaml
Reconciles the pipeline to match the supplied definition. The operation is idempotent: reapplying the same document is a no-op.

​
Validate a definition

POST /api/public/v1/pipelines/validate
POST /api/public/v1/pipelines/{id}/definition/validate
Runs the same checks as create and replace without persisting changes. Use the first form for a new pipeline and the second to dry-run a change to an existing one. A successful response is {"valid": true}.

​
Start a pipeline

POST /api/public/v1/pipelines/{id}/start
Deploys the pipeline.

​
Stop a pipeline

POST /api/public/v1/pipelines/{id}/stop
POST /api/public/v1/pipelines/{id}/stop?force=true
Stops or pauses the pipeline. force=true skips the graceful-stop checks.

​
Archive a pipeline

DELETE /api/public/v1/pipelines/{id}
Archives the pipeline. If the pipeline is deployed, it is stopped and torn down first.

​
Pipeline definition document

The definition is a stable, customer-facing projection of the internal pipeline. It omits credentials, state backend configuration, region orchestration, and other internal fields. Both YAML and JSON map to the same schema, and unknown keys are rejected.

​
Minimal example

definition_version: 1
name: orders-to-snowflake
source:
  connection:
    id: 42
destination:
  connection:
    id: 17
sync:
  frequency: 5
  auto_sync_new_tables: false
tables:
  - name: public.orders
  - name: public.customers
    columns:
      exclude:
        - ssn

​
Top-level fields

FieldRequiredDescription
definition_versionYesContract version. Currently 1.
nameYesPipeline name.
source.connection.idYesExisting source connection ID.
destination.connection.idYesExisting destination connection ID.
syncYesSync schedule. See below.
tablesYesList of tables to replicate.
transformationsNoField-level transforms applied to records.
hooksNoExisting notification hooks to attach to pipeline events.

​
Sync schedule

Provide either frequency (which sets both source and destination) or both source_frequency and destination_frequency. Values are in minutes. 
sync:
  source_frequency: 5
  destination_frequency: 15
  auto_sync_new_tables: true

​
Table selection

Each table can optionally select columns with include or exclude (not both): 
tables:
  - name: public.orders
    append_only: false
    columns:
      include:
        - id
        - created_at
        - total_cents

​
Transformations

Supported type values: exclude_fields, rename_fields, toggle_case, find_and_replace, replace_in_field_name, history_mode. 
transformations:
  - type: rename_fields
    table: public.orders
    config:
      mapping:
        order_id: id

​
Hooks

Attach existing notification hooks (created in Settings > Hooks) to pipeline events: 
hooks:
  - id: 9
    events:
      - pipeline_failed
      - pipeline_stopped

​
Errors

StatusMeaning
400The definition parsed but failed validation (for example, conflicting include and exclude, or an unknown transformation type). The response body contains the failing field.
401Missing or invalid API key.
403The caller lacks admin privileges for key management.
404The pipeline does not exist, or it belongs to another account. Unknown IDs and other-account IDs both return 404 to prevent enumeration.
422The request body contains unknown keys or has the wrong shape.

​
See also

Last modified on June 15, 2026