> For the complete documentation index, see [llms.txt](https://docs.khotan.com/llms.txt). A markdown version of any page is available at its `index.md` URL. # Databases `/api/v1` operations for databases. See [HTTP API](/api/) for authentication, the error envelope, and rate limits. ## Operations ### GET /api/v1/databases List databases Returns the organization's non-deleted production databases. Responses never include usage data or connection credentials. Auth: API key required. Operation ID: `listDatabases` Responses: - `200` — The organization's databases. - `401` — Authentication is missing or invalid. - `429` — Too many requests; retry after the indicated delay. CLI: `khotan databases list` ### POST /api/v1/databases Create a database Provisions a production Postgres database synchronously and responds 201 with the persisted record whether provisioning ends ready or failed; branch on the returned status. This operation is not idempotent: retrying a request that already succeeded provisions a second database. Omit regionId to use the default region. Auth: API key required. Operation ID: `createDatabase` Request body (`application/json`, required): - `name` (string, required) - `regionId` (string | null, optional) - `idempotencyKey` (string, optional) Responses: - `201` — The persisted database record, in ready or failed status. - `400` — The request was malformed or failed validation. - `401` — Authentication is missing or invalid. - `429` — Too many requests; retry after the indicated delay. CLI: `khotan databases create` ### GET /api/v1/databases/{databaseId} Get a database Returns one database's record, including status and failure state when present. Responses never include usage data or connection credentials. Auth: API key required. Operation ID: `getDatabase` Path parameters: - `databaseId` (string, required) Responses: - `200` — The database record. - `401` — Authentication is missing or invalid. - `404` — The resource was not found. - `429` — Too many requests; retry after the indicated delay. CLI: `khotan databases get` ### DELETE /api/v1/databases/{databaseId} Delete a database Tears down the provider project, then soft-deletes the record — the same semantics as deleting from the dashboard. Deletion is permanent. Returns 403 resource_protected when the database has deletion protection enabled; protection can only be removed from the dashboard. Auth: API key required. Operation ID: `deleteDatabase` Path parameters: - `databaseId` (string, required) Responses: - `200` — The database was deleted. - `401` — Authentication is missing or invalid. - `403` — The database is protected from deletion (code resource_protected). Remove protection from the dashboard before deleting via the API. - `404` — The resource was not found. - `429` — Too many requests; retry after the indicated delay. - `502` — Response. CLI: `khotan databases delete` ### PUT /api/v1/databases/{databaseId}/tags Set a database's tags Replaces a database's tag list with the submitted list and returns the stored list. Tags are normalized to lowercase slugs, so `Live` is stored as `live`. Send an empty list to remove every tag. Requires an API key whose role is owner or developer. Auth: API key required. Operation ID: `setDatabaseTags` Path parameters: - `databaseId` (string, required) Request body (`application/json`, required): - `tags` (string[], required) — Full tag list; it replaces the stored list. Each tag is trimmed, lowercased, and has whitespace runs replaced with "-", and repeats are removed. After that, each tag is 1-32 lowercase letters, digits, or single hyphens, with at most 10 tags. Presets: test, live, uat, dev, demo, deprecated. Responses: - `200` — The stored tag list, after normalization. - `400` — The request was malformed or failed validation. - `401` — Authentication is missing or invalid. - `403` — The caller is not permitted to perform this action. - `404` — The resource was not found. - `429` — Too many requests; retry after the indicated delay. CLI: `khotan databases tags set` ### GET /api/v1/databases/{databaseId}/connection Get the connection URI Returns the full Postgres connection URI for a ready database. The URI grants complete read/write access to the database; treat it as a secret. Responds 404 until the database is ready. All schema and row access happens directly over Postgres using this URI — the API never proxies SQL. Auth: API key required. Operation ID: `getDatabaseConnection` Path parameters: - `databaseId` (string, required) Responses: - `200` — The connection URI for the ready database. - `401` — Authentication is missing or invalid. - `404` — The resource was not found. - `429` — Too many requests; retry after the indicated delay. CLI: `khotan databases connection` ### POST /api/v1/databases/{databaseId}/rotate-credentials Rotate database credentials Resets the database role password through the provider and returns the new connection URI; the previous URI stops authenticating immediately. Rotation drops any live connections or pools still using the old credentials — plan to reconnect. Rotation is idempotent: if a rotation reports a persistence failure, rotating again issues a fresh working connection string. Auth: API key required. Operation ID: `rotateDatabaseCredentials` Path parameters: - `databaseId` (string, required) Responses: - `200` — The new connection URI after rotation. - `401` — Authentication is missing or invalid. - `404` — The resource was not found. - `409` — Another rotation is already in progress for this database; retry shortly. - `429` — Too many requests; retry after the indicated delay. CLI: `khotan databases rotate-credentials` ### GET /api/v1/databases/{databaseId}/branches List database branches Returns the database's non-deleted branches. Responses never include connection credentials. Auth: API key required. Operation ID: `listDatabaseBranches` Path parameters: - `databaseId` (string, required) Responses: - `200` — The database's branches. - `401` — Authentication is missing or invalid. - `429` — Too many requests; retry after the indicated delay. CLI: `khotan databases branches list` ### POST /api/v1/databases/{databaseId}/branches Create a database branch Branches a ready database synchronously and responds 201 with the persisted record whether provisioning ends ready or failed; branch on the returned status. Omit parentBranchId to branch from the database root. Expiration: omit expiresAt and noExpiry for the ephemeral default, pass expiresAt (ISO 8601) for an explicit expiry, or noExpiry true for a non-expiring branch. This operation is not idempotent. Auth: API key required. Operation ID: `createDatabaseBranch` Path parameters: - `databaseId` (string, required) Request body (`application/json`, required): - `name` (string, required) - `parentBranchId` (string | null, optional) - `initSource` ("parent-data" | "schema-only", required) - `parentTimestamp` (string | null, optional) - `expiresAt` (string | null, optional) - `noExpiry` (boolean | null, optional) Responses: - `201` — The persisted branch record, in ready or failed status. - `400` — The request was malformed or failed validation. - `401` — Authentication is missing or invalid. - `404` — The resource was not found. - `429` — Too many requests; retry after the indicated delay. CLI: `khotan databases branches create` ### GET /api/v1/databases/{databaseId}/branches/{branchId} Get a database branch Returns one branch's record, including status and failure state when present. Responses never include connection credentials. Auth: API key required. Operation ID: `getDatabaseBranch` Path parameters: - `databaseId` (string, required) - `branchId` (string, required) Responses: - `200` — The branch record. - `401` — Authentication is missing or invalid. - `404` — The resource was not found. - `429` — Too many requests; retry after the indicated delay. CLI: `khotan databases branches get` ### DELETE /api/v1/databases/{databaseId}/branches/{branchId} Delete a database branch Tears down the provider branch and its compute, then soft-deletes the record. Deletion is permanent. Returns 409 branch_has_children when the branch still has child branches; delete the descendants first. Auth: API key required. Operation ID: `deleteDatabaseBranch` Path parameters: - `databaseId` (string, required) - `branchId` (string, required) Responses: - `200` — The branch was deleted. - `401` — Authentication is missing or invalid. - `404` — The resource was not found. - `409` — The branch still has child branches (code branch_has_children). Delete the descendants first. - `429` — Too many requests; retry after the indicated delay. - `502` — Response. CLI: `khotan databases branches delete` ### GET /api/v1/databases/{databaseId}/branches/{branchId}/connection Get a branch connection URI Returns the full Postgres connection URI for a ready branch. The URI grants complete read/write access to the branch; treat it as a secret. Responds 404 until the branch is ready. All schema and row access happens directly over Postgres using this URI — the API never proxies SQL. Auth: API key required. Operation ID: `getDatabaseBranchConnection` Path parameters: - `databaseId` (string, required) - `branchId` (string, required) Responses: - `200` — The connection URI for the ready branch. - `401` — Authentication is missing or invalid. - `404` — The resource was not found. - `429` — Too many requests; retry after the indicated delay. CLI: `khotan databases branches connection` ### POST /api/v1/databases/{databaseId}/branches/{branchId}/rotate-credentials Rotate branch credentials Resets the branch role password through the provider and returns the new connection URI; the previous URI stops authenticating immediately. Rotation drops any live connections or pools still using the old credentials — plan to reconnect. Rotation is idempotent: if a rotation reports a persistence failure, rotating again issues a fresh working connection string. Auth: API key required. Operation ID: `rotateDatabaseBranchCredentials` Path parameters: - `databaseId` (string, required) - `branchId` (string, required) Responses: - `200` — The new connection URI after rotation. - `401` — Authentication is missing or invalid. - `404` — The resource was not found. - `409` — Another rotation is already in progress for this branch; retry shortly. - `429` — Too many requests; retry after the indicated delay. CLI: `khotan databases branches rotate-credentials` ### POST /api/v1/databases/{databaseId}/branches/{branchId}/schema-promotions Plan a database schema promotion Compares a ready branch schema against the production database schema, records a schema-only promotion plan, validates generated SQL on a temporary provider branch, and returns the persisted plan. It never copies branch data to production. Auth: API key required. Operation ID: `planDatabaseSchemaPromotion` Path parameters: - `databaseId` (string, required) - `branchId` (string, required) Responses: - `201` — The persisted promotion plan. Status is ready only when SQL validation passes and no blocked changes exist. - `401` — Authentication is missing or invalid. - `403` — The caller is not permitted to perform this action. - `404` — The resource was not found. - `429` — Too many requests; retry after the indicated delay. CLI: `khotan databases schema-promotions plan` ### GET /api/v1/databases/{databaseId}/schema-promotions/{promotionId} Get a database schema promotion Returns the recorded schema promotion plan, including SQL, summary, blocked changes, and failure state. Auth: API key required. Operation ID: `getDatabaseSchemaPromotion` Path parameters: - `databaseId` (string, required) - `promotionId` (string, required) Responses: - `200` — The schema promotion record. - `401` — Authentication is missing or invalid. - `404` — The resource was not found. - `429` — Too many requests; retry after the indicated delay. CLI: `khotan databases schema-promotions get` ### POST /api/v1/databases/{databaseId}/schema-promotions/{promotionId}/apply Apply a database schema promotion Applies the exact reviewed schema-only promotion SQL to the production database. The stored source and target schema hashes must still match, otherwise the request fails with 409. Auth: API key required. Operation ID: `applyDatabaseSchemaPromotion` Path parameters: - `databaseId` (string, required) - `promotionId` (string, required) Responses: - `200` — The applied promotion record. - `401` — Authentication is missing or invalid. - `404` — The resource was not found. - `409` — The promotion is not ready, the schemas changed after planning, or SQL application failed. - `429` — Too many requests; retry after the indicated delay. CLI: `khotan databases schema-promotions apply`