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

acl_warning · string

ACLWarning explains, in the provider's own words, why this resource's permissions could not be captured. Capture fails OPEN, so the resource is readable by everyone while this is set; without surfacing it, that widening would be invisible to the person who turned RBAC on. Cleared automatically by the next successful capture.

acl_warning_at · string

ACLWarningAt is when this warning last CHANGED (RFC3339). An unchanged warning is not rewritten each cycle, so it reads as "open since".

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_floor · string

BackfillFloor is the fixed oldest boundary the historical crawl is working towards, stamped once at configure time as now-lookback_days.

It exists because the floor used to be recomputed per chunk from the workflow's own clock, which made it a moving target: every hour the crawl was delayed, the boundary advanced an hour with it. A connector paused mid-backfill (PRO-1762) makes that trivially reachable — pause for longer than the crawl has left and it resumes, finds backfill_oldest already at or past the recomputed floor, declares itself complete and clears the marker. The remaining history is never fetched and nothing reports it missing. Anchoring the boundary is what makes "backfill 30 days" mean 30 days from when it was asked for, however long the crawl takes.

Empty on rows configured before this field existed; the workflow falls back to the old now-relative computation for those, so their behaviour is unchanged rather than silently altered by a deploy.

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 }

page_acl_warning · string

PageACLWarning is the same signal for SOURCE-level failures inside this resource: individual pages whose own restrictions could not be resolved and were therefore opened (Confluence, PRO-1684).

A SEPARATE field from ACLWarning on purpose. The two are written by different steps at different points in a sync, and ACLWarning is CLEARED whenever resource capture succeeds. Sharing one field would let a healthy space wipe a live page warning every cycle, leaving a window in which the dashboard reports no problems while pages are still open — a false all-clear on an access-control surface, which is worse than no surface.

page_acl_warning_at · string

PageACLWarningAt is when PageACLWarning last CHANGED (RFC3339).

page_acl_warning_run · string

PageACLWarningRun is the drain run that last observed a page failing open here. It is what makes the warning self-clearing: the drain settles each resource at the END of a cycle, and a stored run that is not the current one means that whole cycle passed with nothing failing, so the warning is withdrawn. Durable on purpose — the alternative was remembering it in the worker, which a restart loses and which has no moment that means "all pages have now been judged".

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.