> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hydradb.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Configure Connector
> Activate resources for sync and set sync options.
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}
}
;
};
Activates one or more resources and sets sync options. This is the step between discovery and the first sync. You can call configure again at any time to add resources, change `sub_tenant_id`, or update metadata - the cursor is preserved on reconfigure.
```bash cURL theme={"dark"}
curl -X POST 'https://api.hydradb.com/connectors/{connector_id}/configure' \
-H "Authorization: Bearer $HYDRA_DB_API_KEY" \
-H "API-Version: 2" \
-H "Content-Type: application/json" \
-d '{
"lookback_days": 30,
"resources": [
{
"resource_id": "{resource_id}",
"resource_type": "channel",
"name": "general",
"sub_tenant_id": "all-hands",
"metadata": { "department": "all-hands" },
"additional_metadata": { "internal_label": "general-slack" }
},
{
"resource_id": "{resource_id_2}",
"resource_type": "channel",
"name": "engineering",
"sub_tenant_id": "engineering",
"metadata": { "department": "engineering" }
}
]
}'
```
## Path parameters
| Name | Description |
| ---- | ---------------------------------------------- |
| `id` | Connector UUID returned by `POST /connectors`. |
## Request body
| Name | Description |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| | Resources to activate. Each item corresponds to one entry from [Discover](/api-reference/v2/endpoint/discover-connector-resources). |
| | How far back the first sync fetches historical data. Only applies to the initial sync - subsequent syncs are incremental from the last cursor. (default: `30`) |
### Resource item fields
| Name | Description |
| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| | Resource identifier from `GET /connectors/:id/discover`. |
| | Resource type from `GET /connectors/:id/discover` (e.g. `channel`, `repo`, `linear_team`). |
| | Display name for this resource. |
| | Routes synced objects from this resource into a specific sub-tenant partition. Overrides the connector-level `sub_tenant_id`. |
| | Key-value pairs merged into tenant metadata on every synced object from this resource. Undeclared keys are accepted and stored, but only keys declared in `database_metadata_schema` are indexed for filtering. |
| | Key-value pairs merged into document metadata on every synced object from this resource. Free-form, no schema required. |
See [Metadata on synced objects](/essentials/v2/connectors#metadata-on-synced-objects) for how these merge with system-generated fields.
```json 200 theme={"dark"}
{
"backfill": false,
"configured": 2,
"connector_id": "{connector_id}"
}
```
`configured` is the count of resources successfully activated.
## Related Resources
* **Next:** [Sync Connector](/api-reference/v2/endpoint/sync-connector) - trigger an on-demand sync (the scheduler also runs hourly automatically)
* **Next:** [Connector Resources](/api-reference/v2/endpoint/connector-resources) - poll `provider_cursor` to confirm sync ran
* [Discover Resources](/api-reference/v2/endpoint/discover-connector-resources) - find resource IDs before configuring
* [Connectors guide - Metadata](/essentials/v2/connectors#metadata-on-synced-objects)
## OpenAPI
````yaml api-reference/v2/openapi.json POST /connectors/{id}/configure
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}/configure:
post:
tags:
- connectors
summary: Configure connector resources
description: >-
Save the selected resources for a connector and trigger initial
sync/backfill.
parameters:
- description: Connector ID
in: path
name: id
required: true
schema:
example: HydraDoc1234
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/handler.configureReq'
description: Resource selection and sync options
required: true
responses:
'200':
content:
application/json:
schema:
additionalProperties: {}
type: object
description: OK
'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.configureReq:
properties:
backfill_chunk_interval_seconds:
description: Internal interval for async backfill paging.
example: 86400
type: integer
lookback_days:
description: >-
How far back the first sync fetches historical data. Only applies to
the initial sync — subsequent syncs are incremental from the last
cursor.
example: 30
type: integer
resources:
description: >-
Resources to activate for this connector. Each item corresponds to
one entry from the Discover endpoint.
example:
- additional_metadata:
author: ada
doc_version: 3
collection: team_docs
database: acme_corp
metadata:
department: finance
priority: 7
name: general
resource_id: C0123456789
resource_type: channel
items:
$ref: '#/components/schemas/handler.resourceMapping'
type: array
uniqueItems: false
required:
- resources
type: object
handler.ErrorResponse:
properties:
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
success: true
type: object
handler.resourceMapping:
properties:
additional_metadata:
additionalProperties: {}
description: >-
AdditionalMetadata is merged into the additional_metadata layer of
every
object synced from this resource. Provider-generated fields take
precedence.
example:
author: ada
doc_version: 3
type: object
collection:
description: >-
Collection is the canonical v2 name for the per-resource sub-tenant
override: routes synced objects from this resource into a specific
collection. Empty means the resource inherits the connector
collection.
SubTenantID is the deprecated alias for this field, reconciled by
Configure before toResource runs.
example: team_docs
type: string
database:
description: >-
Database is the canonical v2 name for the per-resource tenant
override:
routes synced objects from this resource into a specific database.
Empty means the resource inherits the connector database. TenantID
is the
deprecated alias for this field, reconciled by Configure before
toResource runs.
example: acme_corp
type: string
metadata:
additionalProperties: {}
description: >-
Metadata is merged into the tenant metadata layer of every object
synced
from this resource. System fields (connector_id, provider) take
precedence.
example:
department: finance
priority: 7
type: object
name:
description: Display name for this resource.
example: general
type: string
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:
deprecated: true
description: >-
Routes synced objects from this resource into a specific sub-tenant
partition. Overrides the connector-level sub_tenant_id. Deprecated:
use
collection.
example: sub_tenant_4567
type: string
x-deprecated: 'true'
tenant_id:
deprecated: true
description: >-
Optional per-resource tenant override (for "route specific resources
to
different tenants"). Empty means the resource inherits the connector
tenant. Deprecated: use database.
example: tenant_1234
type: string
x-deprecated: 'true'
required:
- resource_id
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:
description: Always false for error responses.
example: true
type: boolean
type: object
securitySchemes:
BearerAuth:
bearerFormat: API key
description: 'API key sent as a Bearer token: "Bearer prefix.secret"'
scheme: bearer
type: http
````