REST API Reference

The DB9 REST API lets you manage databases, execute SQL, and interact with the platform programmatically. All customer endpoints live under https://api.db9.ai/customer.

For most use cases, the CLI or TypeScript SDK provide a more ergonomic interface. The REST API is ideal for custom integrations, CI/CD pipelines, or languages without an SDK.

Authentication

Most requests require a Bearer token in the Authorization header:

curl -H "Authorization: Bearer $DB9_API_KEY" https://api.db9.ai/customer/databases

Exceptions: POST /customer/anonymous-register requires no credentials. POST /customer/anonymous-refresh authenticates using anonymous_id + anonymous_secret in the request body (no Bearer token).

Obtain tokens via:

db9 token create (CLI)
db9 login --api-key <KEY> (verifies and saves an existing API key locally)
Anonymous bootstrap (/customer/anonymous-register)

Error Responses

All errors return a consistent JSON shape:

{
  "message": "human-readable message describing what went wrong"
}

Status	Meaning
`400`	Bad request — missing or invalid fields
`401`	Unauthorized — missing or invalid token
`403`	Forbidden — token lacks required scope
`404`	Not found — resource does not exist
`409`	Conflict — resource already exists
`422`	Unprocessable — valid JSON but semantic error
`429`	Rate limited — slow down and retry
`500`	Internal server error

Account & Sessions

GET /customer/me

Return the current customer's identity and profile.

curl -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/me

{
  "id": "cus_01h9xxxxxxxxxxxxxxxx",
  "email": "user@example.com",
  "created_at": "2026-01-15T10:00:00Z",
  "status": "active"
}

POST /customer/anonymous-register

Create an anonymous account and return a session token. No credentials required.

curl -X POST https://api.db9.ai/customer/anonymous-register

{
  "anonymous_id": "anon_01h9xxxxxxxxxxxxxxxx",
  "anonymous_secret": "sk_anon_xxxxxxxxxxxxxxxxxxxx",
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2027-01-15T10:00:00Z",
  "is_anonymous": true
}

POST /customer/anonymous-refresh

Refresh an anonymous session token using the customer ID and secret.

Field	Type	Required	Description
`anonymous_id`	string	yes	Anonymous customer ID
`anonymous_secret`	string	yes	Anonymous account secret

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"anonymous_id": "anon_01h9xx", "anonymous_secret": "sk_anon_xx"}' \
  https://api.db9.ai/customer/anonymous-refresh

{ "anonymous_id": "anon_01h9xxxxxxxxxxxxxxxx", "anonymous_secret": "sk_anon_xxxxxxxxxxxxxxxxxxxx" }

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2027-02-15T10:00:00Z"
}

POST /customer/claim

Upgrade an anonymous account to a verified identity using an Auth0 id_token. Requires a Bearer token.

curl -X POST -H "Authorization: Bearer $DB9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id_token": "<Auth0 id_token>"}' \
  https://api.db9.ai/customer/claim

{ "id_token": "<Auth0 id_token>" }

{
  "id": "cus_01h9xxxxxxxxxxxxxxxx",
  "email": "user@example.com",
  "claimed": true
}

POST /customer/adopt-anonymous-databases/preflight

Pre-check eligibility and quotas before adopting databases from an anonymous account.

Field	Type	Required	Description
`anonymous_customer_id`	string	yes	Customer ID of the anonymous account
`anonymous_secret`	string	yes	Secret for the anonymous account

curl -X POST -H "Authorization: Bearer $DB9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"anonymous_customer_id": "anon_01h9xx", "anonymous_secret": "sk_anon_xx"}' \
  https://api.db9.ai/customer/adopt-anonymous-databases/preflight

{
  "anonymous_customer_id": "anon_01h9xxxxxxxxxxxxxxxx",
  "anonymous_secret": "sk_anon_xxxxxxxxxxxxxxxxxxxx"
}

{
  "databases": [
    { "id": "db_01h9xxxxxxxxxxxxxxxx", "name": "myapp", "state": "ACTIVE" }
  ],
  "quota_ok": true,
  "current_count": 1,
  "database_limit": 10
}

