Skip to content
Discord Get Started

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

Section titled “Authentication”

All requests require a Bearer token in the Authorization header:

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

Obtain tokens via:

  • db9 token create (CLI)
  • db9 login --api-key <KEY> (sets DB9_API_KEY)
  • Anonymous bootstrap (/customer/anonymous-register)

Account & Sessions

Section titled “Account & Sessions”
MethodPathDescription
GET/customer/meCurrent customer identity and profile
POST/customer/anonymous-registerCreate anonymous account and session
POST/customer/anonymous-refreshRefresh anonymous session tokens
POST/customer/claimUpgrade anonymous account with Auth0 id_token
POST/customer/adopt-anonymous-databases/preflightPre-check database adoption eligibility and quotas
POST/customer/adopt-anonymous-databasesTransfer databases from anonymous account

Anonymous Refresh

Section titled “Anonymous Refresh”
FieldTypeRequiredDescription
anonymous_idstringyesAnonymous customer ID

Adopt Request Fields

Section titled “Adopt Request Fields”

Preflight (POST /customer/adopt-anonymous-databases/preflight):

FieldTypeRequiredDescription
anonymous_customer_idstringyesCustomer ID of the anonymous account
anonymous_secretstringyesSecret for the anonymous account

Execute (POST /customer/adopt-anonymous-databases):

FieldTypeRequiredDescription
anonymous_customer_idstringyesCustomer ID of the anonymous account
anonymous_secretstringyesSecret for the anonymous account
database_idsstring[]yesList of database IDs to adopt (max 100)
idempotency_keystringyesUnique key for idempotent retries

Databases

Section titled “Databases”
MethodPathDescription
POST/customer/databasesCreate a database
GET/customer/databasesList all databases
GET/customer/databases/{database_id}Get database details and connection info
DELETE/customer/databases/{database_id}Delete a database
POST/customer/databases/{database_id}/reset-passwordReset admin password
GET/customer/databases/{database_id}/credentialsGet stored admin credentials
GET/customer/databases/{database_id}/schemaGet database schema (tables, columns, types)
GET/customer/databases/{database_id}/observabilityGet metrics and query samples

Create Database

Section titled “Create Database”
JSON
{
  "name": "myapp",
  "region": "us-east-1"
}
FieldTypeRequiredDescription
namestringyesDatabase name
regionstringnoDeployment region
admin_passwordstringnoAdmin password (auto-generated if omitted)

SQL Execution

Section titled “SQL Execution”
MethodPathDescription
POST/customer/databases/{database_id}/sqlExecute SQL query
POST/customer/databases/{database_id}/dumpExport schema and data as SQL ({"ddl_only": true} for schema only)

Execute SQL

Section titled “Execute SQL”
JSON
{
  "query": "SELECT * FROM users"
}
FieldTypeRequiredDescription
querystringnoInline SQL query
file_contentstringnoSQL content (alternative to query)

Provide either query or file_content, not both.

Connect Tokens & Keys

Section titled “Connect Tokens & Keys”
MethodPathDescription
POST/customer/databases/{database_id}/connect-tokenMint short-lived connect token JWT ({"role": "admin"})
POST/customer/databases/{database_id}/connect-keysCreate long-lived DB Connect Key ({"role": "admin", "scopes": [...]})
GET/customer/databases/{database_id}/connect-keysList DB Connect Keys (metadata only)
DELETE/customer/databases/{database_id}/connect-keys/{key_id}Revoke a DB Connect Key

Auth Configuration

Section titled “Auth Configuration”
MethodPathDescription
GET/customer/databases/{database_id}/auth-configGet browser data-plane auth config
PUT/customer/databases/{database_id}/auth-configUpsert browser data-plane auth config

Upsert Auth Config

Section titled “Upsert Auth Config”
JSON
{
  "auth_mode": "byo_jwt",
  "byo_jwt": {
    "jwks_url": "https://example.com/.well-known/jwks.json",
    "audience": "my-app",
    "issuer": "https://example.com"
  }
}
FieldTypeRequiredDescription
auth_modestringnoAuthentication mode (e.g. byo_jwt)
byo_jwtobjectnoBring-your-own JWT configuration

