Create Connector

curl -X POST 'https://api.hydradb.com/connectors' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "slack",
    "name": "acme-engineering",
    "database": "acme_corp",
    "collection": "engineering",
    "provider_account_scope": "T12345ACME",
    "credentials": {
      "access_token": "xoxp-..."
    }
  }'

{
  "connector_id": "{connector_id}",
  "provider": "slack",
  "name": "acme-engineering",
  "database": "acme_corp",
  "collection": "engineering",
  "tenant_id": "acme_corp",
  "sub_tenant_id": "engineering",
  "provider_account_scope": "T12345ACME",
  "lifecycle": "pending_setup",
  "sync_status": "idle",
  "sync_interval_seconds": 3600,
  "next_sync_at": "2026-06-01T12:05:00Z",
  "first_sync_at": "2026-06-01T12:05:00Z",
  "message": "Connector created. Configure resources to start syncing; the first scheduled sync runs in about 5 minutes."
}

POST

connectors

curl -X POST 'https://api.hydradb.com/connectors' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "slack",
    "name": "acme-engineering",
    "database": "acme_corp",
    "collection": "engineering",
    "provider_account_scope": "T12345ACME",
    "credentials": {
      "access_token": "xoxp-..."
    }
  }'

{
  "connector_id": "{connector_id}",
  "provider": "slack",
  "name": "acme-engineering",
  "database": "acme_corp",
  "collection": "engineering",
  "tenant_id": "acme_corp",
  "sub_tenant_id": "engineering",
  "provider_account_scope": "T12345ACME",
  "lifecycle": "pending_setup",
  "sync_status": "idle",
  "sync_interval_seconds": 3600,
  "next_sync_at": "2026-06-01T12:05:00Z",
  "first_sync_at": "2026-06-01T12:05:00Z",
  "message": "Connector created. Configure resources to start syncing; the first scheduled sync runs in about 5 minutes."
}

Creates a connector for one provider account. Nothing syncs yet: next, call Discover Resources to see what the credentials can reach, then Configure Connector to choose resources and start the first sync. provider is any provider from List Connector Providers. The shape of credentials depends on the provider: read it from credential_schema by calling that endpoint with ?id={provider}. Credentials that do not match the schema are rejected. Optional settings you can also pass here, and change later with Update Connector:

custom_instructions: guidance for how this connector’s documents are interpreted and indexed. See Custom Ingestion Instructions.
sync_interval_seconds: how often scheduled syncs run. Omit it for the provider default (one hour for most providers).

curl -X POST 'https://api.hydradb.com/connectors' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "slack",
    "name": "acme-engineering",
    "database": "acme_corp",
    "collection": "engineering",
    "provider_account_scope": "T12345ACME",
    "credentials": {
      "access_token": "xoxp-..."
    }
  }'

{
  "connector_id": "{connector_id}",
  "provider": "slack",
  "name": "acme-engineering",
  "database": "acme_corp",
  "collection": "engineering",
  "tenant_id": "acme_corp",
  "sub_tenant_id": "engineering",
  "provider_account_scope": "T12345ACME",
  "lifecycle": "pending_setup",
  "sync_status": "idle",
  "sync_interval_seconds": 3600,
  "next_sync_at": "2026-06-01T12:05:00Z",
  "first_sync_at": "2026-06-01T12:05:00Z",
  "message": "Connector created. Configure resources to start syncing; the first scheduled sync runs in about 5 minutes."
}

The response repeats database and collection under their deprecated names tenant_id and sub_tenant_id. Read the new names.

Errors

400: provider or database is missing, the provider is unknown, or a setting such as sync_interval_seconds is out of range.
402: your plan’s connector limit is reached.
403: the provider is not available to your workspace.
422: credentials does not match the provider’s credential_schema.

Next: Discover Resources: see what the credentials can reach
Next: Configure Connector: choose resources and start syncing
List Connector Providers: the credential schema for a provider
Connectors - Overview

Authorizations

Authorization

string

header

required

API key sent as a Bearer token: "Bearer prefix.secret"

Body

application/json

Connector configuration

provider

string

required

External provider being synced (e.g. slack, github, linear, notion, gmail).

Example:

"slack"

auth_type

string

Authentication method for the provider connection (e.g. api_token, oauth).

Example:

"api_token"

collection

string

Default collection partition for synced objects. Deprecated alias: sub_tenant_id.

Example:

"team_docs"

credentials

object

Provider-specific credentials. Their shape is the provider's credential_schema from GET /connectors/providers?id=<provider>, for example {"access_token": "..."}.

Show child attributes

Example:

{ "api_token": "xoxb-..." }

custom_instructions

string

Instructions that steer how this connector's synced documents are ingested and indexed. Up to 4000 characters; editable later.

database

string

Database that receives the synced data. Required; the deprecated alias tenant_id is also accepted.

