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": {
      "api_token": "xoxp-..."
    }
  }'

{
  "connector_id": "{connector_id}",
  "provider": "slack",
  "name": "acme-engineering",
  "tenant_id": "acme_corp",
  "sub_tenant_id": "engineering",
  "provider_account_scope": "T12345ACME",
  "status": "active",
  "next_sync_at": "2026-06-01T13:00:00Z",
  "sync_interval_seconds": 3600
}

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": {
      "api_token": "xoxp-..."
    }
  }'

{
  "connector_id": "{connector_id}",
  "provider": "slack",
  "name": "acme-engineering",
  "tenant_id": "acme_corp",
  "sub_tenant_id": "engineering",
  "provider_account_scope": "T12345ACME",
  "status": "active",
  "next_sync_at": "2026-06-01T13:00:00Z",
  "sync_interval_seconds": 3600
}

Creates a connector and stores credentials for a single provider account. After creation, call Discover to see available resources, then Configure to activate them.

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": {
      "api_token": "xoxp-..."
    }
  }'

Request body

Name	Description
	Provider to connect. One of `slack`, `github`, `linear`, `notion`, `gmail`.
	Human-readable label for this connector.
	Which database receives the synced data. (deprecated alias: `tenant_id`)
	Default collection partition for synced objects. Individual resources can override this. (deprecated alias: `sub_tenant_id`; default: `""`)
	Identifier for the external account (e.g. Slack workspace ID, GitHub org name). Used in deduplication - must be distinct across connectors for the same provider.
	Provider-specific credentials. Typically `{ "api_token": "..." }` or `{ "access_token": "..." }`.

{
  "connector_id": "{connector_id}",
  "provider": "slack",
  "name": "acme-engineering",
  "tenant_id": "acme_corp",
  "sub_tenant_id": "engineering",
  "provider_account_scope": "T12345ACME",
  "status": "active",
  "next_sync_at": "2026-06-01T13:00:00Z",
  "sync_interval_seconds": 3600
}

Next: Discover Resources - inspect what’s available before activating
Next: Configure Connector - activate resources for sync
Teardown: Delete Connector
Read more: 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 (typically {"api_token": "..."} or {"access_token": "..."}).

Show child attributes

Example:

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

database

string

Database/Collection are the canonical v2 names; TenantID/SubTenantID are their deprecated aliases, reconciled by the TenantAliases middleware before binding so TenantID is always populated. Neither is marked binding:required (mirroring TenantCreateRequest): a caller may send either spelling, and the tenant scope is validated downstream by resolveTenant. Requiring tenant_id here would force the generated SDK to demand the deprecated field.

Example:

"acme_corp"

deployment_id

string

Internal deployment context for this connector.

Example:

"deploy_1234"

name

string

Human-readable label for this connector.

Example:

"general"

plan

string

Subscription plan this connector runs under.

Example:

"pro"

provider_account_scope

string

Identifier for the external account (e.g. Slack workspace ID, GitHub org name). Must be distinct across connectors for the same provider.

Example:

"T12345ACME"

sub_tenant_id

string

deprecated

deprecated: use collection

Example:

"sub_tenant_4567"

sync_engine

string

SyncEngine selects the sync pipeline: "classic" (default) or "moveit".

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

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. Canonical name; mirrors the deprecated sub_tenant_id alias.

Example:

"team_docs"

connector_id

string

Connector this resource belongs to.

Example:

"conn_abc123"

credential_ref

string

Internal reference to the stored credential record.

Example:

"cred_1a2b3c"

database

string

Database/Collection are the canonical v2 names for the deprecated tenant_id/sub_tenant_id wire fields. They mirror the same values so a v2 client sees the canonical names on responses while a legacy client keeps reading tenant_id/sub_tenant_id. Not persisted (dynamodbav:"-"): the store builds items from tenant_id/sub_tenant_id and mirrors these on load. They are populated at every construction point (toConnector, connectorFromItem) rather than via MarshalJSON so Temporal's JSON data converter round-trips Connector activity inputs without spuriously populating them.

Example:

"acme_corp"

deployment_id

string

Internal deployment context for this connector.

Example:

"deploy_1234"

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"

name

string

Human-readable label for this connector.

Example:

"general"

needs_reauth

boolean

NeedsReauth is set by MOVEIT's OAuth refresh sweep when the provider has rejected the connector's refresh token (invalid_grant — expired, revoked, or, for a provider with single-use tokens, already spent).

It is deliberately distinct from LastError, which records a sync failure. This is the one failure class no amount of retrying resolves: the stored grant is gone and only the tenant can mint a new one. Surfacing it as its own field is what lets a client show "reconnect" instead of a generic "sync failed", and the sweep clears it automatically on the next successful rotation, so a client can trust the absence of the flag as much as its presence.

Only ever set on OAuth-bundle connectors. A connector authenticated with a static token or with client credentials (X posts: see the client_id / client_secret inputs on tap-twitter) has no refresh token and therefore cannot reach this state at all — which is the reason to prefer that shape where a provider offers it.

Example:

true

needs_reauth_at

string

needs_reauth_reason

string

next_sync_at

string

RFC3339 timestamp when the next scheduled sync will run.

Example:

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

org_id

string

Organization that owns this resource.

Example:

"org_1a2b3c"

plan

string

Subscription plan this connector runs under.

Example:

"pro"

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). Must be distinct across connectors for the same provider.

Example:

"T12345ACME"

status

string

Lifecycle status of the connector (e.g. active, paused, error).

Example:

"completed"

sub_tenant_id

string

deprecated

Default collection partition for synced objects. Deprecated — use collection.

Example:

"sub_tenant_4567"

sync_engine

string

SyncEngine is "classic" (default, empty treated as classic) or "moveit". See the SyncEngine* constants; the scheduler branches on it.

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

Current sync operation state (e.g. idle, running).

Example:

"idle"

tenant_id

string

deprecated

Database that receives synced data. Deprecated — use database.

Example:

"tenant_1234"

user_id

string

User that created or owns this resource.

Example:

"user_alex"

API Documentation

Databases

Context

Query

Connectors

Webhooks

Miscellaneous

Request body

Authorizations

Body

Response

​Request body

​Related Resources

Authorizations

Body

Response

Request body

Related Resources