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

> ## Agent Instructions
> AGENTS.md is HydraDB's maintained agent guide. Read https://docs.hydradb.com/AGENTS.md once, then use its content. /llms.txt and /llms-full.txt redirect to the same guide; they are not separate documentation indexes. If the guide is already loaded, continue with it instead of fetching either alias or reloading the guide.

# Create Database

> Create an isolated database, with an optional metadata schema.

Creates an isolated database, optionally with a metadata schema. Creation is asynchronous: poll [Database Status](https://docs.hydradb.com/api-reference/v2/endpoint/database-status.md) until `infra.ready_for_ingestion` is `true` before you ingest or query.

```python Python SDK theme={"dark"}
response = client.databases.create(
    database="my_first_database",
    database_metadata_schema=[
        {
            "name": "category",
            "data_type": "VARCHAR",
            "max_length": 256,
        },
        {
            "name": "product_description",
            "data_type": "VARCHAR",
            "max_length": 4096,
            "enable_dense_embedding": True,
            "enable_sparse_embedding": True,
        },
    ],
)
```

```typescript TypeScript SDK theme={"dark"}
const response = await client.databases.create({
  database: "my_first_database",
  databaseMetadataSchema: [
    {
      name: "category",
      dataType: "VARCHAR",
      maxLength: 256,
    },
    {
      name: "product_description",
      dataType: "VARCHAR",
      maxLength: 4096,
      enableDenseEmbedding: true,
      enableSparseEmbedding: true,
    },
  ],
});
```

```bash cURL theme={"dark"}
curl -X POST 'https://api.hydradb.com/databases' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "my_first_database",
    "database_metadata_schema": [
      {
        "name": "category",
        "data_type": "VARCHAR",
        "max_length": 256
      },
      {
        "name": "product_description",
        "data_type": "VARCHAR",
        "max_length": 4096,
        "enable_dense_embedding": true,
        "enable_sparse_embedding": true
      }
    ]
  }'
```

```json Success theme={"dark"}
{
  "success": true,
  "data": {
    "status": "accepted",
    "database": "my_first_database",
    "message": "Database creation started in the background. Use GET /databases/status?database=... to check progress."
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}
```

```json Failure theme={"dark"}
{
  "success": false,
  "data": null,
  "error": {
    "code": "DATABASE_ALREADY_EXISTS",
    "message": "Database ID already exists"
  },
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 4.8
  }
}
```

## Request body

| Name | Description |
| - | - |
| `database`&#xA;\* string required | Account-scoped database identifier. Use a stable ID up to 255 characters of lowercase letters, digits, `-`, and `_`; anything else, including uppercase or spaces, returns `400`. |
| `database_metadata_schema` array | Database-level metadata fields. See the [schema field reference](https://docs.hydradb.com/essentials/v2/metadata.md#schema-field-reference) for field options. |

## Metadata schema rules

* Existing field names and types cannot change. [Update Metadata Schema](https://docs.hydradb.com/api-reference/v2/endpoint/update-metadata-schema.md) can add fields later.
* Dense and sparse metadata search can only be enabled at database creation, with `enable_dense_embedding` and `enable_sparse_embedding`.
* Each flag adds one vector field. A database can have at most six vector fields. Exceeding this limit or declaring an `ARRAY` field returns `400`.

## After creation

1. **Wait for provisioning:** Poll [Database Status](https://docs.hydradb.com/api-reference/v2/endpoint/database-status.md) until `infra.ready_for_ingestion` is `true`.
2. **Ingest:** Start [ingesting context](https://docs.hydradb.com/api-reference/v2/endpoint/ingest-context.md). Ingesting with a new `collection` name creates that collection. Omitting `collection` uses the default collection, also created on first ingestion. No separate create call is needed.
3. **Query:** Check [ingestion status](https://docs.hydradb.com/api-reference/v2/endpoint/source-status.md), and query once sources show `graph_creation` (searchable) or `completed`.

**Failed provisioning:** If the database appears in `data.failed_databases` from [List Databases](https://docs.hydradb.com/api-reference/v2/endpoint/list-databases.md), address the reported issue, re-create the database with `POST /databases`, and poll status again before ingesting.

## Errors

Common codes: `400 INVALID_INPUT` (missing or invalid `database`, or an invalid schema), `403 FORBIDDEN` (your plan's database limit is reached), `409 DATABASE_ALREADY_EXISTS` (the `database` is already in use; the deprecated `POST /tenants` route returns `INVALID_INPUT` instead), and `500 INTERNAL_ERROR` (retry; if the message says the rollback also failed, delete the database first, then create it again). See [Error Responses](https://docs.hydradb.com/api-reference/v2/error-responses.md) for the full list.

## Related resources

* **After this:** [Database Status](https://docs.hydradb.com/api-reference/v2/endpoint/database-status.md): poll until provisioning completes
* **After this:** [Ingest Context](https://docs.hydradb.com/api-reference/v2/endpoint/ingest-context.md): ingest once the database is ready
* **Related:** [Update Metadata Schema](https://docs.hydradb.com/api-reference/v2/endpoint/update-metadata-schema.md): add metadata schema fields later
* **Related:** [Delete Database](https://docs.hydradb.com/api-reference/v2/endpoint/delete-database.md): remove the database and everything in it
* **Guide:** [Databases and Collections](https://docs.hydradb.com/essentials/v2/databases-and-collections.md): choose database and collection scopes
* **Guide:** [Metadata Filters](https://docs.hydradb.com/essentials/v2/metadata.md): field options, ingestion, and filtering examples


## OpenAPI

````yaml api-reference/v2/openapi.json POST /databases
openapi: 3.1.0
info:
  contact:
    email: support@hydradb.com
    name: HydraDB Support
  description: >-
    The HydraDB API: ingest context, query it, and manage databases, connectors
    and webhooks.
  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:
  /databases:
    post:
      tags:
        - database-management
      summary: Create a database
      description: Create a new database with optional custom metadata schema
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/tenants.TenantCreateRequest'
        description: Database creation request
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/handler.Envelope-tenants_TenantCreateAcceptedResponse
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Conflict
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
        - BearerAuth: []
components:
  schemas:
    tenants.TenantCreateRequest:
      properties:
        database:
          description: >-
            Name of the database to create. Formerly `tenant_id`, which is still
            accepted.
          example: acme_corp
          type: string
        database_metadata_schema:
          description: >-
            Database-level metadata fields for exact-match filtering and
            semantic or BM25 search. Field names cannot change after creation.
          example:
            - data_type: VARCHAR
              enable_dense_embedding: true
              enable_match: true
              enable_sparse_embedding: false
              max_length: 256
              name: category
          items:
            $ref: '#/components/schemas/tenants.CustomPropertyDefinition'
          type: array
          uniqueItems: false
        embeddings_dimension:
          description: 'Override for the embedding vector dimension. Default: 1536.'
          example: 1536
          type: integer
        is_embeddings_tenant:
          description: Internal flag for embedding-only databases.
          example: false
          type: boolean
        tenant_id:
          deprecated: true
          description: 'Deprecated: use `database`.'
          example: tenant_1234
          type: string
          x-deprecated: 'true'
        tenant_metadata_schema:
          deprecated: true
          description: 'Deprecated: use `database_metadata_schema`.'
          items:
            $ref: '#/components/schemas/tenants.CustomPropertyDefinition'
          type: array
          uniqueItems: false
          x-deprecated: 'true'
      title: TenantsTenantCreateRequest
      type: object
    handler.Envelope-tenants_TenantCreateAcceptedResponse:
      properties:
        data:
          $ref: '#/components/schemas/tenants.TenantCreateAcceptedResponse'
          example:
            database: acme_corp
            message: Success
            status: completed
            tenant_id: tenant_1234
        error:
          anyOf:
            - $ref: '#/components/schemas/handler.apiError'
              title: HandlerApiError
            - title: No error
              type: 'null'
          description: Error details on failure, or null on success.
          example: null
        meta:
          $ref: '#/components/schemas/handler.responseMeta'
          example:
            collection: team_docs
            database: acme_corp
            latency_ms: 12.3
            request_id: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d
            source_type: file
            sub_tenant_id: sub_tenant_4567
            tenant_id: tenant_1234
            warnings:
              - code: acl_ignored_by_connector_enforcement
                message: This connector enforces ACL, so the request's acl was ignored.
        success:
          description: Whether the request succeeded.
          example: true
          type: boolean
      title: HandlerEnvelopeTenantsTenantCreateAcceptedResponse
      type: object
    handler.ErrorResponse:
      properties:
        data:
          description: Always `null` on this error response.
          type: 'null'
        detail:
          $ref: '#/components/schemas/handler.ErrorDetail'
          description: Structured error detail with code, message, and deprecation hints.
          example:
            deprecated: true
            deprecated_field: tenant_id
            deprecated_since: 2.0.1
            error_code: VALIDATION_ERROR
            message: Request validation failed
            preferred_field: database
            retry_after_seconds: 1
            retryable: true
        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
      title: HandlerErrorResponse
      type: object
    tenants.CustomPropertyDefinition:
      properties:
        data_type:
          allOf:
            - $ref: '#/components/schemas/tenants.MetadataDataType'
          description: Data type of the metadata field, for example `VARCHAR`.
          example: VARCHAR
        enable_dense_embedding:
          description: Whether to enable semantic (dense) embedding search on this field.
          example: true
          type: boolean
        enable_match:
          description: Whether to enable exact-match filtering on this field.
          example: true
          type: boolean
        enable_sparse_embedding:
          description: Whether to enable BM25 (sparse) embedding search on this field.
          example: false
          type: boolean
        max_length:
          description: Maximum string length in bytes for VARCHAR fields.
          example: 256
          type: integer
        name:
          description: Field name. Immutable after database creation.
          example: category
          type: string
      title: TenantsCustomPropertyDefinition
      type: object
    tenants.TenantCreateAcceptedResponse:
      properties:
        database:
          description: >-
            Owning database. Formerly `tenant_id`; the `tenant_id` alias is
            still accepted (deprecated).
          example: acme_corp
          type: string
        message:
          description: Human-readable result message.
          example: Success
          type: string
        status:
          description: Current lifecycle or processing state.
          example: completed
          type: string
        tenant_id:
          deprecated: true
          description: 'Deprecated: use `database`.'
          example: tenant_1234
          type: string
          x-deprecated: 'true'
      title: TenantsTenantCreateAcceptedResponse
      type: object
    handler.apiError:
      properties:
        code:
          description: Machine-readable error code (e.g. `DATABASE_NOT_FOUND`).
          example: DATABASE_NOT_FOUND
          type: string
        details:
          additionalProperties:
            type: string
          description: >-
            Extra facts about the error, as string pairs. Omitted when there are
            none.
          type: object
        message:
          description: Human-readable description of the error.
          example: Database not found
          type: string
        param:
          description: >-
            The request field that caused the error. Omitted when no single
            field is at fault.
          type: string
      title: HandlerApiError
      type: object
    handler.responseMeta:
      properties:
        api_version:
          description: >-
            Version of the API that served the request, for example `2.0.1`.
            Always present.
          type: string
        collection:
          description: >-
            Collection scope. Defaults to the default collection when omitted.
            Formerly `sub_tenant_id`; the `sub_tenant_id` alias is still
            accepted (deprecated).
          example: team_docs
          type: string
        database:
          description: >-
            Owning database. Formerly `tenant_id`; the `tenant_id` alias is
            still accepted (deprecated).
          example: acme_corp
          type: string
        deprecation:
          description: >-
            Migration notices for this request, present only when it used a
            deprecated route, field or selector. The status code is unaffected.
          items:
            $ref: '#/components/schemas/handler.deprecationNotice'
          type: array
          uniqueItems: false
        latency_ms:
          description: Server-side processing time in milliseconds.
          example: 12.3
          type:
            - number
            - 'null'
        request_id:
          description: Unique identifier for this request, useful for support and tracing.
          example: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d
          type: string
        source_type:
          description: Type of the parent source (e.g. `file`, `slack`, `notion`).
          example: file
          type: string
        sub_tenant_id:
          deprecated: true
          description: 'Deprecated: use `collection`.'
          example: sub_tenant_4567
          type: string
          x-deprecated: 'true'
        tenant_id:
          deprecated: true
          description: 'Deprecated: use `database`.'
          example: tenant_1234
          type: string
          x-deprecated: 'true'
        warnings:
          description: >-
            Warnings contains non-fatal notices; enforced reads may include
            acl_ignored_by_connector_enforcement when a request ACL is replaced.
          example:
            - code: acl_ignored_by_connector_enforcement
              message: This connector enforces ACL, so the request's acl was ignored.
          items:
            $ref: '#/components/schemas/handler.ResponseWarning'
          type: array
          uniqueItems: false
      title: HandlerResponseMeta
      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
        deprecated_since:
          description: API version that deprecated the conflicting selector.
          example: 2.0.1
          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
        retry_after_seconds:
          description: >-
            Seconds to wait before retrying deletion of context that is still
            indexing.
          example: 1
          type: integer
        retryable:
          description: >-
            Whether retrying this failed query can succeed. Present for search
            workflow failures.
          example: true
          type: boolean
        success:
          deprecated: true
          description: >-
            Deprecated: always `false`. Read the HTTP status, then `error.code`
            and `error.message`.
          example: false
          type: boolean
          x-deprecated: 'true'
      title: HandlerErrorDetail
      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
      title: HandlerErrorMeta
      type: object
    tenants.MetadataDataType:
      description: >-
        Data type of a metadata field. `ARRAY` cannot be declared on a new
        field: for several values, declare `VARCHAR` and store them
        comma-joined.
      enum:
        - BOOL
        - INT8
        - INT16
        - INT32
        - INT64
        - FLOAT
        - DOUBLE
        - VARCHAR
        - JSON
        - ARRAY
      type: string
      x-enum-varnames:
        - DataTypeBool
        - DataTypeInt8
        - DataTypeInt16
        - DataTypeInt32
        - DataTypeInt64
        - DataTypeFloat
        - DataTypeDouble
        - DataTypeVarchar
        - DataTypeJSON
        - DataTypeArray
    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
      title: HandlerDeprecationNotice
      type: object
    handler.ResponseWarning:
      properties:
        code:
          description: >-
            Code identifies the warning type, such as
            acl_ignored_by_connector_enforcement.
          example: acl_ignored_by_connector_enforcement
          type: string
        message:
          description: Human-readable explanation of the warning.
          example: This connector enforces ACL, so the request's acl was ignored.
          type: string
      title: HandlerResponseWarning
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: API key
      description: 'Send your API key as Authorization: Bearer <your_api_key>.'
      scheme: bearer
      type: http

````

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