Example:

"acme_corp"

name

string

Human-readable label for this connector.

Example:

"general"

provider_account_scope

string

Identifier for the external account (e.g. Slack workspace ID, GitHub org name). Set a distinct value per account when you connect several accounts of one provider, so their objects cannot collide.

Example:

"T12345ACME"

sub_tenant_id

string

deprecated

Deprecated: use collection.

Example:

"sub_tenant_4567"

sync_interval_seconds

integer

How frequently the scheduler triggers incremental syncs, in seconds. Bounded per provider; send 0 or omit to use the provider default. Change it later with PATCH /connectors/{id}.

Example:

3600

tenant_id

string

deprecated

Deprecated: use database.

Example:

"tenant_1234"

Response

Created

active_resource_count

integer

Number of active resources on this connector. Zero means none are configured yet, and lifecycle reads pending_setup.

Example:

1

auth_type

string

Authentication method for the provider connection (e.g. api_token, oauth).

Example:

"api_token"

collection

string

Default collection for synced data; a resource can override it. Formerly sub_tenant_id, which is still returned with the same value.

Example:

"team_docs"

connector_id

string

Unique identifier of the connector.

Example:

"conn_abc123"

custom_instructions

string

Instructions that steer how this connector's synced documents are ingested and indexed. Up to 4000 characters; changes apply from the next sync.

database

string

Database that receives the synced data. Formerly tenant_id, which is still returned with the same value.

Example:

"acme_corp"

documents_dispatched

integer

Running total of objects sent for ingestion. It shows data is moving, not the indexed count: updates count again and deletes are not subtracted.

Example:

1

first_data_dispatched_at

string

RFC3339 timestamp of the first sync that sent at least one object for ingestion. Empty until then.

first_sync_at

string

RFC3339 timestamp when the first scheduled sync runs.

last_attempted_sync_at

string

RFC3339 timestamp of the most recent sync attempt (successful or not).

Example:

"2026-07-02T17:00:00Z"

last_error

string

Error message from the most recent failed sync, empty string when no error.

Example:

""

last_successful_sync_at

string

RFC3339 timestamp of the last successful sync completion.

Example:

"2026-07-02T17:00:00Z"

lifecycle

string

Current state: pending_setup (no active resources), ingesting (first sync unfinished), syncing, active, paused, or reconnect (credentials rejected or connector blocked).

message

string

Human-readable note on when data will start to sync, safe to show to users as is.

Example:

"Success"

name

string

Human-readable label for this connector.

Example:

"general"

needs_reauth

boolean

True when the provider rejected the OAuth refresh token. Reconnect the account to resume syncing; clears on the next successful token refresh.

Example:

true

needs_reauth_at

string

RFC3339 timestamp when needs_reauth was set.

needs_reauth_reason

string

Why the provider rejected the OAuth grant, when needs_reauth is true.

next_sync_at

string

RFC3339 timestamp when the next scheduled sync will run.

Example:

"2026-07-02T18:00:00Z"

paused

boolean

True while the connector is paused. Scheduled and manual syncs are both refused until it is resumed; each resource then continues from where it stopped.

Example:

true

paused_at

string

RFC3339 timestamp when the connector was paused.

provider

string

External provider being synced (e.g. slack, github, linear, notion, gmail).

Example:

"slack"

provider_account_scope

string

Identifier for the external account (e.g. Slack workspace ID, GitHub org name). Set a distinct value per account when you connect several accounts of one provider, so their objects cannot collide.

Example:

"T12345ACME"

resources_pending_first_sync

integer

Number of active resources that have not completed their first successful sync. While above zero, lifecycle reads ingesting.

Example:

1

status

string

deprecated

Deprecated: always active. Read lifecycle for what the connector is doing.

Example:

"active"

sub_tenant_id

string

deprecated

Deprecated: use collection.

Example:

"sub_tenant_4567"

sync_blocked

boolean

True when a failure retrying cannot fix, such as rejected credentials, stopped scheduled syncs. Updating credentials or configuration clears it.

Example:

true

sync_blocked_at

string

RFC3339 timestamp when sync_blocked was set.

sync_blocked_reason

string

Error that blocked the connector, when sync_blocked is true. Up to 1000 characters.

sync_interval_seconds

integer

How frequently the scheduler triggers incremental syncs, in seconds. Bounded per provider; send 0 or omit to use the provider default. Change it later with PATCH /connectors/{id}.

Example:

3600

sync_status

string

syncing while a sync is running, otherwise idle.

Example:

"idle"

tenant_id

string

deprecated

Deprecated: use database.

Example:

"tenant_1234"

API Documentation

Databases

Context

Query

Connectors

Webhooks

Miscellaneous

Errors

Authorizations

Body

Response

​Errors

​Related Resources

Authorizations

Body

Response

Errors

Related Resources