Connectors

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`	`GET`	List all available connector providers
`/connectors/providers?id={provider}`	`GET`	Get a provider’s fields and credential requirements
`/connectors`	`POST`	Create a new connector
`/connectors`	`GET`	List all connectors for the organization
`/connectors/:id`	`GET`	Get a single connector
`/connectors/:id`	`DELETE`	Delete a connector
`/connectors/:id/discover`	`GET`	List available resources from the provider
`/connectors/:id/configure`	`POST`	Activate resources and set sync options
`/connectors/:id/sync`	`POST`	Trigger an on-demand sync
`/connectors/:id/resources`	`GET`	List configured resources and their sync state
`/connectors/:id/resources`	`POST`	Add an individual resource row
`/connectors/:id/resources/:resource_id`	`DELETE`	Remove a resource

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

All connector endpoints use your HydraDB API key:

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

Querying with document metadata filter

{
  "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:

{
  "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 to see available providers, then Get Connector Provider to inspect a provider’s indexed fields, query filters, and required credentials.

API Documentation

Databases

Context

Query

Webhooks

Miscellaneous

Connectors - Overview

Endpoint references

Typical call sequence

Authentication

Key concepts

Metadata on synced objects

Tenant metadata (`metadata`)

Document metadata (`additional_metadata`)

Multiple connectors per provider

Provider contracts

​Endpoint references

​Typical call sequence

​Authentication

​Key concepts

​Metadata on synced objects

​Tenant metadata (metadata)

​Document metadata (additional_metadata)

​Multiple connectors per provider

​Provider contracts

Endpoint references

Typical call sequence

Authentication

Key concepts

Metadata on synced objects

Tenant metadata (`metadata`)

Document metadata (`additional_metadata`)

Multiple connectors per provider

Provider contracts