Connectors - Overview

​

Endpoint references

​

Typical call sequence

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

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.