# Integration

> Sync data from Directus collections into a warehouse or database using the Directus Airbyte source connector.

Copy data from your Directus instance into a warehouse or database (BigQuery, Snowflake, Postgres, and more) using the Directus Airbyte source connector.

<callout icon="i-lucide-rocket">

**Quick Start**

1. **Import the connector**: Download `Airbyte.yaml` from [directus-labs/airbyte](https://github.com/directus-labs/airbyte) on GitHub and add it as a new source in Airbyte
2. **Configure the source**: Enter your API key, base URL, and collection name
3. **Test the connection**: Airbyte hits the `/files` endpoint to verify credentials
4. **Create a connection**: Pick your destination and enable only the streams you need

</callout>

## Before You Start

You'll need:

- A Directus project with the collections you want to sync
- An API token with read access to those collections (go to **Settings** > **Access Tokens**)
- An Airbyte account and access to add a new source connector

## Available Streams

The connector exposes five streams. Enable only the ones your pipeline needs.

<table>
<thead>
  <tr>
    <th>
      Stream
    </th>
    
    <th>
      Endpoint
    </th>
    
    <th>
      Typical use
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        collection_items
      </code>
    </td>
    
    <td>
      <code>
        /items/{collection}
      </code>
    </td>
    
    <td>
      Posts, products, pages, custom collections
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        files
      </code>
    </td>
    
    <td>
      <code>
        /files
      </code>
    </td>
    
    <td>
      File library assets
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        users
      </code>
    </td>
    
    <td>
      <code>
        /users
      </code>
    </td>
    
    <td>
      User directory (contains PII - only enable if needed)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        activity
      </code>
    </td>
    
    <td>
      <code>
        /activity
      </code>
    </td>
    
    <td>
      Audit log
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        collections_meta
      </code>
    </td>
    
    <td>
      <code>
        /collections
      </code>
    </td>
    
    <td>
      Collection schema metadata
    </td>
  </tr>
</tbody>
</table>

Connection tests use the `files` stream.

## Setup in Airbyte

1. Download the connector manifest (`Airbyte.yaml`) from [directus-labs/airbyte](https://github.com/directus-labs/airbyte) on GitHub and import it as a new source in Airbyte.
2. Enter the required settings (see below).
3. Click **Test connection** to verify your credentials.
4. Create a **connection**, choose a destination, and enable only the streams you need.
5. Set the sync mode per stream. **Full refresh** is typical for CMS snapshots. Airbyte incremental sync is separate from Directus filters.

## Required Settings

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Example
    </th>
    
    <th>
      Notes
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        API Key
      </strong>
    </td>
    
    <td>
      <code>
        your-token
      </code>
    </td>
    
    <td>
      <strong>
        Settings
      </strong>
      
       > <strong>
        Access Tokens
      </strong>
      
      . Needs read access on every stream you enable.
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Base URL
      </strong>
    </td>
    
    <td>
      <code>
        https://your-project.directus.app
      </code>
    </td>
    
    <td>
      No trailing slash.
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Collection Name
      </strong>
    </td>
    
    <td>
      <code>
        posts
      </code>
    </td>
    
    <td>
      Required even if you only sync <code>
        files
      </code>
      
      . Use any collection slug your token can read.
    </td>
  </tr>
</tbody>
</table>

**Collection Name** feeds the `collection_items` stream. If you don't want to sync collection items, disable that stream on the Airbyte connection after setup.

## Optional Query Controls

These map directly to [Directus query parameters](/guides/connect/query-parameters) and apply to every stream. Use them to filter, sort, and limit what gets synced.

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Query param
    </th>
    
    <th>
      Example
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        Fields
      </strong>
    </td>
    
    <td>
      <code>
        fields
      </code>
    </td>
    
    <td>
      <code>
        id,title,status
      </code>
      
       (or <code>
        *
      </code>
      
       for all fields, the default)
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Filter
      </strong>
    </td>
    
    <td>
      <code>
        filter
      </code>
    </td>
    
    <td>
      <code>
        {"status":{"_eq":"published"}}
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Sort
      </strong>
    </td>
    
    <td>
      <code>
        sort
      </code>
    </td>
    
    <td>
      <code>
        -date_created
      </code>
      
       or <code>
        title,-date_updated
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Search
      </strong>
    </td>
    
    <td>
      <code>
        search
      </code>
    </td>
    
    <td>
      Free-text search string
    </td>
  </tr>
</tbody>
</table>

### Filter Examples

Published items only:

```json
{"status":{"_eq":"published"}}
```

Activity creates only:

```json
{"action":{"_eq":"create"}}
```

Items updated after a specific date:

```json
{"date_updated":{"_gte":"2024-01-01T00:00:00.000Z"}}
```

Enter filter values as a JSON string in the source config.

### Fields Example

```text
id,title,status,date_updated
```

Relational fields use dot notation: `id,title,author.name`

## Start Date

When set, the connector adds a `filter[field][_gte]` parameter to limit results to data after the given date.

<table>
<thead>
  <tr>
    <th>
      Stream
    </th>
    
    <th>
      Field filtered
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        collection_items
      </code>
    </td>
    
    <td>
      <code>
        date_updated
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        files
      </code>
    </td>
    
    <td>
      <code>
        uploaded_on
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        activity
      </code>
    </td>
    
    <td>
      <code>
        timestamp
      </code>
    </td>
  </tr>
</tbody>
</table>

Use `YYYY-MM-DD` format (e.g. `2026-06-01`) or a full ISO datetime. The connector normalizes date-only values to UTC midnight.

**Start Date** does not apply to `users` or `collections_meta`. Use **Filter** for those.

<callout icon="material-symbols:info-outline">

The Directus admin UI may display a different date field for files than what the API filters on. The API uses `uploaded_on`. To filter on a different field, use the **Filter** option instead: `{"modified_on":{"_gte":"2026-06-01T00:00:00.000Z"}}`.

</callout>

## Permissions

Each stream requires read access on the corresponding Directus resource.

<table>
<thead>
  <tr>
    <th>
      Stream
    </th>
    
    <th>
      Required permission
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        collection_items
      </code>
    </td>
    
    <td>
      Read on your collection
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        files
      </code>
    </td>
    
    <td>
      Read files
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        users
      </code>
    </td>
    
    <td>
      Read users
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        activity
      </code>
    </td>
    
    <td>
      Read activity (often requires admin)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        collections_meta
      </code>
    </td>
    
    <td>
      Read collections
    </td>
  </tr>
</tbody>
</table>

If a stream returns a 403 error, fix the token's role permissions or disable that stream on the connection.

## Syncing Multiple Collections

The connector syncs one collection per source. To sync multiple collections, create one Airbyte source per collection with the same base URL and API key, but a different **Collection Name**.

## Learn More

- [Directus API reference](/api)
- [Directus filter rules](/guides/connect/filter-rules)
- [Airbyte docs](https://docs.airbyte.com/)