Create Connector

Store credentials for one provider account so its data can be synced.

POST /connectors

cURL

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-..."
    }
  }'

201

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

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-..."
    }
  }'

201

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

Related Resources

• 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

201

application/json

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"