API Reference

A machine-readable OpenAPI 3.1 spec is available at:

GET /api/v1/openapi.json

No authentication required. Import it into Postman, Insomnia, Swagger UI, or any OpenAPI-compatible tooling to explore all endpoints interactively.

---

All endpoints are under /api/v1. Authenticated endpoints require Authorization: Bearer <access-token> or X-API-Key: bb_....

Admin endpoints require Authorization: Bearer <admin-secret>.

Auth

Method	Path	Auth	Description
POST	/auth/register	—	Register with email + password
POST	/auth/login	—	Login; returns tokens or totp_required
POST	/auth/refresh	—	Exchange refresh token for new pair
POST	/auth/logout	Bearer	Revoke current session
POST	/auth/logout-all	Bearer	Revoke all sessions
GET	/auth/me	Bearer	Get current user
DELETE	/auth/me	Bearer	Delete account
POST	/auth/forgot-password	—	Send password reset email
POST	/auth/reset-password	—	Reset password with token
POST	/auth/verify-email	—	Verify email with token
POST	/auth/resend-verification	Bearer	Resend verification email
POST	/auth/magic-link	—	Send magic link email
POST	/auth/magic-link/verify	—	Verify magic link, create session
POST	/auth/api-keys	Bearer	Create API key
GET	/auth/api-keys	Bearer	List API keys
DELETE	/auth/api-keys/:id	Bearer	Revoke API key
POST	/auth/2fa/setup	Bearer	Generate TOTP secret
POST	/auth/2fa/enable	Bearer	Enable 2FA with TOTP code
DELETE	/auth/2fa/disable	Bearer	Disable 2FA with TOTP code
POST	/auth/2fa/verify	—	Complete login with TOTP code

Collections

Method	Path	Auth	Description
GET	/:collection	Varies	List records (supports ?search= for full-text search)
POST	/:collection	Varies	Create record
GET	/:collection/:id	Varies	Get record
PATCH	/:collection/:id	Varies	Update record
DELETE	/:collection/:id	Varies	Soft-delete record
POST	/:collection/:id/restore	Bearer	Restore soft-deleted record
GET	/:collection/count	Varies	Count records
GET	/:collection/aggregate	Varies	Aggregate (sum/avg/min/max/count)
POST	/:collection/bulk	Varies	Bulk-create records (atomic, max 500)
POST	/:collection/batch	Bearer	Atomic batch create/update/delete (max 100 ops)

Storage

Method	Path	Auth	Description
POST	/storage/upload	Bearer	Upload a file (multipart/form-data)
GET	/storage	Bearer	List files owned by current user
GET	/storage/:id	Varies	Download file
GET	/storage/:id/:filename	Varies	Download file (cosmetic — carries original filename for browser; same auth rules as /:id)
DELETE	/storage/:id	Bearer	Delete file
POST	/storage/sign	Bearer	Generate signed upload URL

Upload fields

Field	Required	Description
file	Yes	The file to upload
bucket	No	Target bucket (default: default)
is_public	No	true or 1 for public files
collection	No	Associated collection name
record_id	No	Associated record ID

Admin — Collections

Method	Path	Description
GET	/admin/collections	List all collections
POST	/admin/collections	Create collection
PATCH	/admin/collections/:name	Update access rules
DELETE	/admin/collections/:name	Drop collection and all data
GET	/admin/collections/:name/schema	Get schema info
DELETE	/admin/collections/:name/schema/:column	Drop a column
GET	/admin/collections/:name/records	List records (admin, includes deleted)
POST	/admin/collections/:name/records	Create record
GET	/admin/collections/:name/records/:id	Get any record
PATCH	/admin/collections/:name/records/:id	Update any record
DELETE	/admin/collections/:name/records/:id	Hard-delete record
PUT	/admin/collections/:name/rules	Set field validation rules
GET	/admin/collections/:name/indexes	List indexes
POST	/admin/collections/:name/indexes	Create index on a column
DELETE	/admin/collections/:name/indexes/:column	Drop an index

Admin — Users

Method	Path	Description
GET	/admin/users	List all users
DELETE	/admin/users/:id	Delete a user
PATCH	/admin/users/:id/roles	Set user roles
POST	/admin/users/:id/impersonate	Issue 15-min token as user

Admin — Sessions

Method	Path	Description
GET	/admin/sessions	List all sessions
DELETE	/admin/sessions/:id	Revoke a session
POST	/admin/sessions/purge	Delete all expired sessions

Admin — Storage

Method	Path	Description
GET	/admin/storage	List all files
POST	/admin/storage/upload	Upload without user ownership
DELETE	/admin/storage/:id	Delete any file

Admin — Buckets

Method	Path	Description
GET	/admin/buckets	List buckets
POST	/admin/buckets	Create bucket
PATCH	/admin/buckets/:name	Update bucket settings
DELETE	/admin/buckets/:name	Delete bucket

Admin — Relations

Method	Path	Description
GET	/admin/relations	List relations
POST	/admin/relations	Create relation
DELETE	/admin/relations/:id	Delete relation

Admin — Lifecycle Hooks

Method	Path	Description
GET	/admin/hooks	List all hooks (filter with ?collection=name)
POST	/admin/hooks	Create hook
GET	/admin/hooks/:id	Get hook
PATCH	/admin/hooks/:id	Update hook (code, enabled)
DELETE	/admin/hooks/:id	Delete hook

See Lifecycle Hooks for full documentation.

Admin — Settings

Method	Path	Description
GET	/admin/settings	Get all runtime settings
PATCH	/admin/settings	Update one or more settings (takes effect within 60 s)
GET	/admin/settings/audit	Settings change audit log (?limit=50&offset=0)
GET	/admin/settings/export	Download all settings as a JSON file
POST	/admin/settings/import	Bulk-import settings from a JSON object
POST	/admin/settings/test-email	Send a test email using current provider config
POST	/admin/restart	Gracefully restart the server process

Available setting keys (see Configuration for full table):

Key	Type	Default	Description
maintenance_mode	boolean	false	Return 503 for all non-admin requests
registration_open	boolean	true	Allow new user registrations
single_session_mode	boolean	false	Revoke other sessions on new login
lockout_max_attempts	number	10	Max failed logins before lockout
lockout_duration_ms	number	900000	Lockout duration in ms
auto_create_buckets	boolean	false	Create missing buckets on first upload
auto_create_collections	boolean	true	Create missing collections on first write
email_provider	string	console	console, resend, or smtp
email_from	string	—	Sender address
app_name	string	—	App name shown in emails
app_url	string	—	Frontend origin for email callback links

Admin — Operations

Method	Path	Description
GET	/admin/health	Health check (public)
GET	/admin/stats	Aggregate server metrics
POST	/admin/backup	Hot backup (VACUUM INTO), streams .db file

Prometheus

Method	Path	Description
GET	/metrics	Prometheus text format metrics

Common Response Codes

Code	Meaning
200	OK
201	Created
204	No content
304	Not modified (conditional GET)
400	Bad request / validation error
401	Authentication required
403	Forbidden
404	Not found
409	Conflict
413	File too large
415	Unsupported MIME type
429	Rate limit exceeded
500	Internal server error

Error Format

All error responses use the same format:

{ "error": "Human-readable error message." }