> ## Documentation Index
> Fetch the complete documentation index at: https://cortex-e852fafe-t3code-rewrite-docs-declutter.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Connector

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

Activates the resources you list and starts a sync right away (unless the connector is paused). This is the step after [Discover Resources](/api-reference/v2/endpoint/discover-connector-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](/api-reference/v2/endpoint/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](/api-reference/v2/endpoint/update-connector-resource); configure cannot clear them.

<Tip>
  To change only a resource's instructions or access rule, use [Update Connector Resource](/api-reference/v2/endpoint/update-connector-resource) instead. It changes just the fields you send.
</Tip>

<RequestExample>
  ```bash cURL theme={"dark"}
  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."
        }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"dark"}
  {
    "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."
  }
  ```
</ResponseExample>

`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](/api-reference/v2/endpoint/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.

<div className="api-before-related-resources" />

## Related Resources

* **Next:** [Get Connector Status](/api-reference/v2/endpoint/get-connector-status): follow the first sync
* [Update Connector Resource](/api-reference/v2/endpoint/update-connector-resource): change one resource's instructions or access rule
* [Discover Resources](/api-reference/v2/endpoint/discover-connector-resources): find resource ids before configuring
* [Connectors - Overview](/api-reference/v2/endpoint/connectors-overview): how synced metadata is merged


## 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: >-
        Activate resources and start a sync. Resources not in the list are left
        as they are. A listed resource keeps its sync position, instructions and
        access rule when those are omitted, but its `name`, `resource_type`,
        `database` and `collection` are set to what you send.
      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:
        full_visibility_roles:
          description: >-
            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.
          items:
            type: string
          type: array
          uniqueItems: false
        lookback_days:
          description: >-
            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
          type: integer
        resources:
          description: >-
            Resources to activate for this connector, each 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: >-
            Per-table replication settings for table-syncing connectors
            (currently BigQuery), applied from the first sync. Other connectors
            return `400`.
          items:
            $ref: '#/components/schemas/handler.tableConfigEntry'
          type: array
          uniqueItems: false
      required:
        - resources
      type: object
    handler.configureResponse:
      properties:
        backfill:
          description: >-
            `true` when older history beyond the first sync will be fetched in
            background chunks (see `lookback_days`).
          example: true
          type: boolean
        configured:
          description: Number of resources activated by this request.
          example: 1
          type: integer
        connector_id:
          description: Connector this resource belongs to.
          example: conn_abc123
          type: string
        first_sync_at:
          description: >-
            When the connector's next scheduled sync runs (RFC 3339). `message`
            says whether a sync already started now.
          type: string
        message:
          description: Human-readable result message.
          example: Success
          type: string
        meta:
          $ref: '#/components/schemas/handler.configureResponseMeta'
        warnings:
          description: >-
            Resources that were saved but returned no records when probed. They
            stay configured and will index nothing until they have data.
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    handler.ErrorResponse:
      properties:
        data:
          description: Always `null` on this error response.
        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: false
          type: boolean
      type: object
    handler.resourceMapping:
      properties:
        acl:
          description: >-
            Principals (emails or prefixed principals) allowed to read objects
            synced from this resource. Omitted means unrestricted; an empty list
            makes them private.
          items:
            type: string
          type: array
          uniqueItems: false
        additional_metadata:
          additionalProperties: {}
          description: >-
            Free-form key-value pairs merged into the custom attributes of every
            synced object. Provider-generated fields win on conflict.
          example:
            author: ada
            doc_version: 3
          type: object
        collection:
          description: >-
            Routes objects synced from this resource into a specific collection.
            Overrides the connector-level `collection`; empty means the
            connector's collection.
          example: team_docs
          type: string
        custom_instructions:
          description: >-
            Ingestion and indexing instructions for this resource, replacing the
            connector's `custom_instructions`; empty inherits it. Up to 4000
            characters.
          type: string
        database:
          description: >-
            Routes objects synced from this resource into a specific database.
            Empty means the connector's database.
          example: acme_corp
          type: string
        metadata:
          additionalProperties: {}
          description: >-
            Key-value pairs merged into the attributes of every synced object.
            Only keys declared in the metadata schema are filterable.
            `connector_id` and `provider` win on conflict.
          example:
            department: finance
            priority: 7
          type: object
        name:
          description: >-
            Display name for this resource. Send it on every configure: an
            omitted name clears the stored one.
          example: general
          type: string
        resource_id:
          description: Resource identifier from the Discover endpoint.
          example: C0123456789
          type: string
        resource_type:
          description: >-
            Type from the Discover endpoint (e.g. `channel`, `repo`, `table`).
            Send it on every configure: an omitted type clears the stored one.
          example: channel
          type: string
        sub_tenant_id:
          deprecated: true
          description: 'Deprecated: use `collection`.'
          example: sub_tenant_4567
          type: string
          x-deprecated: 'true'
        sync_mode:
          description: >-
            How this resource picks up changes (currently Attio objects and
            lists): `rescan` (default) re-reads everything and sees edits;
            `new_only` reads only new records.
          enum:
            - rescan
            - new_only
          type: string
        tenant_id:
          deprecated: true
          description: 'Deprecated: use `database`.'
          example: tenant_1234
          type: string
          x-deprecated: 'true'
      required:
        - resource_id
      type: object
    handler.tableConfigEntry:
      properties:
        change_history:
          description: >-
            Read changes from BigQuery's change history instead of a column:
            `appends` (new rows only) or `changes` (inserts, updates, deletes).
            Set this or `replication_key`.
          type: string
        replication_key:
          description: >-
            An orderable last-modified column (for example `updated_at`) used to
            find changed rows. Set exactly one of `replication_key` or
            `change_history`.
          type: string
        table:
          description: >-
            Table to configure, as its resource id from Discover
            (`dataset.table`). One entry per table.
          type: string
      type: object
    handler.configureResponseMeta:
      properties:
        deprecation:
          description: >-
            Migration notices, present when the request used a deprecated field
            such as `tenant_id` or `sub_tenant_id`.
          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: always `false`. Read the HTTP status, then `error.code`
            and `error.message`.
          example: false
          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:
          description: Version of the API that served the request, for example `2.0.1`.
          type: string
        latency_ms:
          description: Server-side processing time in milliseconds.
          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

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.