Guide

REST API reference

The Layerbase Cloud API lets you create, list, and query databases over HTTPS, and manage the personal API keys that authenticate every request. This page documents each public endpoint: the auth header it expects, the fields it accepts, the shape it returns, and the status codes it can send back. The Docs overview has the quickstart if you are starting from scratch.

Base URL

Every request uses HTTPS and the same base URL. The examples below store it in $LAYERBASE_API_URL.

https://cloud.layerbase.dev

Authentication

All /v1/* endpoints except GET /v1/engines require a personal API key as a Bearer token. Keys are prefixed sk_ and the full secret is shown exactly once, at creation. Create and manage keys under Personal API keys in cloud settings, or with the key endpoints below.

Authorization: Bearer sk_<your-key>

Keys have one of two scopes. An account key (the default) can reach every endpoint for your account. A database key is pinned to one database: it may only call /v1/databases/<that-id> and its sub-paths, and returns 403 anywhere else.

Request and response format

Requests and responses are JSON, and body fields use camelCase. Send Content-Type: application/json on any request with a body. Errors return { "error": "message" } with a relevant HTTP status; some also add a machine-readable code (for example database_limit_reached or pool_block_required).

Health and engines

Unauthenticated liveness probe. Returns { "status": "ok", "service": "layerbase-cloud" }. Returns 503 with draining or overloaded when the server is shutting down or under memory pressure.

The public engine registry: every engine, its display name, versions, and defaults. No auth required. This is the same data the dashboard create flow reads, so you can use it to build a valid engine and version for a create call.

Databases

Lists the databases you own plus any shared with you through a team. Returns { "databases": [ ... ] }. Each entry includes id, name, engine, version, status, host, port, connectionString, and an access field of owner or member. App workloads are not databases and never appear here.

curl $LAYERBASE_API_URL/v1/databases \
  -H "Authorization: Bearer $LAYERBASE_API_KEY"

Provisions a new database. Only engine is required; the rest have defaults.

Returns 201 with the new database, including its connection details and a status. Fast engines come back running; slow-start engines (MySQL, MariaDB, ClickHouse, QuestDB, libSQL) come back provisioning and finish in the background, so poll GET /v1/databases/:id until status is running. Redis and Valkey also return restUrl / restToken; MySQL and MariaDB also return psUrl / psUsername / psPassword for their HTTP drivers (see serverless and edge access).

curl -X POST $LAYERBASE_API_URL/v1/databases \
  -H "Authorization: Bearer $LAYERBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"engine": "postgresql", "name": "my-app"}'

Common failures: 400 for an invalid engine or name, 403 for an engine your plan cannot create, 409 when the name is taken or the pool is exhausted, and 429 when you hit your plan's database limit.

Returns one database with the same fields as the list entry plus teamName and stopped_at. Returns 404 if the database does not exist or is not yours. Poll this after a create to watch status settle.

Runs a query over HTTP against the database, no driver or open socket required, which makes it the easiest path from serverless and edge runtimes. Send { "query": "SELECT 1" } for SQL engines; the query is capped at 10 KB. A hibernated database wakes automatically (you may get a 503 with retry_after while it does); an archived one returns 503 with a restore path, and a locked one returns 423. The full request shapes for non-SQL engines and edge examples are in serverless and edge access.

curl -X POST $LAYERBASE_API_URL/v1/databases/<id>/query \
  -H "Authorization: Bearer $LAYERBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT 1"}'

API keys

Manage the personal keys that authenticate the API. The raw secret is returned exactly once, on create and rotate; store it immediately.

Lists your active keys. Returns { "keys": [ ... ] } with each key's id, name, prefix, scopeType, createdAt, and lastUsedAt. The secret is never included.

Creates a key. Body is optional: name (defaults to default, max 80 chars), scopeType (account or database), and scopeId (required when scopeType is database, naming a database you own). Returns 201 with { "key": { ..., "secret": "sk_..." } }. The secret appears only in this response.

curl -X POST $LAYERBASE_API_URL/v1/api-keys \
  -H "Authorization: Bearer $LAYERBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci"}'

Mints a replacement key with the same name and scope and revokes the old one after a 24-hour grace window, so long-running callers can pick up the new secret without an outage. Returns 201 with the new key and its one-time secret. Returns 404 if the key is not yours and 410 if it is already revoked.

Revokes a key immediately. Returns { "ok": true } and is idempotent (revoking an already-revoked key still returns 200). Any request using that key fails 401 afterward.

The dashboard exposes many more per-database operations (stop, start, backup, restore, branch, firewall, client certificates) over the same /v1/databases/:id/* surface. Those are covered in their own guides, linked below.