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

# REST API Source

The REST API Source Connector lets you ingest data from **any REST API** into Popsink pipelines by providing a declarative JSON configuration. It is the generic counterpart to the dedicated API connectors (Zendesk, Shopify, Pipedrive, …): if a SaaS platform doesn't have its own connector yet, you can usually integrate it in minutes with this one. The configuration follows the [dlt `rest_api_source` schema](https://dlthub.com/docs/dlt-ecosystem/verified-sources/rest_api), describing the API client (base URL, authentication, pagination) and the resources (endpoints) to ingest.

## Compatible versions

| | |
| - | - |
| **Any REST API** | HTTP/1.1 or HTTP/2 over TLS, JSON responses |
| **Authentication** | Bearer token, API key (header or query), HTTP basic, OAuth 2.0 client credentials |
| **Configuration schema** | dlt `rest_api_source`, dlt 1.24 |

<Note>The configuration follows the dlt `rest_api_source` schema. When Popsink upgrades dlt, existing configurations keep working — the schema is backwards compatible within the 1.x line.</Note>

## Key Features

* **Connect to any REST API:** base URL, authentication, pagination, and endpoints are all declared in a single JSON configuration.
* **Multiple auth styles:** bearer tokens, API keys (header or query), HTTP basic, and OAuth2 client credentials.
* **Incremental synchronization:** declare a cursor field per resource and only new or updated records are delivered on each run.
* **Scheduled ingestion:** flexible scheduling by minutes, hours, or days, with an immediate first run on creation.

## Configuration

| Field | Required | Description |
| - | - | - |
| **Configuration** | Yes | A JSON object following the dlt `rest_api_source` schema — see below |
| **Schedule** | Yes | Sync frequency — see [Scheduling](#scheduling) |

### Configuration structure

The configuration JSON has two main blocks:

* **`client`** — how to reach and authenticate against the API: `base_url`, `auth`, optional `paginator` and `headers`.
* **`resources`** — an array of endpoints to ingest. Each resource becomes a stream/table, with its `path`, a `data_selector` pointing at the records in the response, optional query `params`, and an optional `incremental` cursor.

### Example

Ingesting two resources from an API authenticated with a bearer token, with cursor-based incremental sync on `updated_at`:

```json theme={null}
{
  "client": {
    "base_url": "https://api.example.com/v1",
    "auth": {
      "type": "bearer",
      "token": "YOUR_API_TOKEN"
    },
    "paginator": {
      "type": "json_link",
      "next_url_path": "paging.next"
    }
  },
  "resources": [
    {
      "name": "customers",
      "endpoint": {
        "path": "customers",
        "data_selector": "data",
        "params": { "per_page": 100 },
        "incremental": {
          "cursor_path": "updated_at",
          "initial_value": "1970-01-01T00:00:00Z"
        }
      }
    },
    {
      "name": "invoices",
      "endpoint": {
        "path": "invoices",
        "data_selector": "data"
      }
    }
  ]
}
```

Refer to the [dlt REST API source documentation](https://dlthub.com/docs/dlt-ecosystem/verified-sources/rest_api) for the full schema, including all supported authentication types and paginators.

## Scheduling

API source connectors run on a schedule rather than streaming continuously. A first run is always triggered immediately after the connector is created; subsequent runs depend on the selected mode:

| Mode | Behavior | Example |
| - | - | - |
| **days** | Runs every N days at 00:00 UTC + offset (in minutes) | Offset 30 → every day at 00:30 UTC |
| **hours** | Runs every N hours at :00 + offset (in minutes) | Offset 15 → 00:15, 01:15, 02:15, … |
| **minutes** | Runs every N minutes, anchored on the connector creation time | Created 10:03, interval 10 → 10:13, 10:23, … |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.