> ## 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.

# Create Connector

> Store credentials for one provider account so its data can be synced.

Creates a connector for one provider account. Nothing syncs yet: next, call [Discover Resources](/api-reference/v2/endpoint/discover-connector-resources) to see what the credentials can reach, then [Configure Connector](/api-reference/v2/endpoint/configure-connector) to choose resources and start the first sync.

`provider` is any provider from [List Connector Providers](/api-reference/v2/endpoint/list-connector-providers). The shape of `credentials` depends on the provider: read it from `credential_schema` by calling that endpoint with `?id={provider}`. Credentials that do not match the schema are rejected.

Optional settings you can also pass here, and change later with [Update Connector](/api-reference/v2/endpoint/update-connector):

* `custom_instructions`: guidance for how this connector's documents are interpreted and indexed. See [Custom Ingestion Instructions](/essentials/v2/connector-instructions).
* `sync_interval_seconds`: how often scheduled syncs run. Omit it for the provider default (one hour for most providers).

<RequestExample>
  ```bash cURL theme={"dark"}
  curl -X POST 'https://api.hydradb.com/connectors' \
    -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
    -H "API-Version: 2" \
    -H "Content-Type: application/json" \
    -d '{
      "provider": "slack",
      "name": "acme-engineering",
      "database": "acme_corp",
      "collection": "engineering",
      "provider_account_scope": "T12345ACME",
      "credentials": {
        "access_token": "xoxp-..."
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={"dark"}
  {
    "connector_id": "{connector_id}",
    "provider": "slack",
    "name": "acme-engineering",
    "database": "acme_corp",
    "collection": "engineering",
    "tenant_id": "acme_corp",
    "sub_tenant_id": "engineering",
    "provider_account_scope": "T12345ACME",
    "lifecycle": "pending_setup",
    "sync_status": "idle",
    "sync_interval_seconds": 3600,
    "next_sync_at": "2026-06-01T12:05:00Z",
    "first_sync_at": "2026-06-01T12:05:00Z",
    "message": "Connector created. Configure resources to start syncing; the first scheduled sync runs in about 5 minutes."
  }
  ```
</ResponseExample>

The response repeats `database` and `collection` under their deprecated names `tenant_id` and `sub_tenant_id`. Read the new names.

## Errors

* `400`: `provider` or `database` is missing, the provider is unknown, or a setting such as `sync_interval_seconds` is out of range.
* `402`: your plan's connector limit is reached.
* `403`: the provider is not available to your workspace.
* `422`: `credentials` does not match the provider's `credential_schema`.

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

## Related Resources

* **Next:** [Discover Resources](/api-reference/v2/endpoint/discover-connector-resources): see what the credentials can reach
* **Next:** [Configure Connector](/api-reference/v2/endpoint/configure-connector): choose resources and start syncing
* [List Connector Providers](/api-reference/v2/endpoint/list-connector-providers): the credential schema for a provider
* [Connectors - Overview](/api-reference/v2/endpoint/connectors-overview)


## OpenAPI

````yaml api-reference/v2/openapi.json POST /connectors
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:
    post:
      tags:
        - connectors
      summary: Create a connector
      description: Create a connector for a provider and store its credentials.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handler.connectorCreateReq'
        description: Connector configuration
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.connectorCreateResponse'
          description: Created
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Service Unavailable
      security:
        - BearerAuth: []
