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

# Create Connector

> Create a new connector that continuously syncs data from an external provider.

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 <span aria-label={ariaParts.join(', ')} className={label ? 'field-wrap has-field-tip' : 'field-wrap'} style={{
    position: 'relative',
    cursor: label ? 'default' : undefined
  }} tabIndex={label ? 0 : undefined}>
      <span className="field-name-row">
        <code>{name}</code>
        {required && <span className="field-req"> *</span>}
        {recommended && <span className="field-rec"> ●</span>}
      </span>
      {type && <span className="field-type">{type}</span>}
      {label && <span className="field-tip" role="tooltip">
          {label}
        </span>}
    </span>;
};

Creates a connector and stores credentials for a single provider account. After creation, call [Discover](/api-reference/v2/endpoint/discover-connector-resources) to see available resources, then [Configure](/api-reference/v2/endpoint/configure-connector) to activate them.

<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": {
        "api_token": "xoxp-..."
      }
    }'
  ```
</RequestExample>

## Request body

| Name                                                  | Description                                                                                                                                                         |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <Field name="provider" type="string" required />      | Provider to connect. One of `slack`, `github`, `linear`, `notion`, `gmail`.                                                                                         |
| <Field name="name" type="string" required />          | Human-readable label for this connector.                                                                                                                            |
| <Field name="database" type="string" required />      | Which database receives the synced data. (deprecated alias: `tenant_id`)                                                                                            |
| <Field name="collection" type="string" />             | Default collection partition for synced objects. Individual resources can override this. (deprecated alias: `sub_tenant_id`; default: `""`)                         |
| <Field name="provider_account_scope" type="string" /> | Identifier for the external account (e.g. Slack workspace ID, GitHub org name). Used in deduplication  -  must be distinct across connectors for the same provider. |
| <Field name="credentials" type="object" required />   | Provider-specific credentials. Typically `{ "api_token": "..." }` or `{ "access_token": "..." }`.                                                                   |

<ResponseExample>
  ```json 201 theme={"dark"}
  {
    "connector_id": "{connector_id}",
    "provider": "slack",
    "name": "acme-engineering",
    "tenant_id": "acme_corp",
    "sub_tenant_id": "engineering",
    "provider_account_scope": "T12345ACME",
    "status": "active",
    "next_sync_at": "2026-06-01T13:00:00Z",
    "sync_interval_seconds": 3600
  }
  ```
</ResponseExample>

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

## Related Resources

* **Next:** [Discover Resources](/api-reference/v2/endpoint/discover-connector-resources)  -  inspect what's available before activating
* **Next:** [Configure Connector](/api-reference/v2/endpoint/configure-connector)  -  activate resources for sync
* **Teardown:** [Delete Connector](/api-reference/v2/endpoint/delete-connector)
* **Read more:** [Connectors guide](/essentials/v2/connectors)


## 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/connectors.Connector'
          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 (typically `{"api_token": "..."}` or
            `{"access_token": "..."}`).
          example:
            api_token: xoxb-...
          type: object
        database:
          description: >-
            Database/Collection are the canonical v2 names; TenantID/SubTenantID
            are

            their deprecated aliases, reconciled by the TenantAliases middleware
            before

            binding so TenantID is always populated. Neither is marked
            binding:required

            (mirroring TenantCreateRequest): a caller may send either spelling,
            and the

            tenant scope is validated downstream by resolveTenant. Requiring
            tenant_id

            here would force the generated SDK to demand the deprecated field.
          example: acme_corp
          type: string
        deployment_id:
          description: Internal deployment context for this connector.
          example: deploy_1234
          type: string
        name:
          description: Human-readable label for this connector.
          example: general
          type: string
        plan:
          description: Subscription plan this connector runs under.
          example: pro
          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). Must be distinct across connectors for the same provider.
          example: T12345ACME
          type: string
        sub_tenant_id:
          deprecated: true
          description: 'deprecated: use collection'
          example: sub_tenant_4567
          type: string
          x-deprecated: 'true'
        sync_engine:
          description: >-
            SyncEngine selects the sync pipeline: "classic" (default) or
            "moveit".
          type: string
        sync_interval_seconds:
          description: How frequently the scheduler triggers incremental syncs, in seconds.
          example: 3600
          type: integer
        tenant_id:
          deprecated: true
          description: 'deprecated: use database'
          example: tenant_1234
          type: string
          x-deprecated: 'true'
      required:
        - provider
      type: object
    connectors.Connector:
      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. Canonical name;
            mirrors the deprecated `sub_tenant_id` alias.
          example: team_docs
          type: string
        connector_id:
          description: Connector this resource belongs to.
          example: conn_abc123
          type: string
        credential_ref:
          description: Internal reference to the stored credential record.
          example: cred_1a2b3c
          type: string
        database:
          description: >-
            Database/Collection are the canonical v2 names for the deprecated

            tenant_id/sub_tenant_id wire fields. They mirror the same values so
            a v2

            client sees the canonical names on responses while a legacy client
            keeps

            reading tenant_id/sub_tenant_id. Not persisted (dynamodbav:"-"): the
            store

            builds items from tenant_id/sub_tenant_id and mirrors these on load.
            They

            are populated at every construction point (toConnector,
            connectorFromItem)

            rather than via MarshalJSON so Temporal's JSON data converter
            round-trips

            Connector activity inputs without spuriously populating them.
          example: acme_corp
          type: string
        deployment_id:
          description: Internal deployment context for this connector.
          example: deploy_1234
          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
        name:
          description: Human-readable label for this connector.
          example: general
          type: string
        next_sync_at:
          description: RFC3339 timestamp when the next scheduled sync will run.
          example: '2026-07-02T18:00:00Z'
          type: string
        org_id:
          description: Organization that owns this resource.
          example: org_1a2b3c
          type: string
        plan:
          description: Subscription plan this connector runs under.
          example: pro
          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). Must be distinct across connectors for the same provider.
          example: T12345ACME
          type: string
        status:
          description: >-
            Lifecycle status of the connector (e.g. `active`, `paused`,
            `error`).
          example: completed
          type: string
        sub_tenant_id:
          deprecated: true
          description: >-
            Default collection partition for synced objects. Deprecated — use
            `collection`.
          example: sub_tenant_4567
          type: string
          x-deprecated: 'true'
        sync_engine:
          description: >-
            SyncEngine is "classic" (default, empty treated as classic) or
            "moveit".

            See the SyncEngine* constants; the scheduler branches on it.
          type: string
        sync_interval_seconds:
          description: How frequently the scheduler triggers incremental syncs, in seconds.
          example: 3600
          type: integer
        sync_status:
          description: Current sync operation state (e.g. `idle`, `running`).
          example: idle
          type: string
        tenant_id:
          deprecated: true
          description: Database that receives synced data. Deprecated — use `database`.
          example: tenant_1234
          type: string
          x-deprecated: 'true'
        user_id:
          description: User that created or owns this resource.
          example: user_alex
          type: string
      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.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

````