POST /customer/adopt-anonymous-databases

Transfer databases from an anonymous account to your authenticated account.

Field	Type	Required	Description
`anonymous_customer_id`	string	yes	Customer ID of the anonymous account
`anonymous_secret`	string	yes	Secret for the anonymous account
`database_ids`	string[]	yes	List of database IDs to adopt (max 100)
`idempotency_key`	string	yes	Unique key for idempotent retries

curl -X POST -H "Authorization: Bearer $DB9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"anonymous_customer_id": "anon_01h9xx", "anonymous_secret": "sk_anon_xx", "database_ids": ["db_01h9xx"], "idempotency_key": "adopt-2026-01-15"}' \
  https://api.db9.ai/customer/adopt-anonymous-databases

{
  "anonymous_customer_id": "anon_01h9xxxxxxxxxxxxxxxx",
  "anonymous_secret": "sk_anon_xxxxxxxxxxxxxxxxxxxx",
  "database_ids": ["db_01h9xxxxxxxxxxxxxxxx"],
  "idempotency_key": "adopt-2026-01-15"
}

{
  "transferred": ["db_01h9xxxxxxxxxxxxxxxx"],
  "skipped": [],
  "total_transferred": 1
}

Databases

POST /customer/databases

Create a new database. Returns credentials and connection string immediately.

Field	Type	Required	Description
`name`	string	yes	Database name
`region`	string	no	Deployment region
`admin_password`	string	no	Admin password (auto-generated if omitted)
`project_id`	string	no	Project ID to group databases under

curl -X POST -H "Authorization: Bearer $DB9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "myapp", "region": "us-east-1"}' \
  https://api.db9.ai/customer/databases

{
  "name": "myapp",
  "region": "us-east-1"
}

{
  "id": "db_01h9xxxxxxxxxxxxxxxx",
  "name": "myapp",
  "region": "us-east-1",
  "state": "ready",
  "connection_string": "postgresql://admin:password@db-01h9xx.db9.ai:5433/myapp",
  "admin_user": "admin",
  "admin_password": "generated-password",
  "created_at": "2026-01-15T10:00:00Z"
}

GET /customer/databases

List all databases in your account.

curl -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases

[
  {
    "id": "db_01h9xxxxxxxxxxxxxxxx",
    "name": "myapp",
    "region": "us-east-1",
    "state": "ready",
    "created_at": "2026-01-15T10:00:00Z"
  }
]

GET /customer/databases/{database_id}

Get database details including connection string and current state.

curl -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx

{
  "id": "db_01h9xxxxxxxxxxxxxxxx",
  "name": "myapp",
  "region": "us-east-1",
  "state": "ready",
  "connection_string": "postgresql://admin:password@db-01h9xx.db9.ai:5433/myapp",
  "created_at": "2026-01-15T10:00:00Z"
}

DELETE /customer/databases/{database_id}

Permanently delete a database. This action is irreversible.

curl -X DELETE -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx

{ "message": "Database disabled" }

POST /customer/databases/{database_id}/reset-password

Reset the admin password for a database and return the new credentials.

curl -X POST -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/reset-password

{
  "admin_user": "admin",
  "admin_password": "new-generated-password",
  "connection_string": "postgresql://admin:new-generated-password@db-01h9xx.db9.ai:5433/postgres"
}

GET /customer/databases/{database_id}/credentials

Retrieve stored admin credentials for a database.

curl -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/credentials

{
  "admin_user": "admin",
  "admin_password": "stored-password",
  "connection_string": "postgresql://admin:stored-password@db-01h9xx.db9.ai:5432/myapp"
}

GET /customer/databases/{database_id}/schema

Get the database schema — tables, columns, and types.

curl -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/schema

{
  "tables": [
    {
      "schema": "public",
      "name": "users",
      "columns": [
        { "name": "id", "type": "integer", "nullable": false },
        { "name": "email", "type": "text", "nullable": false },
        { "name": "created_at", "type": "timestamp", "nullable": true }
      ]
    }
  ],
  "views": [
    { "name": "active_users", "schema": "public" }
  ]
}

