> ## Documentation Index
> Fetch the complete documentation index at: https://cortex-e852fafe-auto-update-openapi-90ba87bf22729efa0749c85.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Connectors - Overview

> Quick reference for all connector endpoints, their lifecycle, and when to call each.

Connectors continuously sync external app data (Slack, GitHub, Linear, Notion, Gmail) into your knowledge store without manual ingestion.

## Endpoint references

| Endpoint                                                                                         | Method   | Purpose                                             |
| ------------------------------------------------------------------------------------------------ | -------- | --------------------------------------------------- |
| [`/connectors/providers`](/api-reference/v2/endpoint/list-connector-providers)                   | `GET`    | List all available connector providers              |
| [`/connectors/providers?id={provider}`](/api-reference/v2/endpoint/get-connector-provider)       | `GET`    | Get a provider's fields and credential requirements |
| [`/connectors`](/api-reference/v2/endpoint/create-connector)                                     | `POST`   | Create a new connector                              |
| [`/connectors`](/api-reference/v2/endpoint/list-connectors)                                      | `GET`    | List all connectors for the organization            |
| [`/connectors/:id`](/api-reference/v2/endpoint/get-connector)                                    | `GET`    | Get a single connector                              |
| [`/connectors/:id`](/api-reference/v2/endpoint/delete-connector)                                 | `DELETE` | Delete a connector                                  |
| [`/connectors/:id/discover`](/api-reference/v2/endpoint/discover-connector-resources)            | `GET`    | List available resources from the provider          |
| [`/connectors/:id/configure`](/api-reference/v2/endpoint/configure-connector)                    | `POST`   | Activate resources and set sync options             |
| [`/connectors/:id/sync`](/api-reference/v2/endpoint/sync-connector)                              | `POST`   | Trigger an on-demand sync                           |
| [`/connectors/:id/resources`](/api-reference/v2/endpoint/connector-resources)                    | `GET`    | List configured resources and their sync state      |
| [`/connectors/:id/resources`](/api-reference/v2/endpoint/add-connector-resource)                 | `POST`   | Add an individual resource row                      |
| [`/connectors/:id/resources/:resource_id`](/api-reference/v2/endpoint/delete-connector-resource) | `DELETE` | Remove a resource                                   |

## Typical call sequence

```text theme={null}
POST /connectors                     -> create connector with credentials
GET  /connectors/:id/discover        -> inspect what resources are available
POST /connectors/:id/configure       -> activate resources, set lookback_days
POST /connectors/:id/sync            -> trigger first sync (optional; scheduler runs hourly)
GET  /connectors/:id/resources       -> poll until provider_cursor is set (sync ran)
POST /query  (query_apps: true)      -> search synced data
DELETE /connectors/:id               -> teardown
```

## Authentication

All connector endpoints use your HydraDB API key:

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

## Key concepts

* **Connector**  -  An authenticated connection to one external provider account. A single connector manages all resources synced from that account.
* **Resource**  -  A syncable unit within a provider: a Slack channel, GitHub repo, Linear team/project, Notion database/page, or Gmail label. You activate resources individually via `/configure`.
* **Cursor**  -  A per-resource bookmark of the last synced position. Sync is incremental: only content newer than the cursor is fetched on each run.
* **provider\_account\_scope**  -  An identifier for the external account (e.g. Slack workspace ID, GitHub org). Used as part of the deduplication key  -  two connectors for the same provider must have distinct `provider_account_scope` values.

## Metadata on synced objects

Every object synced by a connector has two metadata layers.

### Tenant metadata (`metadata`)

Tenant metadata is the **schema-declared** layer. Fields are defined per tenant through `database_metadata_schema` and are indexed for fast, exact-match filtering. Use it for stable fields you filter on often, such as `department`, `region`, `status`, or `priority`.

HydraDB writes `provider` into tenant metadata for every synced object. You can add fields through `metadata` on each resource in [Configure Connector](/api-reference/v2/endpoint/configure-connector). User-supplied fields are merged first; `provider` takes precedence.

### Document metadata (`additional_metadata`)

Document metadata is the **free-form** layer and needs no schema. Connectors automatically populate provider-specific fields including connector ID, resource ID, provider account scope, and provider-native identifiers.

You can add fields through `additional_metadata` on each resource in [Configure Connector](/api-reference/v2/endpoint/configure-connector). User-supplied fields are merged first; provider-generated fields take precedence.

Use document metadata to scope a query to a connector, channel, repository, or inbox:

```json Querying with document metadata filter theme={null}
{
  "database": "acme_corp",
  "query": "deployment checklist",
  "query_apps": true,
  "metadata_filters": {
    "additional_metadata": {
      "connector_id": "{connector_id}"
    }
  }
}
```

| Filter target                         | Key in `additional_metadata` |
| ------------------------------------- | ---------------------------- |
| Specific connector                    | `connector_id`               |
| Specific channel / repository / label | `resource_id`                |
| Specific external account             | `provider_account_scope`     |

## Multiple connectors per provider

You can create more than one connector for the same provider, such as two Slack workspaces or separate personal and work Gmail accounts. Each connector has its own credentials, resources, and `provider_account_scope`.

Set a distinct `provider_account_scope` for each account. It is part of every object's deduplication key; without it, objects from two accounts of the same provider can collide.

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

```json theme={null}
{
  "resources": [
    { "resource_id": "C_GENERAL", "name": "general", "sub_tenant_id": "all-hands" },
    { "resource_id": "C_ENG", "name": "engineering", "sub_tenant_id": "engineering" }
  ]
}
```

## Provider contracts

Use [List Connector Providers](/api-reference/v2/endpoint/list-connector-providers) to see available providers, then [Get Connector Provider](/api-reference/v2/endpoint/get-connector-provider) to inspect a provider's indexed fields, query filters, and required credentials.