Publishable Keys

Section titled “Publishable Keys”
MethodPathDescription
POST/customer/databases/{database_id}/publishable-keysCreate publishable browser key
GET/customer/databases/{database_id}/publishable-keysList publishable keys (metadata only)
DELETE/customer/databases/{database_id}/publishable-keys/{key_id}Revoke a publishable key

Create Publishable Key

Section titled “Create Publishable Key”
JSON
{
  "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
}
FieldTypeRequiredDescription
namestringnoKey name
allowed_originsstring[]noCORS allowed origins
exposed_schemasstring[]noSchemas accessible via this key
exposed_tablesstring[]noTables accessible via this key
rate_limitobjectnoRate limiting (rps, burst)
expires_in_daysnumbernoKey expiration in days

Service Keys

Section titled “Service Keys”
MethodPathDescription
POST/customer/databases/{database_id}/service-keysCreate service key for server-side access
GET/customer/databases/{database_id}/service-keysList service keys (metadata only)
DELETE/customer/databases/{database_id}/service-keys/{key_id}Revoke a service key

Database Users

Section titled “Database Users”
MethodPathDescription
GET/customer/databases/{database_id}/usersList database users
POST/customer/databases/{database_id}/usersCreate a database user
DELETE/customer/databases/{database_id}/users/{username}Delete a database user

Migrations

Section titled “Migrations”
MethodPathDescription
GET/customer/databases/{database_id}/migrationsList applied migrations
POST/customer/databases/{database_id}/migrationsApply a migration ({"name": "...", "sql": "...", "checksum": "..."})

Branching

Section titled “Branching”
MethodPathDescription
POST/customer/databases/{database_id}/branchCreate a branch (schema copy)

Create Branch

Section titled “Create Branch”
JSON
{
  "name": "feature-branch",
  "snapshot_at": "2026-03-22T06:00:00Z"
}
FieldTypeRequiredDescription
namestringyesBranch name
snapshot_atstringnoRFC 3339 UTC timestamp for point-in-time branching (omit to branch from current state)

Filesystem

Section titled “Filesystem”
MethodPathDescription
POST/customer/databases/{database_id}/fs-connectObtain filesystem WebSocket connection details

Functions

Section titled “Functions”
MethodPathDescription
POST/customer/databases/{database_id}/functionsDeploy a function (see fields below)
GET/customer/databases/{database_id}/functionsList deployed functions
POST/customer/databases/{database_id}/functions/{function_id}/invokeInvoke a function ({"input": {...}})
GET/customer/databases/{database_id}/functions/{function_id}/runsList function runs
GET/customer/databases/{database_id}/functions/{function_id}/runs/{run_id}Get function run details
GET/customer/databases/{database_id}/functions/{function_id}/runs/{run_id}/logsGet function run logs

Create Function

Section titled “Create Function”
JSON
{
  "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 * * * *"
}
FieldTypeRequiredDescription
namestringyesFunction name
entrypointstringyesFunction entrypoint (e.g. index.handler)
bundle_refstringyesBundle storage reference
bundle_digeststringnoBundle content digest for integrity
run_asstringnoDatabase role to execute as
bypass_rlsbooleannoBypass Row-Level Security
limitsobjectnoExecution limits
network_allowliststring[]noAllowed outbound network destinations
fs9_scopeobjectnoFilesystem access scope
secret_bindingsstring[]noSecrets to bind to the function
cron_schedulestringnoCron expression for scheduled execution

Invoke Function

Section titled “Invoke Function”
FieldTypeRequiredDescription
inputobjectnoFunction input payload
idempotency_keystringnoUnique key for idempotent invocations

API Tokens

Section titled “API Tokens”
MethodPathDescription
POST/customer/tokensCreate API token
GET/customer/tokensList API tokens
DELETE/customer/tokens/{token_id}Revoke a token
Section titled “Related Docs”