Connectors - Overview

​

Endpoints

• 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: POST /connectors stores credentials for one provider account.
• Discover Resources: GET /connectors/{id}/discover lists what the credentials can reach.
• Configure Connector: POST /connectors/{id}/configure activates resources and starts the first sync.

• Get Connector Status: GET /connectors/{id}/status says whether the connector and each resource are working.
• List Connectors: GET /connectors lists your connectors and their sync state.
• Get Connector: GET /connectors/{id} reads one connector’s settings.
• List Connector Resources: GET /connectors/{id}/resources reads each resource’s settings.
• Sync Connector: POST /connectors/{id}/sync syncs now instead of waiting for the schedule.
• Pause Connector and Resume Connector: POST /connectors/{id}/pause and /resume turn scheduled syncs off and back on.

• Update Connector: PATCH /connectors/{id} changes the sync interval, connector-level instructions or credentials.
• Update Connector Resource: PATCH /connectors/{id}/resources/{resource_id} changes one resource’s instructions or access rule.
• Add Connector Resource: POST /connectors/{id}/resources adds one new resource.
• Delete Connector Resource: DELETE /connectors/{id}/resources/{resource_id} stops syncing a resource.
• 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.

​

Which endpoint changes what

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

​

Authentication

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

{
  "database": "acme_corp",
  "query": "deployment checklist",
  "metadata_filters": {
    "additional_metadata": {
      "connector_id": "{connector_id}"
    }
  }
}

​

Multiple connectors per provider

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