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

Admin Login

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 Status

POST/api/admin/status

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

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"
}
]
}

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. Requires 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 require 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}]}'

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, and fields query params. Accessible with an API key or admin session.

# 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: Non-admin API keys may only execute SELECT statements. INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, and other write statements require an admin key or session. If the database is in read-only mode, writes are rejected for everyone.

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. Requires admin session.

Import Database

POST/api/databases/import

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

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
500 Internal Error	Server error