---
title: "Create a database"
method: POST
path: "/databases"
tags: ["database-management"]
---

# Create a database

`POST /databases`

Create a new database with optional custom metadata schema

## Request body

- TenantsTenantCreateRequest
  - `database` string — Database is the canonical v2 name; TenantID is its deprecated alias and remains fully accepted. The TenantAliases middleware reconciles them before this binds, so TenantID is always populated.
  - `database_metadata_schema` TenantsCustomPropertyDefinition[] — Defines database-level metadata fields for exact-match filtering and semantic/BM25 search. Canonical name; `tenant_metadata_schema` is a deprecated alias. Schema field names are immutable after database creation.
    - `data_type` 'BOOL' | 'INT8' | 'INT16' | 'INT32' | 'INT64' | 'FLOAT' | 'DOUBLE' | 'VARCHAR' | 'JSON' | 'ARRAY'
    - `enable_analyzer` boolean — Whether to enable text analysis (tokenization) for BM25 search on this field.
    - `enable_dense_embedding` boolean — Whether to enable semantic (dense) embedding search on this field.
    - `enable_match` boolean — Whether to enable exact-match filtering on this field.
    - `enable_sparse_embedding` boolean — Whether to enable BM25 (sparse) embedding search on this field.
    - `max_length` integer — Maximum string length in bytes for VARCHAR fields.
    - `name` string — Field name. Immutable after database creation.
  - `embeddings_dimension` integer — Override for the embedding vector dimension. Default: 1536.
  - `is_embeddings_tenant` boolean — Internal flag for embedding-only databases.
  - `tenant_id` string — deprecated: use database
  - `tenant_metadata_schema` TenantsCustomPropertyDefinition[] — deprecated: use database_metadata_schema
    - `data_type` 'BOOL' | 'INT8' | 'INT16' | 'INT32' | 'INT64' | 'FLOAT' | 'DOUBLE' | 'VARCHAR' | 'JSON' | 'ARRAY'
    - `enable_analyzer` boolean — Whether to enable text analysis (tokenization) for BM25 search on this field.
    - `enable_dense_embedding` boolean — Whether to enable semantic (dense) embedding search on this field.
    - `enable_match` boolean — Whether to enable exact-match filtering on this field.
    - `enable_sparse_embedding` boolean — Whether to enable BM25 (sparse) embedding search on this field.
    - `max_length` integer — Maximum string length in bytes for VARCHAR fields.
    - `name` string — Field name. Immutable after database creation.

## Response `200`

OK

- HandlerEnvelopeTenantsTenantCreateAcceptedResponse
  - `data` TenantsTenantCreateAcceptedResponse
    - `database` string — Owning database. Formerly `tenant_id`; the `tenant_id` alias is still accepted (deprecated).
    - `message` string — Human-readable result message.
    - `status` string — Current lifecycle or processing state.
    - `tenant_id` string
  - `error` HandlerApiError
    - `code` string — Machine-readable error code (e.g. `DATABASE_NOT_FOUND`).
    - `message` string — Human-readable description of the error.
  - `meta` HandlerResponseMeta
    - `api_version` string — APIVersion echoes the version of the API that served the request (PRO-1209), sourced from reqmeta.APIVersion — the same value carried by OpenAPI info.version and /health — so a client always knows which API version produced a response. Always present (no omitempty).
    - `collection` string — Collection scope. Defaults to the default collection when omitted. Formerly `sub_tenant_id`; the `sub_tenant_id` alias is still accepted (deprecated).
    - `database` string — Owning database. Formerly `tenant_id`; the `tenant_id` alias is still accepted (deprecated).
    - `deprecation` HandlerDeprecationNotice[] — Deprecation lists any migration nudges that apply to this request — the caller used a legacy /tenants route, a legacy tenant_id/sub_tenant_id field, or the deprecated sub_tenant_ids selector. It is a non-breaking signal (the status code is unchanged); omitempty keeps it absent for fully-migrated requests. A list so independent deprecations coexist without clobbering.
      - `deprecated` boolean — Whether this response concerns a deprecated field or route.
      - `deprecated_field` string — The deprecated field name.
      - `deprecated_since` string — API version when the field was deprecated.
      - `message` string — Migration guidance message.
      - `preferred_field` string — The canonical replacement for the deprecated field.
    - `latency_ms` number — Server-side processing time in milliseconds.
    - `request_id` string — Unique identifier for this request, useful for support and tracing.
    - `source_type` string — Type of the parent source (e.g. `file`, `slack`, `notion`).
    - `sub_tenant_id` string
    - `tenant_id` string
  - `success` boolean — Whether the request succeeded.

## Other responses

- `400` — Bad Request
- `403` — Forbidden
- `409` — Conflict
- `500` — Internal Server Error

---

[API](https://skmtc.dev/hydradb/apis/hydradb-application-api.md) · [All operations](https://skmtc.dev/hydradb/apis/hydradb-application-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/hydradb/hydradb-application-api/revisions/c773cb4e113a/schema)