GET /customer/databases/{database_id}/observability

Get database metrics and slow query samples.

curl -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/observability

{
  "summary": {
    "tps": 42.5,
    "latency_avg_ms": 3.2,
    "latency_p99_ms": 18.7,
    "active_connections": 3,
    "database_storage_bytes": 10485760,
    "fs_logical_bytes": 2097152
  },
  "samples": [
    {
      "query": "SELECT * FROM events WHERE user_id = $1",
      "sample_count": 120,
      "error_count": 0,
      "latency_avg_ms": 245.0,
      "latency_p99_ms": 480.0,
      "latency_max_ms": 612.0,
      "last_seen_ms_ago": 5000
    }
  ]
}

Batch Create

POST /customer/databases/batch

Create multiple databases in a single request. Each item in the array is created independently — partial success is possible.

Field	Type	Required	Description
`databases`	array	yes	Array of `{ name, region?, admin_password? }` items
`project_id`	string	no	Project ID to assign all databases to

curl -X POST -H "Authorization: Bearer $DB9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"databases": [{"name": "shard-1"}, {"name": "shard-2", "region": "us-east-1"}], "project_id": "proj-abc"}' \
  https://api.db9.ai/customer/databases/batch

{
  "databases": [
    { "name": "shard-1" },
    { "name": "shard-2", "region": "us-east-1" }
  ],
  "project_id": "proj-abc"
}

{
  "created": [
    { "id": "db_01...", "name": "shard-1", "state": "ready", ... },
    { "id": "db_02...", "name": "shard-2", "state": "ready", ... }
  ],
  "failed": [],
  "total_requested": 2,
  "total_created": 2
}

SQL Execution

POST /customer/databases/{database_id}/sql

Execute a SQL query and return results as column names + row arrays.

Field	Type	Required	Description
`query`	string	no	Inline SQL query
`file_content`	string	no	SQL content (alternative to `query`)

Provide either query or file_content, not both.

curl -X POST -H "Authorization: Bearer $DB9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT id, email FROM users LIMIT 2"}' \
  https://api.db9.ai/customer/databases/db_01h9xx/sql

{ "query": "SELECT id, email FROM users LIMIT 2" }

{
  "columns": [
    { "name": "id", "data_type": "integer" },
    { "name": "email", "data_type": "text" }
  ],
  "rows": [
    [1, "alice@example.com"],
    [2, "bob@example.com"]
  ],
  "row_count": 2,
  "command": "SELECT"
}

POST /customer/databases/{database_id}/dump

Export schema and data as SQL. Pass {"ddl_only": true} for schema-only export.

curl -X POST -H "Authorization: Bearer $DB9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ddl_only": false}' \
  https://api.db9.ai/customer/databases/db_01h9xx/dump

{ "ddl_only": false }

{
  "sql": "-- DB9 dump\nCREATE TABLE users (...);\nINSERT INTO users VALUES (...);",
  "object_count": 3
}

Connect Tokens & Keys

POST /customer/databases/{database_id}/connect-token

Mint a short-lived JWT connect token. Pass {"role": "admin"} in the body.

curl -X POST -H "Authorization: Bearer $DB9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}' \
  https://api.db9.ai/customer/databases/db_01h9xx/connect-token

{ "role": "admin" }

{
  "host": "db-01h9xx.db9.ai",
  "port": 5433,
  "database": "postgres",
  "user": "tenant_id.admin",
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "fs_websocket_url": "wss://fs.db9.ai/ws",
  "expires_in_seconds": 900,
  "expires_at": "2026-01-15T11:00:00Z",
  "tls": "not_enforced"
}

POST /customer/databases/{database_id}/connect-keys

Create a long-lived DB Connect Key. The key value is only returned once.

curl -X POST -H "Authorization: Bearer $DB9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin", "scopes": []}' \
  https://api.db9.ai/customer/databases/db_01h9xx/connect-keys

