Configure Connector

Choose which resources a connector syncs, and start the first sync.

POST /connectors/{id}/configure

cURL

curl -X POST 'https://api.hydradb.com/connectors/{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": "C0123456789",
        "resource_type": "channel",
        "name": "general",
        "collection": "all-hands",
        "metadata": { "department": "all-hands" },
        "additional_metadata": { "internal_label": "general-slack" }
      },
      {
        "resource_id": "C0987654321",
        "resource_type": "channel",
        "name": "incidents",
        "collection": "engineering",
        "custom_instructions": "These threads are incident retros. Extract root cause, impact and owner."
      }
    ]
  }'

200

{
  "connector_id": "{connector_id}",
  "configured": 2,
  "backfill": false,
  "first_sync_at": "2026-06-01T13:00:00Z",
  "message": "First sync is running. Data usually appears within a few minutes; the connector reports lifecycle 'ingesting' until data has synced."
}

Activates the resources you list and starts a sync right away (unless the connector is paused). This is the step after Discover Resources. Each resource can route its data to its own collection and carry its own metadata, additional_metadata, custom_instructions and acl.

lookback_days sets how much history the first sync fetches (default 30). Above 30, some providers fetch the older history in the background after the first sync, and the response reports backfill: true.

Calling configure again

You can call configure again at any time to add resources or change their settings:

• Resources you leave out of the list are not changed or removed. Use Delete Connector Resource to stop syncing one.
• For each resource you list, name, resource_type, database and collection are set to exactly what you send. Always send name and resource_type, because an omitted value clears the stored one. Send collection again if the resource has one.
• metadata and additional_metadata are merged into what is stored. New keys are added and existing keys are overwritten; keys cannot be removed this way.
• The resource’s sync position is kept, so it does not sync again from the beginning.
• custom_instructions and acl are kept when you omit them. To clear instructions, send "" with Update Connector Resource; configure cannot clear them.

To change only a resource’s instructions or access rule, use Update Connector Resource instead. It changes just the fields you send.

cURL

curl -X POST 'https://api.hydradb.com/connectors/{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": "C0123456789",
        "resource_type": "channel",
        "name": "general",
        "collection": "all-hands",
        "metadata": { "department": "all-hands" },
        "additional_metadata": { "internal_label": "general-slack" }
      },
      {
        "resource_id": "C0987654321",
        "resource_type": "channel",
        "name": "incidents",
        "collection": "engineering",
        "custom_instructions": "These threads are incident retros. Extract root cause, impact and owner."
      }
    ]
  }'

200

{
  "connector_id": "{connector_id}",
  "configured": 2,
  "backfill": false,
  "first_sync_at": "2026-06-01T13:00:00Z",
  "message": "First sync is running. Data usually appears within a few minutes; the connector reports lifecycle 'ingesting' until data has synced."
}

configured is the number of resources saved. warnings lists resources that were saved but returned no records when HydraDB tested them; they stay configured and index nothing until they have data.

Use Get Connector Status to follow the first sync.

Errors

• 400: resources is empty, or a field is invalid, for example custom_instructions over 4,000 characters.
• 404: no connector with this id in your workspace.
• 422: HydraDB tested a resource and the provider refused access. The message says which one and why. Nothing is saved.

Related Resources

• Next: Get Connector Status: follow the first sync
• Update Connector Resource: change one resource’s instructions or access rule
• Discover Resources: find resource ids before configuring
• Connectors - Overview: how synced metadata is merged

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 selection and sync options

resources · object[] · required

Resources to activate for this connector, each one entry from the Discover endpoint.

Show child attributes

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"
  }
]

full_visibility_roles · string[]

HubSpot only. HubSpot roles whose members can see every record; requires the all resource. Omit to keep the setting, send [] to clear it. Unknown roles fail the request.

lookback_days · integer

Days of history the first sync fetches. Default 30. Above 30, some providers fetch older history in background chunks and the response reports backfill: true.

Example:

30

table_configs · object[]

Per-table replication settings for table-syncing connectors (currently BigQuery), applied from the first sync. Other connectors return 400.

Show child attributes

Response

200

application/json

OK

backfill · boolean

true when older history beyond the first sync will be fetched in background chunks (see lookback_days).

Example:

true

configured · integer

Number of resources activated by this request.

Example:

1

connector_id · string

Connector this resource belongs to.

Example:

"conn_abc123"

first_sync_at · string

When the connector's next scheduled sync runs (RFC 3339). message says whether a sync already started now.

message · string

Human-readable result message.

Example:

"Success"

meta · object

Show child attributes

warnings · string[]

Resources that were saved but returned no records when probed. They stay configured and will index nothing until they have data.