components:
  schemas:
    handler.connectorCreateReq:
      properties:
        auth_type:
          description: >-
            Authentication method for the provider connection (e.g. `api_token`,
            `oauth`).
          example: api_token
          type: string
        collection:
          description: >-
            Default collection partition for synced objects. Deprecated alias:
            `sub_tenant_id`.
          example: team_docs
          type: string
        credentials:
          additionalProperties: {}
          description: >-
            Provider-specific credentials. Their shape is the provider's
            `credential_schema` from `GET /connectors/providers?id=<provider>`,
            for example `{"access_token": "..."}`.
          example:
            api_token: xoxb-...
          type: object
        custom_instructions:
          description: >-
            Instructions that steer how this connector's synced documents are
            ingested and indexed. Up to 4000 characters; editable later.
          type: string
        database:
          description: >-
            Database that receives the synced data. Required; the deprecated
            alias `tenant_id` is also accepted.
          example: acme_corp
          type: string
        name:
          description: Human-readable label for this connector.
          example: general
          type: string
        provider:
          description: >-
            External provider being synced (e.g. `slack`, `github`, `linear`,
            `notion`, `gmail`).
          example: slack
          type: string
        provider_account_scope:
          description: >-
            Identifier for the external account (e.g. Slack workspace ID, GitHub
            org name). Set a distinct value per account when you connect several
            accounts of one provider, so their objects cannot collide.
          example: T12345ACME
          type: string
        sub_tenant_id:
          deprecated: true
          description: 'Deprecated: use `collection`.'
          example: sub_tenant_4567
          type: string
          x-deprecated: 'true'
        sync_interval_seconds:
          description: >-
            How frequently the scheduler triggers incremental syncs, in seconds.
            Bounded per provider; send 0 or omit to use the provider default.
            Change it later with PATCH /connectors/{id}.
          example: 3600
          type: integer
        tenant_id:
          deprecated: true
          description: 'Deprecated: use `database`.'
          example: tenant_1234
          type: string
          x-deprecated: 'true'
      required:
        - provider
      type: object
    handler.connectorCreateResponse:
      properties:
        active_resource_count:
          description: >-
            Number of active resources on this connector. Zero means none are
            configured yet, and `lifecycle` reads `pending_setup`.
          example: 1
          type: integer
        auth_type:
          description: >-
            Authentication method for the provider connection (e.g. `api_token`,
            `oauth`).
          example: api_token
          type: string
        collection:
          description: >-
            Default collection for synced data; a resource can override it.
            Formerly `sub_tenant_id`, which is still returned with the same
            value.
          example: team_docs
          type: string
        connector_id:
          description: Unique identifier of the connector.
          example: conn_abc123
          type: string
        custom_instructions:
          description: >-
            Instructions that steer how this connector's synced documents are
            ingested and indexed. Up to 4000 characters; changes apply from the
            next sync.
          type: string
        database:
          description: >-
            Database that receives the synced data. Formerly `tenant_id`, which
            is still returned with the same value.
          example: acme_corp
          type: string
        documents_dispatched:
          description: >-
            Running total of objects sent for ingestion. It shows data is
            moving, not the indexed count: updates count again and deletes are
            not subtracted.
          example: 1
          type: integer
        first_data_dispatched_at:
          description: >-
            RFC3339 timestamp of the first sync that sent at least one object
            for ingestion. Empty until then.
          type: string
        first_sync_at:
          description: RFC3339 timestamp when the first scheduled sync runs.
          type: string
        last_attempted_sync_at:
          description: >-
            RFC3339 timestamp of the most recent sync attempt (successful or
            not).
          example: '2026-07-02T17:00:00Z'
          type: string
        last_error:
          description: >-
            Error message from the most recent failed sync, empty string when no
            error.
          example: ''
          type: string
        last_successful_sync_at:
          description: RFC3339 timestamp of the last successful sync completion.
          example: '2026-07-02T17:00:00Z'
          type: string
        lifecycle:
          description: >-
            Current state: `pending_setup` (no active resources), `ingesting`
            (first sync unfinished), `syncing`, `active`, `paused`, or
            `reconnect` (credentials rejected or connector blocked).
          type: string
        message:
          description: >-
            Human-readable note on when data will start to sync, safe to show to
            users as is.
          example: Success
          type: string
        name:
          description: Human-readable label for this connector.
          example: general
          type: string
        needs_reauth:
          description: >-
            True when the provider rejected the OAuth refresh token. Reconnect
            the account to resume syncing; clears on the next successful token
            refresh.
          example: true
          type: boolean
        needs_reauth_at:
          description: RFC3339 timestamp when `needs_reauth` was set.
          type: string
        needs_reauth_reason:
          description: >-
            Why the provider rejected the OAuth grant, when `needs_reauth` is
            true.
          type: string
        next_sync_at:
          description: RFC3339 timestamp when the next scheduled sync will run.
          example: '2026-07-02T18:00:00Z'
          type: string
        paused:
          description: >-
            True while the connector is paused. Scheduled and manual syncs are
            both refused until it is resumed; each resource then continues from
            where it stopped.
          example: true
          type: boolean
        paused_at:
          description: RFC3339 timestamp when the connector was paused.
          type: string
        provider:
          description: >-
            External provider being synced (e.g. `slack`, `github`, `linear`,
            `notion`, `gmail`).
          example: slack
          type: string
        provider_account_scope:
          description: >-
            Identifier for the external account (e.g. Slack workspace ID, GitHub
            org name). Set a distinct value per account when you connect several
            accounts of one provider, so their objects cannot collide.
          example: T12345ACME
          type: string
        resources_pending_first_sync:
          description: >-
            Number of active resources that have not completed their first
            successful sync. While above zero, `lifecycle` reads `ingesting`.
          example: 1
          type: integer
        status:
          deprecated: true
          description: >-
            Deprecated: always `active`. Read `lifecycle` for what the connector
            is doing.
          example: active
          type: string
        sub_tenant_id:
          deprecated: true
          description: 'Deprecated: use `collection`.'
          example: sub_tenant_4567
          type: string
          x-deprecated: 'true'
        sync_blocked:
          description: >-
            True when a failure retrying cannot fix, such as rejected
            credentials, stopped scheduled syncs. Updating credentials or
            configuration clears it.
          example: true
          type: boolean
        sync_blocked_at:
          description: RFC3339 timestamp when `sync_blocked` was set.
          type: string
        sync_blocked_reason:
          description: >-
            Error that blocked the connector, when `sync_blocked` is true. Up to
            1000 characters.
          type: string
        sync_interval_seconds:
          description: >-
            How frequently the scheduler triggers incremental syncs, in seconds.
            Bounded per provider; send 0 or omit to use the provider default.
            Change it later with PATCH /connectors/{id}.
          example: 3600
          type: integer
        sync_status:
          description: '`syncing` while a sync is running, otherwise `idle`.'
          example: idle
          type: string
        tenant_id:
          deprecated: true
          description: 'Deprecated: use `database`.'
          example: tenant_1234
          type: string
          x-deprecated: 'true'
      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.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
  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.