{ "role": "admin", "scopes": [] }

{
  "id": "ck_01h9xxxxxxxxxxxxxxxx",
  "name": "ci",
  "connect_key": "db9ck_xxxxxxxxxxxxxxxxxxxx",
  "role": "admin",
  "scopes": [],
  "created_at": "2026-01-15T10:00:00Z"
}

GET /customer/databases/{database_id}/connect-keys

List all DB Connect Keys (metadata only — key values are never returned).

curl -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/connect-keys

[
  {
    "id": "ck_01h9xxxxxxxxxxxxxxxx",
    "name": "ci",
    "role": "admin",
    "scopes": [],
    "created_at": "2026-01-15T10:00:00Z",
    "expires_at": "2027-01-15T10:00:00Z"
  }
]

DELETE /customer/databases/{database_id}/connect-keys/{key_id}

Revoke a DB Connect Key immediately.

curl -X DELETE -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/connect-keys/ck_01h9xx

{ "message": "Connect key revoked" }

Auth Configuration

GET /customer/databases/{database_id}/auth-config

Get the browser data-plane authentication configuration. Default auth_mode is byo_jwt.

curl -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/auth-config

{
  "auth_mode": "byo_jwt",
  "byo_jwt": {
    "jwks_url": "https://example.com/.well-known/jwks.json",
    "audience": "my-app",
    "issuer": "https://example.com",
    "subject_claim": "sub",
    "claims_allowlist": [],
    "claims_max_bytes": 4096
  },
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-01-15T10:00:00Z"
}

PUT /customer/databases/{database_id}/auth-config

Create or update the browser data-plane authentication configuration.

Field	Type	Required	Description
`auth_mode`	string	no	Authentication mode (e.g. `byo_jwt`)
`byo_jwt`	object	no	Bring-your-own JWT configuration

curl -X PUT -H "Authorization: Bearer $DB9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auth_mode": "byo_jwt", "byo_jwt": {"jwks_url": "https://example.com/.well-known/jwks.json", "audience": "my-app", "issuer": "https://example.com"}}' \
  https://api.db9.ai/customer/databases/db_01h9xx/auth-config

{
  "auth_mode": "byo_jwt",
  "byo_jwt": {
    "jwks_url": "https://example.com/.well-known/jwks.json",
    "audience": "my-app",
    "issuer": "https://example.com",
    "subject_claim": "sub",
    "claims_allowlist": [],
    "claims_max_bytes": 4096
  }
}

{
  "auth_mode": "byo_jwt",
  "byo_jwt": {
    "jwks_url": "https://example.com/.well-known/jwks.json",
    "audience": "my-app",
    "issuer": "https://example.com",
    "subject_claim": "sub",
    "claims_allowlist": [],
    "claims_max_bytes": 4096
  },
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-01-15T10:00:00Z"
}

Publishable Keys

POST /customer/databases/{database_id}/publishable-keys

Create a publishable key for browser/client-side data access. Key value returned once only.

Field	Type	Required	Description
`name`	string	no	Key name
`allowed_origins`	string[]	no	CORS allowed origins
`exposed_schemas`	string[]	no	Schemas accessible via this key
`exposed_tables`	string[]	no	Tables accessible via this key
`rate_limit`	object	no	Rate limiting (`rps`, `burst`)
`expires_in_days`	number	no	Key expiration in days

curl -X POST -H "Authorization: Bearer $DB9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "web-app", "allowed_origins": ["https://example.com"], "exposed_schemas": ["public"]}' \
  https://api.db9.ai/customer/databases/db_01h9xx/publishable-keys

{
  "name": "web-app",
  "allowed_origins": ["https://example.com"],
  "exposed_schemas": ["public"],
  "exposed_tables": ["posts", "comments"],
  "rate_limit": { "rps": 100, "burst": 200 },
  "expires_in_days": 90
}

