Add Connector Resource

Add a single resource to a connector.

POST /connectors/{id}/resources

cURL

curl -X POST 'https://api.hydradb.com/connectors/{id}/resources' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_id": "{resource_id}",
    "resource_type": "channel",
    "display_name": "general",
    "sub_tenant_id_override": "all-hands"
  }'

201

{
  "connector_id": "{connector_id}",
  "resource_id": "{resource_id}",
  "resource_type": "channel",
  "display_name": "general",
  "status": "active",
  "provider_cursor": "",
  "tenant_id_override": "",
  "sub_tenant_id_override": "all-hands",
  "provider_metadata": null,
  "filters": null
}

Adds a single resource without going through the full configure flow. Use Configure Connector instead when activating multiple resources or setting metadata / lookback_days.

cURL

curl -X POST 'https://api.hydradb.com/connectors/{id}/resources' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_id": "{resource_id}",
    "resource_type": "channel",
    "display_name": "general",
    "sub_tenant_id_override": "all-hands"
  }'

Path parameters

Name	Description
id	Connector UUID returned by POST /connectors.

Request body

Name	Description
	Resource identifier from GET /connectors/:id/discover.
	Resource type from GET /connectors/:id/discover.
	Human-readable name for this resource.
	Routes synced objects from this resource into a specific sub-tenant partition.

201

{
  "connector_id": "{connector_id}",
  "resource_id": "{resource_id}",
  "resource_type": "channel",
  "display_name": "general",
  "status": "active",
  "provider_cursor": "",
  "tenant_id_override": "",
  "sub_tenant_id_override": "all-hands",
  "provider_metadata": null,
  "filters": null
}

Related Resources

• List Connector Resources - view all resources and sync state
• Delete Connector Resource - remove a resource
• Configure Connector - add multiple resources with metadata and lookback settings

Authorizations

Authorization · string · header · required

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

Path Parameters

id · string · required

Connector ID

Example:

"HydraDoc1234"

Body

application/json

Resource configuration

resource_id · string · required

Resource identifier from the Discover endpoint.

Example:

"C0123456789"

acl · string[]

ACL restricts every object synced from this resource to the listed principals (see resourceMapping.ACL). Omitted means unrestricted.

additional_metadata · object

Key-value pairs merged into document metadata on every synced object from this resource. Capped at 1 KiB, measured on the compact JSON encoding of the whole map in UTF-8 bytes — keys, quotes, commas and braces count toward the budget. The cap is applied when synced objects are ingested, not to this request.

Show child attributes

Example:

{ "author": "ada", "doc_version": 3 }

collection_override · string

custom_instructions · string

CustomInstructions optionally steers how documents synced from this resource are ingested and indexed. When set it replaces the connector-level custom_instructions for this resource; empty inherits the connector's value. Max 4000 characters.

database_override · string

display_name · string

Human-readable name for this resource.

Example:

"general"

filters · object

Provider-specific filters applied during sync (e.g. {"lookback_days": 30}).

Show child attributes

Example:

{ "channel": "general" }

metadata · object

Key-value pairs merged into tenant metadata on every synced object from this resource. Capped at 16 KiB, measured on the compact JSON encoding of the whole map in UTF-8 bytes — keys, quotes, commas and braces count toward the budget. The cap is applied when synced objects are ingested, not to this request.

Show child attributes

Example:

{ "department": "finance", "priority": 7 }

provider_metadata · object

Additional provider-supplied metadata for this resource.

Show child attributes

Example:

{ "workspace_id": "T12345ACME" }

resource_type · string

Type of resource within the provider (e.g. channel, repo, linear_team).

Example:

"channel"

sub_tenant_id_override · string · deprecated

deprecated: use collection_override

tenant_id_override · string · deprecated

DatabaseOverride/CollectionOverride are the canonical v2 names; TenantIDOverride/SubTenantIDOverride are their deprecated aliases.

Response

201

application/json

Created

acl · string[]

ACL is the customer-declared access-control list stamped onto every object synced from this resource (PRO-1684; see internal/domain/acl). Stored in caller-supplied form and normalized at transform time. nil means no ACL, documents stay unrestricted. Provider-derived ACLs (Phase 2) take precedence over this when the provider supports them.

acl_fingerprint · string

