> ## Documentation Index
> Fetch the complete documentation index at: https://www.integrate.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ELT/CDC: REST API

> Manage Integrate.io ELT & CDC pipelines programmatically with the REST API: bearer API keys, YAML or JSON definitions, lifecycle endpoints.

## Overview

The 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.

See the **API Reference** tab for the full request and response reference for every endpoint.

## Base URL

All endpoints live under:

```
/api/public/v1
```

## Authentication

Requests are authenticated with a bearer API key:

```http theme={null}
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.

<Steps>
  <Step>
    Go to **Settings** > **API Keys**.
  </Step>

  <Step>
    Click **Create API key**, give the key a human-readable name (for example, `terraform-prod` or `ci-pipeline`), and optionally set an expiry.
  </Step>

  <Step>
    Copy the key value from the confirmation dialog. The full value is not shown again.
  </Step>
</Steps>

### 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.

## 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

```yaml theme={null}
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

| Field                       | Required | Description                                               |
| --------------------------- | -------- | --------------------------------------------------------- |
| `definition_version`        | Yes      | Contract version. Currently `1`.                          |
| `name`                      | Yes      | Pipeline name.                                            |
| `source.connection.id`      | Yes      | Existing source connection ID.                            |
| `destination.connection.id` | Yes      | Existing destination connection ID.                       |
| `sync`                      | Yes      | Sync schedule. See below.                                 |
| `tables`                    | Yes      | List of tables to replicate.                              |
| `transformations`           | No       | Field-level transforms applied to records.                |
| `hooks`                     | No       | Existing 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.

```yaml theme={null}
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):

```yaml theme={null}
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`.

```yaml theme={null}
transformations:
  - type: rename_fields
    table: public.orders
    config:
      mapping:
        order_id: id
```

### Hooks

Attach existing notification hooks (created in **Settings** > **Hooks**) to pipeline events:

```yaml theme={null}
hooks:
  - id: 9
    events:
      - pipeline_failed
      - pipeline_stopped
```

## Errors

| Status | Meaning                                                                                                                                                                          |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | The definition parsed but failed validation (for example, conflicting `include` and `exclude`, or an unknown transformation type). The response body contains 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 it belongs to another account. Unknown IDs and other-account IDs both return `404` to prevent enumeration.                                       |
| `422`  | The request body contains unknown keys or has the wrong shape.                                                                                                                   |

## See also

* [Pipeline definition import and export](/cdc/pipeline-definition-import-export) for the dashboard equivalent.
* [Hooks](/cdc/hooks) for setting up the notification hooks referenced by `hooks[].id`.