{
  "id": "pk_01h9xxxxxxxxxxxxxxxx",
  "publishable_key": "db9pk_xxxxxxxxxxxxxxxxxxxx",
  "name": "web-app",
  "allowed_origins": ["https://example.com"],
  "exposed_schemas": ["public"],
  "exposed_tables": ["posts", "comments"],
  "expires_at": "2026-04-15T10:00:00Z",
  "created_at": "2026-01-15T10:00:00Z"
}

GET /customer/databases/{database_id}/publishable-keys

List all publishable keys (metadata only — key values are never returned).

curl -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/publishable-keys

[
  {
    "id": "pk_01h9xxxxxxxxxxxxxxxx",
    "name": "web-app",
    "allowed_origins": ["https://example.com"],
    "exposed_schemas": ["public"],
    "exposed_tables": ["posts", "comments"],
    "expires_at": "2026-04-15T10:00:00Z",
    "created_at": "2026-01-15T10:00:00Z"
  }
]

DELETE /customer/databases/{database_id}/publishable-keys/{key_id}

Revoke a publishable key immediately.

curl -X DELETE -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/publishable-keys/ck_01h9xx

{ "message": "Publishable key revoked" }

Service Keys

POST /customer/databases/{database_id}/service-keys

Create a service key for server-side operations (CRUD only — consumption API not yet implemented). Key value returned once only.

curl -X POST -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/service-keys

{
  "id": "sk_01h9xxxxxxxxxxxxxxxx",
  "name": "service-key",
  "service_key": "db9sk_xxxxxxxxxxxxxxxxxxxx",
  "created_at": "2026-01-15T10:00:00Z"
}

GET /customer/databases/{database_id}/service-keys

List all service keys (metadata only).

curl -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/service-keys

[
  {
    "id": "sk_01h9xxxxxxxxxxxxxxxx",
    "name": "service-key",
    "created_at": "2026-01-15T10:00:00Z",
    "expires_at": "2027-01-15T10:00:00Z"
  }
]

DELETE /customer/databases/{database_id}/service-keys/{key_id}

Revoke a service key immediately.

curl -X DELETE -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/service-keys/ck_01h9xx

{ "message": "Service key revoked" }

Database Users

GET /customer/databases/{database_id}/users

List all PostgreSQL users in the database.

curl -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/users

[
  { "name": "admin", "is_superuser": true, "can_login": true, "can_create_db": true, "can_create_role": true },
  { "name": "app_user", "is_superuser": false, "can_login": true, "can_create_db": false, "can_create_role": false }
]

POST /customer/databases/{database_id}/users

Create a new PostgreSQL user. Returns the generated password (returned once only).

curl -X POST -H "Authorization: Bearer $DB9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "app_user", "password": "playground123"}' \
  https://api.db9.ai/customer/databases/db_01h9xx/users

{ "username": "app_user" }

{
  "message": "User 'app_user' created",
  "username": "app_user",
  "password": "generated-password",
  "connection_string": "postgresql://tenant_id.app_user@db-01h9xx.db9.ai:5433/postgres",
  "connection_string_with_password": "postgresql://tenant_id.app_user:generated-password@db-01h9xx.db9.ai:5433/postgres"
}

DELETE /customer/databases/{database_id}/users/{username}

Delete a PostgreSQL user from the database.

curl -X DELETE -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/users/app_user

{ "message": "User 'app_user' deleted" }

Migrations

GET /customer/databases/{database_id}/migrations

List all applied migrations with names, checksums, and timestamps.

curl -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/migrations

[
  {
    "name": "add_users_table",
    "checksum": "sha256:abc123",
    "applied_at": "2026-01-15T10:00:00Z",
    "sql_preview": "CREATE TABLE users (id SERIAL PRIMARY KEY, email TEXT NOT NULL);"
  }
]

POST /customer/databases/{database_id}/migrations

Apply a migration. Migrations are idempotent by name — re-applying the same name returns 409.

Field	Type	Required	Description
`name`	string	yes	Migration name (must be unique)
`sql`	string	yes	SQL to execute
`checksum`	string	no	Content digest for integrity verification