ACLFingerprint is the stable identity of the ACL last APPLIED to this resource's already-indexed documents (PRO-1684). The sync compares the freshly-resolved provider ACL against it: equal means nothing to do, different means fan the new ACL out to existing documents. Empty means nothing has been applied yet (first capture-enabled sync).

additional_metadata · object

AdditionalMetadata is merged into the additional_metadata (document metadata) layer of every object synced from this resource. User-supplied keys are shallow-merged as the base; provider-generated fields are applied on top and always win on conflict.

Show child attributes

Example:

{ "author": "ada", "doc_version": 3 }

backfill_chunk_interval_seconds · integer

BackfillChunkIntervalSeconds is the pacing interval persisted at configure time so the scheduler can thread it into each chunk's workflow input.

Example:

86400

backfill_next_chunk_at · string

BackfillNextChunkAt is the RFC3339 time the next chunk becomes due. The backfill workflow processes one chunk then sets this to now+interval and exits; the connector scheduler starts the next chunk once it passes.

backfill_oldest · string

BackfillOldest is an RFC3339 timestamp marking the oldest boundary remaining for async historical backfill. Empty means backfill is complete or not needed.

Example:

"2026-06-01T00:00:00Z"

backfill_status · string

BackfillStatus gates the sparse ResourcesByBackfillNextChunkAt GSI: it is set to BackfillStatusActive while a historical backfill is in progress and removed when it completes, so only actively-backfilling resources appear in the scheduler's due query. Pacing between chunks is driven by that scheduler (see BackfillNextChunkAt), not by an in-workflow sleep.

collection_override · string

Routes this resource's synced objects into a specific collection, overriding the connector's. Canonical name; mirrors the deprecated sub_tenant_id_override alias.

connector_id · string

Connector this resource belongs to.

Example:

"conn_abc123"

custom_instructions · string

CustomInstructions is optional free-text ingestion guidance scoped to this resource. When set it replaces the connector-level custom_instructions for documents synced from this resource; empty means the resource inherits the connector's value. Max 4000 characters; changes apply from the next sync cycle.

database_override · string

DatabaseOverride/CollectionOverride are the canonical v2 names for the deprecated tenant_id_override/sub_tenant_id_override wire fields. Empty means the resource inherits the connector's database/collection, exactly as the deprecated fields do. Not persisted (dynamodbav:"-"): mirrored from the tenant_id_override/sub_tenant_id_override values at construction time.

display_name · string

Human-readable name for this resource.

Example:

"general"

filters · object

Provider-specific filters applied during sync (e.g. {"lookback_days": 30}).

Show child attributes

Example:

{ "channel": "general" }

metadata · object

Metadata is merged into the tenant metadata layer of every object synced from this resource. User-supplied keys are shallow-merged as the base; system defaults (connector_id, provider) are applied on top so they always win on conflict — user keys extend the map but cannot override system-set fields.

Show child attributes

Example:

{ "department": "finance", "priority": 7 }

provider_cursor · string

Bookmark of the last synced position. Non-empty value confirms the first sync has run.

Example:

"1699999999.000100"

provider_metadata · object

Additional provider-supplied metadata for this resource.

Show child attributes

Example:

{ "workspace_id": "T12345ACME" }

resource_id · string

Resource identifier from the Discover endpoint.

Example:

"C0123456789"

resource_type · string

Type of resource within the provider (e.g. channel, repo, linear_team).

Example:

"channel"

status · string

Current sync state of this resource (e.g. active, paused).

Example:

"completed"

sub_tenant_id_override · string · deprecated

Overrides the connector-level collection for objects synced from this resource.

sync_blocked · boolean

SyncBlocked marks a resource the provider will go on refusing — a table that was dropped, a channel this credential was never invited to.

Deliberately not a Status value. Status gates ListConnectorResources, which is what GET /connectors/{id}/status reads, so expressing this as a status would hide the resource from the one endpoint that explains why it stopped. The resource stays active and visible; this only takes it out of what gets synced.

Example:

true

sync_blocked_at · string

SyncBlockedAt is when the resource was stopped (RFC3339).

sync_blocked_reason · string

SyncBlockedReason is the provider's own explanation, carried forward from the health that triggered the block so it survives the next sync overwriting that health.

tenant_id_override · string · deprecated

Overrides the connector-level database for objects synced from this resource. Deprecated.