Databases

/api/v1 operations for databases. See HTTP 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