curl -X POST -H "Authorization: Bearer $DB9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "add_users_table", "sql": "CREATE TABLE users (id SERIAL PRIMARY KEY, email TEXT NOT NULL);"}' \
  https://api.db9.ai/customer/databases/db_01h9xx/migrations

{
  "name": "add_users_table",
  "sql": "CREATE TABLE users (id SERIAL PRIMARY KEY, email TEXT NOT NULL);"
}

{
  "status": "applied",
  "name": "add_users_table"
}

Branching

POST /customer/databases/{database_id}/branch

Create a branch — a full copy of the database schema (and optionally data) at a point in time.

Field	Type	Required	Description
`name`	string	yes	Branch name
`snapshot_at`	string	no	RFC 3339 UTC timestamp for point-in-time branching (omit to branch from current state)

curl -X POST -H "Authorization: Bearer $DB9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "feature-branch"}' \
  https://api.db9.ai/customer/databases/db_01h9xx/branch

{
  "name": "feature-branch",
  "snapshot_at": "2026-03-22T06:00:00Z"
}

{
  "id": "db_01h9yyyyyyyyyyyyyyyy",
  "name": "feature-branch",
  "parent_database_id": "db_01h9xxxxxxxxxxxxxxxx",
  "region": "us-east-1",
  "state": "ready",
  "connection_string": "postgresql://admin:password@db-01h9yy.db9.ai:5433/feature-branch",
  "created_at": "2026-01-15T10:00:00Z"
}

Backups & Restores

POST /customer/databases/{database_id}/backups

Create a backup of a database.

Field	Type	Required	Description
`label`	string	no	Human-readable label for the backup

curl -X POST -H "Authorization: Bearer $DB9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "pre-migration-snap"}' \
  https://api.db9.ai/customer/databases/db_01h9xx/backups

{
  "label": "pre-migration-snap"
}

{
  "id": "bkp_01...",
  "database_id": "db_01h9xxxxxxxxxxxxxxxx",
  "state": "creating",
  "label": "pre-migration-snap",
  "created_at": "2026-04-09T10:00:00Z"
}

GET /customer/databases/{database_id}/backups

List all backups for a database.

curl -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/backups

GET /customer/databases/{database_id}/backups/{backup_id}

Get details of a specific backup.

curl -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/backups/bkp_01h9xx

DELETE /customer/databases/{database_id}/backups/{backup_id}

Delete a backup.

curl -X DELETE -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/backups/bkp_01h9xx

POST /customer/restores

Restore a database from a backup. Creates a new database with the restored data.

Field	Type	Required	Description
`backup_id`	string	yes	ID of the backup to restore from
`target_name`	string	yes	Name for the restored database
`idempotency_key`	string	no	Idempotency key for safe retries

curl -X POST -H "Authorization: Bearer $DB9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"backup_id": "bkp_01h9xx", "target_name": "myapp-restored"}' \
  https://api.db9.ai/customer/restores

{
  "backup_id": "bkp_01...",
  "target_name": "myapp-restored"
}

GET /customer/restores/{restore_id}

Check the status of a restore operation.

curl -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/restores/rst_01h9xx

Filesystem

POST /customer/databases/{database_id}/fs-connect

Obtain database credentials and filesystem WebSocket URL for fs9 access.

curl -X POST -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/fs-connect

{
  "database_id": "db_01h9xxxxxxxxxxxxxxxx",
  "database_name": "myapp",
  "admin_user": "admin",
  "admin_password": "stored-password",
  "connection_string": "postgresql://tenant_id.admin@db-01h9xx.db9.ai:5433/postgres",
  "fs_websocket_url": "wss://fs.db9.ai/ws",
  "connection_string_with_password": "postgresql://tenant_id.admin:stored-password@db-01h9xx.db9.ai:5433/postgres"
}

Functions

POST /customer/databases/{database_id}/functions

Deploy a serverless function. Functions run in an isolated environment with optional database access, secrets, and filesystem scope.

