API Reference

REST API

The Boltstore REST API provides full access to your databases and admin operations. All endpoints are prefixed with /api.

Authentication

All API requests require authentication via the Authorization header:

# Per-database API key
Authorization: Bearer boltstore_...
# Admin session token (from POST /api/admin/login)
Authorization: Bearer <session-token>

API keys are scoped per database. Admin sessions have global scope. Manage keys in the Dashboard or via the admin API.

Base URL

# Local development
http://localhost:8080/api
# Production (your deployed instance)
https://your-boltstore-instance.com/api

Admin Endpoints

POST/api/admin/login

Authenticate an admin user and receive a session token. Login is throttled per-IP (5 attempts per 15 minutes).

curl -X POST http://localhost:8080/api/admin/login \
-H 'Content-Type: application/json' \
-d '{"email": "admin@example.com", "password": "..."}'
# Response
{ "data": { "token": "<session-token>", "admin": { "id": "adm_...", "email": "admin@example.com" } } }

Admin Status

GET/api/admin/status

Check whether any admins exist (used by the dashboard setup flow). Public, no auth required.

Admin Setup

POST/api/admin/setup

Create the first admin account (no auth required) or additional admins (requires bootstrap key or existing session). Throttled per-IP.

bash

curl -X POST http://localhost:8080/api/admin/setup \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "password": "..."}'

Get Current Admin

GET/api/admin/me

Returns the current admin's { id, email } from the session token. Requires admin session.

Admin Logout

POST/api/admin/logout

Invalidates the session token. Requires admin session.

Databases

List Databases

GET/api/databases

Returns a list of all databases. Requires admin session.

curl http://localhost:8080/api/databases \
-H 'Authorization: Bearer <session-token>'
# Response
{
"data": [
{
"id": "db_...",
"name": "my-app",
"path": "./data/my-app.db",
"createdAt": "2026-06-20T10:00:00Z"
}
]
}

Get Database

GET/api/databases/:name

Returns a single database with its tables. Accepts an API key or admin session.

Rename Database

PATCH/api/databases/:name

Renames a database and its underlying file. Requires admin session.

bash

curl -X PATCH http://localhost:8080/api/databases/my-app \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app-v2"}'

Database Config

GET/api/databases/:name/config

PATCH/api/databases/:name/config

Get or update per-database configuration (CORS origins, readonly flag, group). Accepts an API key or admin session.

Create Database

POST/api/databases

Creates a new database. Names must match /^[a-z0-9][a-z0-9_-]*$/. Requires admin session.

curl -X POST http://localhost:8080/api/databases \
-H 'Authorization: Bearer <session-token>' \
-H 'Content-Type: application/json' \
-d '{"name": "my-app"}'

Delete Database

DELETE/api/databases/:name

Permanently deletes a database and its file. This action cannot be undone. Requires admin session.

API Keys

Create API Key

POST/api/databases/:name/keys

Creates a new per-database API key. The raw key is returned only once. Accepts an API key or admin session.

curl -X POST http://localhost:8080/api/databases/my-app/keys \
-H 'Authorization: Bearer <session-token>' \
-H 'Content-Type: application/json' \
-d '{"label": "My App Backend"}'
# Response
{
"data": {
"id": "apk_...",
"label": "My App Backend",
"key": "boltstore_..."
}
}

Rotate / Revoke Key

POST/api/databases/:name/keys/:id/rotate

DELETE/api/databases/:name/keys/:id

Rotate generates a new key string (old key stops working). Revoke permanently deletes the key. Both accept an API key or admin session.

Tables

List / Create Tables

GET/api/databases/:db/tables

POST/api/databases/:db/tables

Accessible with an API key or admin session.

curl -X POST http://localhost:8080/api/databases/my-app/tables \
-H 'Authorization: Bearer boltstore_...' \
-H 'Content-Type: application/json' \
-d '{"name": "users", "columns": [{"name": "id", "type": "integer", "primary_key": true, "auto_increment": true}, {"name": "name", "type": "text", "nullable": false}]}'

Get Table Schema

GET/api/databases/:db/tables/:table

Returns column metadata (name, type, notnull, pk, default) from PRAGMA table_info. Accessible with an API key or admin session.

Alter Table

PATCH/api/databases/:db/tables/:table

Rename the table, add/drop columns, or rename a column:

json

{
  "name": "new-name",
  "add_columns": [{ "name": "body", "type": "text" }],
  "drop_columns": ["old_col"],
  "rename_column": { "from": "old_name", "to": "new_name" }
}

Requires a write-capable API key or admin session.

Drop Table

DELETE/api/databases/:db/tables/:table

Permanently drops a table and all its data. Requires write access.

Records

List / Create Records

GET/api/databases/:db/tables/:table/records

POST/api/databases/:db/tables/:table/records

List supports filter, sort, limit (max 1000, default 50), offset, fields, and search query params. Accessible with an API key or admin session.

Filter Syntax

The filter parameter is a JSON object. Simple equality: {"status": "active"}. For comparison operators, append __op to the field name:

