> ## Documentation Index
> Fetch the complete documentation index at: https://cortex-e852fafe-t3code-rewrite-docs-declutter.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Connectors - Overview

> Every connector endpoint, the order to call them in, and which one to use to change what.

Connectors keep data from an external app (Slack, GitHub, Google Drive, Supabase and more) synced into your database without manual ingestion. [List Connector Providers](/api-reference/v2/endpoint/list-connector-providers) returns every provider you can connect.

## Endpoints

The sidebar lists the endpoints you use to set a connector up and change it. The others are linked here.

Set up a connector:

* [List Connector Providers](/api-reference/v2/endpoint/list-connector-providers): `GET /connectors/providers` lists the providers you can connect. Add `?id={provider}` to describe one, including the credentials it needs.
* [Create Connector](/api-reference/v2/endpoint/create-connector): `POST /connectors` stores credentials for one provider account.
* [Discover Resources](/api-reference/v2/endpoint/discover-connector-resources): `GET /connectors/{id}/discover` lists what the credentials can reach.
* [Configure Connector](/api-reference/v2/endpoint/configure-connector): `POST /connectors/{id}/configure` activates resources and starts the first sync.

Check on it:

* [Get Connector Status](/api-reference/v2/endpoint/get-connector-status): `GET /connectors/{id}/status` says whether the connector and each resource are working.
* [List Connectors](/api-reference/v2/endpoint/list-connectors): `GET /connectors` lists your connectors and their sync state.
* [Get Connector](/api-reference/v2/endpoint/get-connector): `GET /connectors/{id}` reads one connector's settings.
* [List Connector Resources](/api-reference/v2/endpoint/connector-resources): `GET /connectors/{id}/resources` reads each resource's settings.
* [Sync Connector](/api-reference/v2/endpoint/sync-connector): `POST /connectors/{id}/sync` syncs now instead of waiting for the schedule.
* [Pause Connector](/api-reference/v2/endpoint/pause-connector) and [Resume Connector](/api-reference/v2/endpoint/resume-connector): `POST /connectors/{id}/pause` and `/resume` turn scheduled syncs off and back on.

Change it:

* [Update Connector](/api-reference/v2/endpoint/update-connector): `PATCH /connectors/{id}` changes the sync interval, connector-level instructions or credentials.
* [Update Connector Resource](/api-reference/v2/endpoint/update-connector-resource): `PATCH /connectors/{id}/resources/{resource_id}` changes one resource's instructions or access rule.
* [Add Connector Resource](/api-reference/v2/endpoint/add-connector-resource): `POST /connectors/{id}/resources` adds one new resource.
* [Delete Connector Resource](/api-reference/v2/endpoint/delete-connector-resource): `DELETE /connectors/{id}/resources/{resource_id}` stops syncing a resource.
* [Delete Connector](/api-reference/v2/endpoint/delete-connector): `DELETE /connectors/{id}` removes the connector.

## Typical call sequence

1. `POST /connectors` with the provider's credentials.
2. `GET /connectors/{id}/discover` to see which resources are available.
3. `POST /connectors/{id}/configure` with the resources to sync. This starts the first sync.
4. `GET /connectors/{id}/status` until `status` is `healthy` and `lifecycle` is `active`.
5. `POST /query` to search the synced data. `query_apps` defaults to `true`, so connector content is searched without setting it.

After that, syncs run every `sync_interval_seconds` (one hour by default). Call `POST /connectors/{id}/sync` only when you need data sooner.

## Which endpoint changes what

<Warning>
  To change a resource that is already configured, use `PATCH /connectors/{id}/resources/{resource_id}`. `POST /connectors/{id}/resources` on an existing `resource_id` replaces the whole resource: every field you leave out is cleared, and the resource syncs again from the beginning.
</Warning>

* Instructions or access rule on one resource: `PATCH /connectors/{id}/resources/{resource_id}`. Only the fields you send change.
* Instructions, sync interval or credentials for the whole connector: `PATCH /connectors/{id}`. Only the fields you send change.
* Name, type, database, collection or metadata of resources: `POST /connectors/{id}/configure`. Resources you leave out of the list are not touched. For each resource you list, send `name` and `resource_type` every time, because omitted values are cleared. Its sync position, instructions and access rule are kept.
* A brand new resource: `POST /connectors/{id}/configure` or `POST /connectors/{id}/resources`.

In paths, `{resource_id}` is the resource's id as returned by the Discover and List Resources endpoints, for example a Slack channel id or a Supabase `schema.table` name. URL-encode it when it contains spaces or other reserved characters.

## Authentication

All connector endpoints use your HydraDB API key:

```bash theme={"dark"}
Authorization: Bearer $HYDRA_DB_API_KEY
API-Version: 2
```

## Key concepts

* **Connector:** an authenticated connection to one external provider account. It owns every resource synced from that account.
* **Resource:** a syncable unit inside the account, such as a Slack channel, a GitHub repository, a Notion database or a Supabase table. You choose which resources to sync.
* **Cursor:** each resource's saved sync position. Syncs are incremental: each one fetches only what changed since the cursor.
* **provider\_account\_scope:** an identifier for the external account, such as a Slack workspace id. It is part of every synced object's deduplication key, so set a distinct value per account when you connect several accounts of one provider.

## Metadata on synced objects

Every object a connector syncs carries two metadata layers.

**Attributes (`metadata`)** are declared in your database's metadata schema and indexed for fast exact-match filtering. HydraDB always writes `connector_id` and `provider` here. Add your own fields per resource with `metadata` on [Configure Connector](/api-reference/v2/endpoint/configure-connector). The system fields win on conflict.

**Custom attributes (`additional_metadata`)** are free-form and need no schema. HydraDB always writes `connector_id` and `resource_id` here, plus provider-specific fields that [List Connector Providers](/api-reference/v2/endpoint/list-connector-providers) shows under `filterable_fields` when called with `?id={provider}`. Add your own per resource with `additional_metadata` on Configure. Provider-generated fields win on conflict.

To scope a query to one connector, filter on `connector_id`:

```json Querying with a custom attribute filter theme={"dark"}
{
  "database": "acme_corp",
  "query": "deployment checklist",
  "metadata_filters": {
    "additional_metadata": {
      "connector_id": "{connector_id}"
    }
  }
}
```

Filter on `resource_id` the same way to scope to one channel, repository or table.

## Multiple connectors per provider

You can create more than one connector for the same provider, such as two Slack workspaces. Each has its own credentials, resources and `provider_account_scope`. Give each a distinct `provider_account_scope`, or objects from the two accounts that share an external id can collide.

You can also route resources from one connector into different collections with [Configure Connector](/api-reference/v2/endpoint/configure-connector):

```json theme={"dark"}
{
  "resources": [
    { "resource_id": "C_GENERAL", "resource_type": "channel", "name": "general", "collection": "all-hands" },
    { "resource_id": "C_ENG", "resource_type": "channel", "name": "engineering", "collection": "engineering" }
  ]
}
```


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