Field	Type	Required	Description
`name`	string	yes	Function name
`entrypoint`	string	yes	Function entrypoint (e.g. `index.handler`)
`bundle_ref`	string	yes	Bundle storage reference
`bundle_digest`	string	no	Bundle content digest for integrity
`run_as`	string	no	Database role to execute as
`bypass_rls`	boolean	no	Bypass Row-Level Security
`limits`	object	no	Execution limits
`network_allowlist`	string[]	no	Allowed outbound network destinations
`fs9_scope`	object	no	Filesystem access scope
`secret_bindings`	string[]	no	Secrets to bind to the function
`cron_schedule`	string	no	Cron expression for scheduled execution
`visibility`	string	no	`"public"` (callable via publishable key) or `"private"` (default)

curl -X POST -H "Authorization: Bearer $DB9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-function", "entrypoint": "index.handler", "bundle_ref": "s3://bucket/bundle.zip"}' \
  https://api.db9.ai/customer/databases/db_01h9xx/functions

{
  "name": "my-function",
  "entrypoint": "index.handler",
  "bundle_ref": "s3://bucket/bundle.zip",
  "bundle_digest": "sha256:abc123",
  "run_as": "app_user",
  "bypass_rls": false,
  "limits": { "timeout_ms": 30000 },
  "network_allowlist": ["https://api.example.com"],
  "fs9_scope": { "read": ["/data"], "write": [] },
  "secret_bindings": ["API_KEY"],
  "cron_schedule": "*/5 * * * *"
}

{
  "function": {
    "id": "fn_01h9xxxxxxxxxxxxxxxx",
    "name": "my-function",
    "enabled": true,
    "visibility": "private",
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-01-15T10:00:00Z"
  },
  "version": {
    "id": "ver_01h9xxxxxxxxxxxxxxxx",
    "version": 1,
    "entrypoint": "index.handler",
    "bundle_ref": "s3://bucket/bundle.zip",
    "bundle_digest": "sha256:abc123",
    "run_as": "app_user",
    "bypass_rls": false,
    "created_at": "2026-01-15T10:00:00Z"
  }
}

GET /customer/databases/{database_id}/functions

List all deployed functions.

curl -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/functions

[
  {
    "id": "fn_01h9xxxxxxxxxxxxxxxx",
    "name": "my-function",
    "enabled": true,
    "visibility": "private",
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-01-15T10:00:00Z"
  }
]

POST /customer/databases/{database_id}/functions/{function_id}/invoke

Invoke a function synchronously and return the output.

Field	Type	Required	Description
`input`	object	no	Function input payload
`idempotency_key`	string	no	Unique key for idempotent invocations

curl -X POST -H "Authorization: Bearer $DB9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"user_id": "u_123"}}' \
  https://api.db9.ai/customer/databases/db_01h9xx/functions/fn_01h9xx/invoke

{ "input": { "user_id": "u_123" } }

{
  "run_id": "run_01h9xxxxxxxxxxxxxxxx",
  "function_id": "fn_01h9xxxxxxxxxxxxxxxx",
  "version_id": "ver_01h9xxxxxxxxxxxxxxxx",
  "status": "completed",
  "result_json": "{\"result\":\"ok\"}"
}

GET /customer/databases/{database_id}/functions/{function_id}/runs

List all runs for a function, ordered by most recent first.

curl -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/functions/fn_01h9xx/runs

[
  {
    "id": "run_01h9xxxxxxxxxxxxxxxx",
    "function_id": "fn_01h9xxxxxxxxxxxxxxxx",
    "version_id": "ver_01h9xxxxxxxxxxxxxxxx",
    "trigger_type": "invoke",
    "status": "completed",
    "run_as": "app_user",
    "attempt": 1,
    "created_at": "2026-01-15T10:00:00Z"
  }
]

GET /customer/databases/{database_id}/functions/{function_id}/runs/{run_id}

Get details for a specific function run including output and timing.

curl -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/functions/fn_01h9xx/runs/run_01h9xx

