REST API
Every endpoint is under /v1 and needs Authorization: Bearer <token>. {db} and {branch} take a name or an id. The machine-readable document is served at /v1/openapi.json and committed as apps/engine/openapi.json.
- Errors are
application/problem+jsonwith a stablecode; see Error codes. - Values in rows and parameters use the typed encoding in Value encoding.
- Lists take
limit(1 to 200, default 50) andcursor, and returndataandnext_cursor(empty on the last page). - Create endpoints accept an
Idempotency-Keyheader: a retry with the same key returns the first response. - Every response carries
X-Request-Id.
Databases
Section titled “Databases”List databases
Section titled “List databases”GET /v1/databases
| Parameter | In | Type | Description |
|---|---|---|---|
limit |
query | integer | Most items to return. |
cursor |
query | string | The next_cursor from the previous page. |
Response 200:
| Field | Type | Description |
|---|---|---|
data (required) |
DatabaseOut[] | |
next_cursor (required) |
string | Pass as cursor for the next page; empty on the last page. |
Create a database
Section titled “Create a database”POST /v1/databases
| Parameter | In | Type | Description |
|---|---|---|---|
Idempotency-Key |
header | string | Retrying with the same key returns the first response instead of creating twice. |
Request body:
| Field | Type | Description |
|---|---|---|
name (required) |
string | Lowercase letters, digits and hyphens. |
Response 201:
| Field | Type | Description |
|---|---|---|
branch_count (required) |
integer | |
created_at (required) |
string | |
default_branch (required) |
string | Name of the default branch. |
default_branch_id (required) |
string | |
deleted_at (required) |
string or null | When it went to the trash, or null. |
id (required) |
string | |
last_activity_at (required) |
string or null | Start of the last minute with a query, or null. |
name (required) |
string | |
purge_after (required) |
string or null | When a trashed database is removed for good, or null. |
size_bytes (required) |
integer | Space all branches take on disk. |
updated_at (required) |
string |
Get a database
Section titled “Get a database”GET /v1/databases/{db}
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | Database name or id. |
Response 200:
| Field | Type | Description |
|---|---|---|
branch_count (required) |
integer | |
created_at (required) |
string | |
default_branch (required) |
string | Name of the default branch. |
default_branch_id (required) |
string | |
deleted_at (required) |
string or null | When it went to the trash, or null. |
id (required) |
string | |
last_activity_at (required) |
string or null | Start of the last minute with a query, or null. |
name (required) |
string | |
purge_after (required) |
string or null | When a trashed database is removed for good, or null. |
size_bytes (required) |
integer | Space all branches take on disk. |
updated_at (required) |
string |
Rename a database
Section titled “Rename a database”PATCH /v1/databases/{db}
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | Database name or id. |
Request body:
| Field | Type | Description |
|---|---|---|
name (required) |
string |
Response 200:
| Field | Type | Description |
|---|---|---|
branch_count (required) |
integer | |
created_at (required) |
string | |
default_branch (required) |
string | Name of the default branch. |
default_branch_id (required) |
string | |
deleted_at (required) |
string or null | When it went to the trash, or null. |
id (required) |
string | |
last_activity_at (required) |
string or null | Start of the last minute with a query, or null. |
name (required) |
string | |
purge_after (required) |
string or null | When a trashed database is removed for good, or null. |
size_bytes (required) |
integer | Space all branches take on disk. |
updated_at (required) |
string |
Move a database to the trash
Section titled “Move a database to the trash”DELETE /v1/databases/{db}
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | Database name or id. |
Response 200:
| Field | Type | Description |
|---|---|---|
branch_count (required) |
integer | |
created_at (required) |
string | |
default_branch (required) |
string | Name of the default branch. |
default_branch_id (required) |
string | |
deleted_at (required) |
string or null | When it went to the trash, or null. |
id (required) |
string | |
last_activity_at (required) |
string or null | Start of the last minute with a query, or null. |
name (required) |
string | |
purge_after (required) |
string or null | When a trashed database is removed for good, or null. |
size_bytes (required) |
integer | Space all branches take on disk. |
updated_at (required) |
string |
Restore a database from the trash
Section titled “Restore a database from the trash”POST /v1/databases/{db}/restore
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | Database name or id. |
Request body:
| Field | Type | Description |
|---|---|---|
name |
string | Restore under this name instead of the old one. |
Response 200:
| Field | Type | Description |
|---|---|---|
branch_count (required) |
integer | |
created_at (required) |
string | |
default_branch (required) |
string | Name of the default branch. |
default_branch_id (required) |
string | |
deleted_at (required) |
string or null | When it went to the trash, or null. |
id (required) |
string | |
last_activity_at (required) |
string or null | Start of the last minute with a query, or null. |
name (required) |
string | |
purge_after (required) |
string or null | When a trashed database is removed for good, or null. |
size_bytes (required) |
integer | Space all branches take on disk. |
updated_at (required) |
string |
List databases in the trash
Section titled “List databases in the trash”GET /v1/trash
| Parameter | In | Type | Description |
|---|---|---|---|
limit |
query | integer | Most items to return. |
cursor |
query | string | The next_cursor from the previous page. |
Response 200:
| Field | Type | Description |
|---|---|---|
data (required) |
DatabaseOut[] | |
next_cursor (required) |
string | Pass as cursor for the next page; empty on the last page. |
Branches
Section titled “Branches”List branches
Section titled “List branches”GET /v1/databases/{db}/branches
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | Database name or id. |
limit |
query | integer | Most items to return. |
cursor |
query | string | The next_cursor from the previous page. |
Response 200:
| Field | Type | Description |
|---|---|---|
data (required) |
BranchOut[] | |
next_cursor (required) |
string |
Create a branch
Section titled “Create a branch”POST /v1/databases/{db}/branches
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | Database name or id. |
Idempotency-Key |
header | string |
Request body:
| Field | Type | Description |
|---|---|---|
expires_in_days |
integer | Delete the branch automatically after this many days. 0 keeps it. |
from |
string | Branch to copy, name or id. Defaults to the default branch. |
from_snapshot |
string | Snapshot id to copy instead of a branch. |
name (required) |
string | |
protected |
boolean |
Response 201:
| Field | Type | Description |
|---|---|---|
created_at (required) |
string | |
database_id (required) |
string | |
default (required) |
boolean | Whether this is the database’s default branch. |
expires_at (required) |
string or null | When it is deleted automatically, or null. |
id (required) |
string | |
name (required) |
string | |
parent_id (required) |
string | The branch it was copied from, or empty. |
protected (required) |
boolean | Protected branches can’t be deleted or reset. |
size_bytes (required) |
integer | |
source_snapshot_id (required) |
string | The snapshot it was restored from, or empty. |
updated_at (required) |
string |
Get a branch
Section titled “Get a branch”GET /v1/databases/{db}/branches/{branch}
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | Database name or id. |
branch (required) |
path | string | Branch name or id. |
Response 200:
| Field | Type | Description |
|---|---|---|
created_at (required) |
string | |
database_id (required) |
string | |
default (required) |
boolean | Whether this is the database’s default branch. |
expires_at (required) |
string or null | When it is deleted automatically, or null. |
id (required) |
string | |
name (required) |
string | |
parent_id (required) |
string | The branch it was copied from, or empty. |
protected (required) |
boolean | Protected branches can’t be deleted or reset. |
size_bytes (required) |
integer | |
source_snapshot_id (required) |
string | The snapshot it was restored from, or empty. |
updated_at (required) |
string |
Rename a branch or change its protection or expiry
Section titled “Rename a branch or change its protection or expiry”PATCH /v1/databases/{db}/branches/{branch}
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | Database name or id. |
branch (required) |
path | string | Branch name or id. |
Request body:
| Field | Type | Description |
|---|---|---|
expires_in_days |
integer | Days from now until automatic deletion. 0 clears the expiry. |
name |
string | |
protected |
boolean |
Response 200:
| Field | Type | Description |
|---|---|---|
created_at (required) |
string | |
database_id (required) |
string | |
default (required) |
boolean | Whether this is the database’s default branch. |
expires_at (required) |
string or null | When it is deleted automatically, or null. |
id (required) |
string | |
name (required) |
string | |
parent_id (required) |
string | The branch it was copied from, or empty. |
protected (required) |
boolean | Protected branches can’t be deleted or reset. |
size_bytes (required) |
integer | |
source_snapshot_id (required) |
string | The snapshot it was restored from, or empty. |
updated_at (required) |
string |
Delete a branch
Section titled “Delete a branch”DELETE /v1/databases/{db}/branches/{branch}
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | Database name or id. |
branch (required) |
path | string | Branch name or id. |
Response 204: no content.
Compare a branch’s schema with another branch
Section titled “Compare a branch’s schema with another branch”GET /v1/databases/{db}/branches/{branch}/diff
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | Database name or id. |
branch (required) |
path | string | Branch name or id. |
against (required) |
query | string | Branch to compare with, name or id. |
Response 200:
| Field | Type | Description |
|---|---|---|
against (required) |
string | |
against_ddl (required) |
string[] | |
branch (required) |
string | |
branch_ddl (required) |
string[] | |
changes (required) |
Change[] |
Make a branch the default
Section titled “Make a branch the default”POST /v1/databases/{db}/branches/{branch}/promote
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | Database name or id. |
branch (required) |
path | string | Branch name or id. |
Response 200:
| Field | Type | Description |
|---|---|---|
created_at (required) |
string | |
database_id (required) |
string | |
default (required) |
boolean | Whether this is the database’s default branch. |
expires_at (required) |
string or null | When it is deleted automatically, or null. |
id (required) |
string | |
name (required) |
string | |
parent_id (required) |
string | The branch it was copied from, or empty. |
protected (required) |
boolean | Protected branches can’t be deleted or reset. |
size_bytes (required) |
integer | |
source_snapshot_id (required) |
string | The snapshot it was restored from, or empty. |
updated_at (required) |
string |
Reset a branch to a fresh copy of its parent
Section titled “Reset a branch to a fresh copy of its parent”POST /v1/databases/{db}/branches/{branch}/reset
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | Database name or id. |
branch (required) |
path | string | Branch name or id. |
Response 200:
| Field | Type | Description |
|---|---|---|
created_at (required) |
string | |
database_id (required) |
string | |
default (required) |
boolean | Whether this is the database’s default branch. |
expires_at (required) |
string or null | When it is deleted automatically, or null. |
id (required) |
string | |
name (required) |
string | |
parent_id (required) |
string | The branch it was copied from, or empty. |
protected (required) |
boolean | Protected branches can’t be deleted or reset. |
size_bytes (required) |
integer | |
source_snapshot_id (required) |
string | The snapshot it was restored from, or empty. |
updated_at (required) |
string |
Get a branch’s schema
Section titled “Get a branch’s schema”GET /v1/databases/{db}/branches/{branch}/schema
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | Database name or id. |
branch (required) |
path | string | Branch name or id. |
Response 200:
| Field | Type | Description |
|---|---|---|
indexes (required) |
Index[] | |
tables (required) |
Table[] | |
triggers (required) |
Trigger[] | |
views (required) |
View[] |
Get a branch’s activity
Section titled “Get a branch’s activity”GET /v1/databases/{db}/branches/{branch}/stats
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | Database name or id. |
branch (required) |
path | string | Branch name or id. |
window |
query | string: 1h, 6h, 24h, 48h |
Response 200:
| Field | Type | Description |
|---|---|---|
errors (required) |
integer | |
p50_ms (required) |
integer | |
p95_ms (required) |
integer | |
p99_ms (required) |
integer | |
queries (required) |
integer | |
rows_read (required) |
integer | |
rows_written (required) |
integer | |
series (required) |
Point[] | |
since (required) |
string | |
size_bytes (required) |
integer | |
slow_queries (required) |
SlowQueryOut[] | |
step (required) |
string |
Run statements on the default branch in one transaction
Section titled “Run statements on the default branch in one transaction”POST /v1/databases/{db}/batch
Runs statements in order in one transaction. If any fails, none take effect.
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string |
Request body:
| Field | Type | Description |
|---|---|---|
migration |
boolean | Turn foreign key enforcement off for the batch and check every foreign key once before committing. Use it for schema migrations: rebuilding a table (create, copy, drop, rename) would otherwise fire ON DELETE actions and delete child rows. Needs write access. |
read_only |
boolean | Run on a read-only connection even if the token can write. |
statements (required) |
StatementIn[] | Run in order in one transaction: all take effect or none do. |
Response 200:
| Field | Type | Description |
|---|---|---|
results (required) |
ResultOut[] |
Run statements on a branch in one transaction
Section titled “Run statements on a branch in one transaction”POST /v1/databases/{db}/branches/{branch}/batch
Runs statements in order in one transaction. If any fails, none take effect.
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | |
branch (required) |
path | string |
Request body:
| Field | Type | Description |
|---|---|---|
migration |
boolean | Turn foreign key enforcement off for the batch and check every foreign key once before committing. Use it for schema migrations: rebuilding a table (create, copy, drop, rename) would otherwise fire ON DELETE actions and delete child rows. Needs write access. |
read_only |
boolean | Run on a read-only connection even if the token can write. |
statements (required) |
StatementIn[] | Run in order in one transaction: all take effect or none do. |
Response 200:
| Field | Type | Description |
|---|---|---|
results (required) |
ResultOut[] |
Run a statement on a branch
Section titled “Run a statement on a branch”POST /v1/databases/{db}/branches/{branch}/query
Runs one statement with bound parameters in its own transaction. A token that can write runs it on the branch’s writer; a read-only token runs it on a read-only connection, where SQLite refuses writes.
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | |
branch (required) |
path | string |
Request body:
| Field | Type | Description |
|---|---|---|
args |
value[] | Values for positional parameters (?, ?1), in order. |
named |
object | Values for named parameters (:name, @name, $name), keyed with or without the prefix. |
read_only |
boolean | Run on a read-only connection even if the token can write. |
sql (required) |
string | One SQL statement. |
Response 200:
| Field | Type | Description |
|---|---|---|
columns (required) |
ColumnOut[] | |
last_insert_rowid (required) |
string | The rowid of the last row this statement inserted, or “0”. A decimal string, since rowids can pass 2^53. |
rows (required) |
value[][] | Rows as arrays in column order. |
rows_affected (required) |
integer | Rows changed by an INSERT, UPDATE or DELETE, not counting triggers. |
Run a statement on the default branch
Section titled “Run a statement on the default branch”POST /v1/databases/{db}/query
Runs one statement with bound parameters in its own transaction. A token that can write runs it on the branch’s writer; a read-only token runs it on a read-only connection, where SQLite refuses writes.
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string |
Request body:
| Field | Type | Description |
|---|---|---|
args |
value[] | Values for positional parameters (?, ?1), in order. |
named |
object | Values for named parameters (:name, @name, $name), keyed with or without the prefix. |
read_only |
boolean | Run on a read-only connection even if the token can write. |
sql (required) |
string | One SQL statement. |
Response 200:
| Field | Type | Description |
|---|---|---|
columns (required) |
ColumnOut[] | |
last_insert_rowid (required) |
string | The rowid of the last row this statement inserted, or “0”. A decimal string, since rowids can pass 2^53. |
rows (required) |
value[][] | Rows as arrays in column order. |
rows_affected (required) |
integer | Rows changed by an INSERT, UPDATE or DELETE, not counting triggers. |
Snapshots
Section titled “Snapshots”Get a branch’s snapshot schedule
Section titled “Get a branch’s snapshot schedule”GET /v1/databases/{db}/branches/{branch}/snapshot-schedule
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | Database name or id. |
branch (required) |
path | string | Branch name or id. |
Response 200:
| Field | Type | Description |
|---|---|---|
every_minutes (required) |
integer | |
keep_count (required) |
integer | Scheduled snapshots kept, newest first. 0 keeps any number. Manual snapshots are never removed by retention. |
keep_days (required) |
integer | Scheduled snapshots older than this are removed. 0 keeps any age. |
last_run_at (required) |
string or null |
Set a branch’s snapshot schedule
Section titled “Set a branch’s snapshot schedule”PUT /v1/databases/{db}/branches/{branch}/snapshot-schedule
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | Database name or id. |
branch (required) |
path | string | Branch name or id. |
Request body:
| Field | Type | Description |
|---|---|---|
every_minutes (required) |
integer | |
keep_count |
integer | |
keep_days |
integer |
Response 200:
| Field | Type | Description |
|---|---|---|
every_minutes (required) |
integer | |
keep_count (required) |
integer | Scheduled snapshots kept, newest first. 0 keeps any number. Manual snapshots are never removed by retention. |
keep_days (required) |
integer | Scheduled snapshots older than this are removed. 0 keeps any age. |
last_run_at (required) |
string or null |
Remove a branch’s snapshot schedule
Section titled “Remove a branch’s snapshot schedule”DELETE /v1/databases/{db}/branches/{branch}/snapshot-schedule
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | Database name or id. |
branch (required) |
path | string | Branch name or id. |
Response 204: no content.
List a branch’s snapshots
Section titled “List a branch’s snapshots”GET /v1/databases/{db}/branches/{branch}/snapshots
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | Database name or id. |
branch (required) |
path | string | Branch name or id. |
limit |
query | integer | Most items to return. |
cursor |
query | string | The next_cursor from the previous page. |
Response 200:
| Field | Type | Description |
|---|---|---|
data (required) |
SnapshotOut[] | |
next_cursor (required) |
string |
Take a snapshot of a branch
Section titled “Take a snapshot of a branch”POST /v1/databases/{db}/branches/{branch}/snapshots
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | Database name or id. |
branch (required) |
path | string | Branch name or id. |
Idempotency-Key |
header | string |
Request body:
| Field | Type | Description |
|---|---|---|
label |
string |
Response 201:
| Field | Type | Description |
|---|---|---|
branch_id (required) |
string | The branch it was taken from. It may since have been deleted. |
branch_name (required) |
string | The branch’s name when the snapshot was taken. |
created_at (required) |
string | |
database_id (required) |
string | |
id (required) |
string | |
kind (required) |
string: manual, scheduled | |
label (required) |
string | |
size_bytes (required) |
integer |
Delete a snapshot
Section titled “Delete a snapshot”DELETE /v1/databases/{db}/snapshots/{snapshot}
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | Database name or id. |
snapshot (required) |
path | string | Snapshot id. |
Response 204: no content.
Restore a snapshot into a new branch
Section titled “Restore a snapshot into a new branch”POST /v1/databases/{db}/snapshots/{snapshot}/restore
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | Database name or id. |
snapshot (required) |
path | string | Snapshot id. |
Request body:
| Field | Type | Description |
|---|---|---|
name (required) |
string | Name of the new branch the snapshot is restored into. |
Response 201:
| Field | Type | Description |
|---|---|---|
created_at (required) |
string | |
database_id (required) |
string | |
default (required) |
boolean | Whether this is the database’s default branch. |
expires_at (required) |
string or null | When it is deleted automatically, or null. |
id (required) |
string | |
name (required) |
string | |
parent_id (required) |
string | The branch it was copied from, or empty. |
protected (required) |
boolean | Protected branches can’t be deleted or reset. |
size_bytes (required) |
integer | |
source_snapshot_id (required) |
string | The snapshot it was restored from, or empty. |
updated_at (required) |
string |
Import and download
Section titled “Import and download”Download a branch as a SQLite file or SQL dump
Section titled “Download a branch as a SQLite file or SQL dump”GET /v1/databases/{db}/branches/{branch}/export
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | Database name or id. |
branch (required) |
path | string | Branch name or id. |
format |
query | string: db, sql | db: a consistent SQLite file. sql: a SQL dump. |
Response 200: the file, as application/sql or application/vnd.sqlite3.
Import a database file or SQL dump into a branch
Section titled “Import a database file or SQL dump into a branch”POST /v1/databases/{db}/branches/{branch}/import
Send the file as the raw request body. It is built into a new file and checked first: the header, PRAGMA integrity_check, the branch size limit and the same isolation rules as user SQL. The branch only changes when everything passed.
| Parameter | In | Type | Description |
|---|---|---|---|
db (required) |
path | string | Database name or id. |
branch (required) |
path | string | Branch name or id. |
format |
query | string: db, sql | db: a SQLite database file. sql: a SQL dump. |
mode |
query | string: empty, replace | empty refuses a branch that already has tables. replace throws the branch’s content away (not on a protected branch). |
Request body: the raw file, as application/octet-stream or application/sql.
Response 200:
| Field | Type | Description |
|---|---|---|
created_at (required) |
string | |
database_id (required) |
string | |
default (required) |
boolean | Whether this is the database’s default branch. |
expires_at (required) |
string or null | When it is deleted automatically, or null. |
id (required) |
string | |
name (required) |
string | |
parent_id (required) |
string | The branch it was copied from, or empty. |
protected (required) |
boolean | Protected branches can’t be deleted or reset. |
size_bytes (required) |
integer | |
source_snapshot_id (required) |
string | The snapshot it was restored from, or empty. |
updated_at (required) |
string |
Tokens
Section titled “Tokens”List tokens
Section titled “List tokens”GET /v1/tokens
| Parameter | In | Type | Description |
|---|---|---|---|
limit |
query | integer | Most items to return. |
cursor |
query | string | The next_cursor from the previous page. |
Response 200:
| Field | Type | Description |
|---|---|---|
data (required) |
TokenOut[] | |
next_cursor (required) |
string |
Create a token
Section titled “Create a token”POST /v1/tokens
Request body:
| Field | Type | Description |
|---|---|---|
access (required) |
string: read, write, admin | |
branch |
string | Branch name or id, to limit a database token to one branch. |
database |
string | Database name or id. Omit for an instance token. |
expires_in_days |
integer | 0: never expires. A token that expires can’t create one that outlives it: the expiry is capped at the creator’s. |
name (required) |
string |
Response 201:
| Field | Type | Description |
|---|---|---|
access (required) |
string: read, write, admin | |
branch_id (required) |
string | When set, the token only reaches this branch. |
created_at (required) |
string | |
database_id (required) |
string | For a database token, the database it reaches. |
expires_at (required) |
string or null | |
id (required) |
string | |
last_used_at (required) |
string or null | |
name (required) |
string | |
scope (required) |
string: instance, database | |
service (required) |
boolean | The dashboard’s service token. |
token (required) |
string | The full token. Shown once; only its hash is stored. |
Revoke a token
Section titled “Revoke a token”DELETE /v1/tokens/{token_id}
| Parameter | In | Type | Description |
|---|---|---|---|
token_id (required) |
path | string |
Response 204: no content.
Read the audit log
Section titled “Read the audit log”GET /v1/audit
| Parameter | In | Type | Description |
|---|---|---|---|
limit |
query | integer | Most items to return. |
cursor |
query | string | The next_cursor from the previous page. |
Response 200:
| Field | Type | Description |
|---|---|---|
data (required) |
AuditOut[] | |
next_cursor (required) |
string |