> ## Documentation Index
> Fetch the complete documentation index at: https://cortex-e852fafe-auto-update-openapi-90ba87bf22729efa0749c85.mintlify.site/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={null}
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 [Connectors - Overview](/api-reference/v2/endpoint/connectors-overview) for how these merge with system-generated fields.
```json 200 theme={null}
{
"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 - Overview](/api-reference/v2/endpoint/connectors-overview)
## 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:
$ref: '#/components/schemas/handler.configureResponse'
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
full_visibility_roles:
description: >-
FullVisibilityRoles names the HubSpot roles whose members can see
every
record (PRO-2036). Resolved to ids against the portal at configure
time
and stored on the account-wide resource row. A pointer so an omitted
field keeps the current setting while an explicit [] clears it.
items:
type: string
type: array
uniqueItems: false
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
table_configs:
description: >-
TableConfigs carries per-table replication settings for MOVEIT
connectors whose tap reads a `table_configs` credential input
(bigquery).
Configure merges them into the stored credential bundle before the
first
sync, so the mode chosen at selection time governs every sync from
the
start. Optional; rejected for non-MOVEIT engines.
items:
$ref: '#/components/schemas/handler.tableConfigEntry'
type: array
uniqueItems: false
required:
- resources
type: object
handler.configureResponse:
properties:
backfill:
example: true
type: boolean
configured:
example: 1
type: integer
connector_id:
description: Connector this resource belongs to.
example: conn_abc123
type: string
first_sync_at:
description: >-
FirstSyncAt/Message state the timing expectation: whether the first
sync is already running (configure triggers one) or when the
scheduled
one runs, so clients stop inventing their own copy (PRO-1565).
type: string
message:
description: Human-readable result message.
example: Success
type: string
meta:
$ref: '#/components/schemas/handler.configureResponseMeta'
warnings:
description: >-
Warnings names resources that were saved but produced nothing when
probed. They are valid — the user may know a table is empty and
expect it
to fill — so they are not rejected, but they are the case that is
otherwise indistinguishable from success at every layer, so they are
never saved silently either.
items:
type: string
type: array
uniqueItems: false
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.resourceMapping:
properties:
acl:
description: >-
ACL restricts every object synced from this resource to the listed
principals (emails, or prefixed principals, see the query-side
user_email parameter). Omitted means unrestricted. An explicitly
empty
list means private (visible only to unfiltered queries).
items:
type: string
type: array
uniqueItems: false
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
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:
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'
sync_mode:
description: >-
SyncMode is the per-resource update strategy for taps that support
one
(today: attio objects/lists). "rescan" (default) re-reads the full
set
every sync — the only way edits are seen on APIs with no updated_at.
"new_only" bounds each scan to the sync window and stops paging at
its
floor — cheap, and an explicit opt-in to not seeing edits until
webhooks land. Stored in the resource's filters and carried to the
tap
on every window.
enum:
- rescan
- new_only
type: string
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.tableConfigEntry:
properties:
change_history:
type: string
replication_key:
type: string
table:
type: string
type: object
handler.configureResponseMeta:
properties:
deprecation:
items:
$ref: '#/components/schemas/handler.deprecationNotice'
type: array
uniqueItems: false
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
handler.deprecationNotice:
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
deprecated_since:
description: API version when the field was deprecated.
example: 2.0.1
type: string
message:
description: Migration guidance message.
example: tenant_id is deprecated; use database instead.
type: string
preferred_field:
description: The canonical replacement for the deprecated field.
example: database
type: string
type: object
securitySchemes:
BearerAuth:
bearerFormat: API key
description: 'API key sent as a Bearer token: "Bearer prefix.secret"'
scheme: bearer
type: http
````