> ## Documentation Index
> Fetch the complete documentation index at: https://cortex-e852fafe-auto-update-openapi-6a9e3873a7492d091ac8c1f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Add Connector Resource
> Add a single resource to a connector.
export const Field = ({name, type, required, recommended}) => {
const label = required ? 'required' : recommended ? 'recommended' : null;
const typeLabel = typeof type === 'string' ? type : null;
const ariaParts = [name, typeLabel && `${typeLabel}`, label].filter(Boolean);
return
{name}
{required && *}
{recommended && ●}
{type && {type}}
{label &&
{label}
}
;
};
Adds a single resource without going through the full [configure](/api-reference/v2/endpoint/configure-connector) flow. Use [Configure Connector](/api-reference/v2/endpoint/configure-connector) instead when activating multiple resources or setting `metadata` / `lookback_days`.
```bash cURL theme={null}
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. |
```json 201 theme={null}
{
"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](/api-reference/v2/endpoint/connector-resources) - view all resources and sync state
* [Delete Connector Resource](/api-reference/v2/endpoint/delete-connector-resource) - remove a resource
* [Configure Connector](/api-reference/v2/endpoint/configure-connector) - add multiple resources with metadata and lookback settings
## OpenAPI
````yaml api-reference/v2/openapi.json POST /connectors/{id}/resources
openapi: 3.1.0
info:
contact:
email: support@hydradb.com
name: HydraDB Support
description: >-
HydraDB Application API — knowledge ingestion, search, and memory
management.
license:
name: Proprietary
title: HydraDB Application API
version: 0.1.0
servers:
- description: Production server
url: https://api.hydradb.com
security: []
externalDocs:
description: ''
url: ''
paths:
/connectors/{id}/resources:
post:
tags:
- connectors
summary: Create a connector resource
description: Add a resource mapping to a connector.
parameters:
- description: Connector ID
in: path
name: id
required: true
schema:
example: HydraDoc1234
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/handler.resourceCreateReq'
description: Resource configuration
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/connectors.Resource'
description: Created
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/handler.ErrorResponse'
description: Bad Request
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/handler.ErrorResponse'
description: Not Found
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/handler.ErrorResponse'
description: Internal Server Error
security:
- BearerAuth: []
components:
schemas:
handler.resourceCreateReq:
properties:
acl:
description: |-
ACL restricts every object synced from this resource to the listed
principals (see resourceMapping.ACL). Omitted means unrestricted.
items:
type: string
type: array
uniqueItems: false
additional_metadata:
additionalProperties: {}
description: >-
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.
example:
author: ada
doc_version: 3
type: object
collection_override:
type: string
custom_instructions:
description: >-
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.
type: string
database_override:
type: string
display_name:
description: Human-readable name for this resource.
example: general
type: string
filters:
additionalProperties: {}
description: >-
Provider-specific filters applied during sync (e.g.
`{"lookback_days": 30}`).
example:
channel: general
type: object
metadata:
additionalProperties: {}
description: >-
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.
example:
department: finance
priority: 7
type: object
provider_metadata:
additionalProperties: {}
description: Additional provider-supplied metadata for this resource.
example:
workspace_id: T12345ACME
type: object
resource_id:
description: Resource identifier from the Discover endpoint.
example: C0123456789
type: string
resource_type:
description: >-
Type of resource within the provider (e.g. `channel`, `repo`,
`linear_team`).
example: channel
type: string
sub_tenant_id_override:
deprecated: true
description: 'deprecated: use collection_override'
type: string
x-deprecated: 'true'
tenant_id_override:
deprecated: true
description: |-
DatabaseOverride/CollectionOverride are the canonical v2 names;
TenantIDOverride/SubTenantIDOverride are their deprecated aliases.
type: string
x-deprecated: 'true'
required:
- resource_id
type: object
connectors.Resource:
properties:
acl:
description: >-
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.
items:
type: string
type: array
uniqueItems: false
acl_fingerprint:
description: >-
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).
type: string
acl_warning:
description: >-
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.
type: string
acl_warning_at:
description: >-
ACLWarningAt is when this warning last CHANGED (RFC3339). An
unchanged
warning is not rewritten each cycle, so it reads as "open since".
type: string
additional_metadata:
additionalProperties: {}
description: >-
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.
example:
author: ada
doc_version: 3
type: object
backfill_chunk_interval_seconds:
description: >-
BackfillChunkIntervalSeconds is the pacing interval persisted at
configure
time so the scheduler can thread it into each chunk's workflow
input.
example: 86400
type: integer
backfill_floor:
description: >-
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.
type: string
backfill_next_chunk_at:
description: >-
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.
type: string
backfill_oldest:
description: >-
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'
type: string
backfill_status:
description: >-
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.
type: string
collection_override:
description: >-
Routes this resource's synced objects into a specific collection,
overriding the connector's. Canonical name; mirrors the deprecated
`sub_tenant_id_override` alias.
type: string
connector_id:
description: Connector this resource belongs to.
example: conn_abc123
type: string
custom_instructions:
description: >-
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.
type: string
database_override:
description: >-
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.
type: string
display_name:
description: Human-readable name for this resource.
example: general
type: string
filters:
additionalProperties: {}
description: >-
Provider-specific filters applied during sync (e.g.
`{"lookback_days": 30}`).
example:
channel: general
type: object
metadata:
additionalProperties: {}
description: >-
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.
example:
department: finance
priority: 7
type: object
page_acl_warning:
description: >-
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.
type: string
page_acl_warning_at:
description: PageACLWarningAt is when PageACLWarning last CHANGED (RFC3339).
type: string
page_acl_warning_run:
description: >-
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".
type: string
provider_cursor:
description: >-
Bookmark of the last synced position. Non-empty value confirms the
first sync has run.
example: '1699999999.000100'
type: string
provider_metadata:
additionalProperties: {}
description: Additional provider-supplied metadata for this resource.
example:
workspace_id: T12345ACME
type: object
resource_id:
description: Resource identifier from the Discover endpoint.
example: C0123456789
type: string
resource_type:
description: >-
Type of resource within the provider (e.g. `channel`, `repo`,
`linear_team`).
example: channel
type: string
status:
description: Current sync state of this resource (e.g. `active`, `paused`).
example: completed
type: string
sub_tenant_id_override:
deprecated: true
description: >-
Overrides the connector-level collection for objects synced from
this resource.
type: string
x-deprecated: 'true'
sync_blocked:
description: >-
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
type: boolean
sync_blocked_at:
description: SyncBlockedAt is when the resource was stopped (RFC3339).
type: string
sync_blocked_reason:
description: >-
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.
type: string
tenant_id_override:
deprecated: true
description: >-
Overrides the connector-level database for objects synced from this
resource. Deprecated.
type: string
x-deprecated: 'true'
type: object
handler.ErrorResponse:
properties:
data: {}
detail:
$ref: '#/components/schemas/handler.ErrorDetail'
description: Structured error detail with code, message, and deprecation hints.
example:
deprecated: true
deprecated_field: tenant_id
error_code: VALIDATION_ERROR
message: Request validation failed
preferred_field: database
error:
$ref: '#/components/schemas/handler.apiError'
description: Error message, empty string on success.
example:
code: DATABASE_NOT_FOUND
message: Database not found
meta:
$ref: '#/components/schemas/handler.ErrorMeta'
example:
latency_ms: 12.3
request_id: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d
success:
description: Whether the request succeeded.
example: true
type: boolean
type: object
handler.ErrorDetail:
properties:
deprecated:
description: Whether this response concerns a deprecated field or route.
example: true
type: boolean
deprecated_field:
description: The deprecated field name.
example: tenant_id
type: string
error_code:
description: Machine-readable error classification code.
example: VALIDATION_ERROR
type: string
message:
description: Human-readable description of the error.
example: Request validation failed
type: string
preferred_field:
description: The canonical replacement for the deprecated field.
example: database
type: string
success:
deprecated: true
description: >-
Deprecated for API clients: always false on this path, so it carries
no
information. To detect a failure read the HTTP status code; for what
went wrong read the envelope's error.code and error.message, and
meta.request_id when reporting it. The whole `detail` object is
deprecated legacy — tagging the field individually so SDK users see
it
on the property, not just the container (PRO-1208).
example: true
type: boolean
x-deprecated: 'true'
type: object
handler.apiError:
properties:
code:
description: Machine-readable error code (e.g. `DATABASE_NOT_FOUND`).
example: DATABASE_NOT_FOUND
type: string
message:
description: Human-readable description of the error.
example: Database not found
type: string
type: object
handler.ErrorMeta:
properties:
api_version:
type: string
latency_ms:
example: 12.3
type: number
request_id:
description: Unique identifier for this request, useful for support and tracing.
example: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d
type: string
type: object
securitySchemes:
BearerAuth:
bearerFormat: API key
description: 'API key sent as a Bearer token: "Bearer prefix.secret"'
scheme: bearer
type: http
````