Operator	Example	Description
`__eq`	`{"views__eq": 100}`	Equal (same as bare value)
`__ne`	`{"status__ne": "archived"}`	Not equal
`__gt`	`{"views__gt": 100}`	Greater than
`__gte`	`{"views__gte": 100}`	Greater than or equal
`__lt`	`{"views__lt": 100}`	Less than
`__lte`	`{"views__lte": 100}`	Less than or equal
`__in`	`{"status__in": ["active","pending"]}`	Value in array
`__like`	`{"title__like": "%hello%"}`	SQL LIKE match (use `%` for wildcards)
`__glob`	`{"title__glob": "hello"}`	SQL GLOB match

Other Params

sort — Field name prefixed with - for descending (e.g., -created_at).
fields — Comma-separated list of columns to return (e.g., id,title).
search — Full-text search across all text columns (simple LIKE match on the search term).
limit — Max records per page (default 50, max 1000).
offset — Pagination offset.

# List with filter and pagination
curl 'http://localhost:8080/api/databases/my-app/tables/users/records?filter={"active":true}&sort=-created_at&limit=10' \
-H 'Authorization: Bearer boltstore_...'
# Create a record
curl -X POST http://localhost:8080/api/databases/my-app/tables/users/records \
-H 'Authorization: Bearer boltstore_...' \
-H 'Content-Type: application/json' \
-d '{"name": "Alice", "email": "alice@example.com"}'

Get / Update / Delete Record

GET/api/databases/:db/tables/:table/records/:id

PATCH/api/databases/:db/tables/:table/records/:id

DELETE/api/databases/:db/tables/:table/records/:id

Standard CRUD on a single record by ID. Accessible with an API key or admin session.

Raw SQL

Execute SQL

POST/api/databases/:db/query

Execute parameterised SQL. Accepts { sql: string, params?: unknown[] }.

Policy: API keys may execute any SQL statement — SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, PRAGMA, ATTACH, etc. If the database is in read-only mode, writes are rejected for everyone. ATTACH DATABASE paths must be within the server data directory.

curl -X POST http://localhost:8080/api/databases/my-app/query \
-H 'Authorization: Bearer boltstore_...' \
-H 'Content-Type: application/json' \
-d '{"sql": "SELECT * FROM users WHERE active = ?", "params": [1]}'
# Response
{
"data": [
{ "id": 1, "name": "Alice", "email": "alice@example.com" }
]
}

Import / Export

Export Database

POST/api/databases/:name/export

Exports the database to a .db file via VACUUM INTO. Accepts an API key or admin session.

Response: Binary application/octet-stream stream of the .db file (NOT JSON). Save the response body directly to a .db file.

Import Database

POST/api/databases/import

Imports a .db file and registers a new database (with integrity check). Requires admin session.

Activity Log

GET/api/activity?limit=20&offset=0

Paginated audit log of admin actions (login, database create/rename/delete, etc.). Requires admin session.

Settings

GET/api/settings

PATCH/api/settings

Get or update global settings (timezone, server URL). Requires admin session.

Health

GET/api/health

Public health check. Returns server status, version, and database count. No auth required.

bash

curl http://localhost:8080/api/health
# { "status": "ok", "version": "1.0.0", "databases": 3 }

Response Codes

Status	Description
200 OK	Request successful
201 Created	Resource created successfully
400 Bad Request	Invalid request parameters
401 Unauthorized	Missing or invalid credentials
403 Forbidden	Action requires admin privileges
404 Not Found	Resource not found
409 Conflict	Resource already exists (e.g., duplicate database name)
413 Payload Too Large	Request body exceeds `maxBodySize` limit
429 Rate Limited	Too many requests — retry after the indicated delay
500 Internal Error	Server error

REST API ​

Authentication ​

Base URL ​

Admin Endpoints ​

Admin Login ​

Admin Status ​

Admin Setup ​

Get Current Admin ​

Admin Logout ​

Databases ​

List Databases ​

Get Database ​

Rename Database ​

Database Config ​

Create Database ​

Delete Database ​

API Keys ​

Create API Key ​

Rotate / Revoke Key ​

Tables ​

List / Create Tables ​

Get Table Schema ​

Alter Table ​

Drop Table ​

Records ​

List / Create Records ​

Filter Syntax ​

Other Params ​

Get / Update / Delete Record ​

Raw SQL ​

Execute SQL ​

Import / Export ​

Export Database ​

Import Database ​

Activity Log ​

Settings ​

Health ​

Response Codes ​

REST API

Authentication

Base URL

Admin Endpoints

Admin Login

Admin Status

Admin Setup

Get Current Admin

Admin Logout

Databases

List Databases

Get Database

Rename Database

Database Config

Create Database

Delete Database

API Keys

Create API Key

Rotate / Revoke Key

Tables

List / Create Tables

Get Table Schema

Alter Table

Drop Table

Records

List / Create Records

Filter Syntax

Other Params

Get / Update / Delete Record

Raw SQL

Execute SQL

Import / Export

Export Database

Import Database

Activity Log

Settings

Health

Response Codes