{
  "id": "run_01h9xxxxxxxxxxxxxxxx",
  "function_id": "fn_01h9xxxxxxxxxxxxxxxx",
  "version_id": "ver_01h9xxxxxxxxxxxxxxxx",
  "trigger_type": "invoke",
  "status": "completed",
  "run_as": "app_user",
  "attempt": 1,
  "created_at": "2026-01-15T10:00:00Z"
}

GET /customer/databases/{database_id}/functions/{function_id}/runs/{run_id}/logs

Get structured log output for a specific function run.

curl -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/functions/fn_01h9xx/runs/run_01h9xx/logs

{
  "run_id": "run_01h9xxxxxxxxxxxxxxxx",
  "logs": "2026-01-15T10:00:00.010Z [info] Function started\n2026-01-15T10:00:00.140Z [info] Function completed"
}

Secrets

GET /customer/databases/{database_id}/secrets

List all secret names and timestamps. Secret values are never returned.

curl -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/secrets

[
  {
    "name": "API_KEY",
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-01-20T08:00:00Z"
  }
]

POST /customer/databases/{database_id}/secrets

Create a secret. The value is encrypted at rest and never returned after creation.

Field	Type	Required	Description
`name`	string	yes	Secret name (alphanumeric and underscores)
`value`	string	yes	Secret value (encrypted at rest)

curl -X POST -H "Authorization: Bearer $DB9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "API_KEY", "value": "sk-live-xxxxxxxxxxxx"}' \
  https://api.db9.ai/customer/databases/db_01h9xx/secrets

{ "name": "API_KEY", "value": "sk-live-xxxxxxxxxxxx" }

{
  "name": "API_KEY",
  "created_at": "2026-01-15T10:00:00Z"
}

PUT /customer/databases/{database_id}/secrets/{secret_name}

Update an existing secret's value.

Field	Type	Required	Description
`value`	string	yes	New secret value

curl -X PUT -H "Authorization: Bearer $DB9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value": "sk-live-new-xxxxxxxxxxxx"}' \
  https://api.db9.ai/customer/databases/db_01h9xx/secrets/API_KEY

{ "value": "sk-live-new-xxxxxxxxxxxx" }

{
  "name": "API_KEY",
  "updated_at": "2026-02-01T09:00:00Z"
}

DELETE /customer/databases/{database_id}/secrets/{secret_name}

Delete a secret permanently.

curl -X DELETE -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/databases/db_01h9xx/secrets/API_KEY

Response: 204 No Content — empty body.

API Tokens

POST /customer/tokens

Create an API token. The token value is returned once only — store it securely.

Field	Type	Required	Description
`name`	string	no	Token name
`expires_in_days`	integer	no	Expiry in days (default: 365)
`scope_json`	string	no	JSON string scoping token to specific databases, e.g. `{"databases":[{"id":"<id>","access":"ro"}]}`

curl -X POST -H "Authorization: Bearer $DB9_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-token", "expires_in_days": 365}' \
  https://api.db9.ai/customer/tokens

{
  "name": "ci-token",
  "expires_in_days": 365
}

{
  "id": "tok_01h9xxxxxxxxxxxxxxxx",
  "name": "ci-token",
  "token": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "expires_at": "2027-01-15T10:00:00Z",
  "created_at": "2026-01-15T10:00:00Z"
}

GET /customer/tokens

List all API tokens (metadata only — token values are never returned).

curl -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/tokens

[
  {
    "id": "tok_01h9xxxxxxxxxxxxxxxx",
    "name": "ci-token",
    "expires_at": "2027-01-15T10:00:00Z",
    "created_at": "2026-01-15T10:00:00Z"
  }
]

DELETE /customer/tokens/{token_id}

Revoke an API token immediately. All requests using this token will be rejected.

curl -X DELETE -H "Authorization: Bearer $DB9_API_KEY" \
  https://api.db9.ai/customer/tokens/tok_01h9xx

{ "message": "Token revoked" }

Next Steps

Error Codes — Full HTTP status code reference with causes and resolution
CLI Reference — Command-line interface
TypeScript SDK — Server-side SDK wrapping this API
Browser SDK — Client-side data access
Connect — Connection strings and drivers