API conventions, headers and errors
URL and transport
Use https://api.lordbase.com/e/v1 plus the path documented for the operation. Reference pages show full /e/v1/.../ paths; do not add the prefix twice. Preserve trailing slashes and URL-encode path/query strings. Resource IDs are UUIDs unless otherwise stated.
Use HTTPS, Accept: application/json, and Content-Type: application/json for JSON bodies. Do not send a body on GET. Endpoints that say “no body” do not require invented JSON fields.
Authentication
The public GET /e/v1/health/ needs no credential. Other documented operations require an authenticated developer account, normally an active Lordbase subscription, and any resource role described on the operation.
The dashboard uses its signed-in session. The automation header is:
Authorization: Bearer YOUR_DEVELOPER_TOKEN
Developer tokens are supported on explicitly listed operations; see scopes and exclusions. Do not export dashboard cookies, use database passwords as Bearer tokens or substitute another product’s token header. Native database traffic has separate engine authentication.
Required scopes are enforced; unlisted routes and methods deny token access, including api. Workspace roles, account status, plan features and database state remain separate prerequisites.
Bodies and responses
Requests and responses use JSON unless a response is empty. POST creates/actions, PATCH partially updates, and DELETE removes or deactivates the documented resource. Workspace PUT also behaves as a partial update; do not assume that behavior for unlisted endpoints.
Typical success codes are 200, 201 for creation and 204 for deletion without a body. Schedule deletion is an exception: it returns 200 with a message. Backup creation is asynchronous even though it returns 201; database provisioning is synchronous. Restore returns 202 and an independent job to poll.
Read the response body: pooling/health/analytics endpoints can report an unavailable or unhealthy feature with HTTP 200. Examples show representative selected fields, not a fixed plan, timestamp, port or comprehensive enum for dynamic engine results.
Pagination and list shapes
Database lists, backups, schedules and audit logs use:
{"count":1,"limit":20,"offset":0,"results":[{"id":"11111111-1111-4111-8111-111111111111"}]}
count is the total matching count. Default limit is 20, maximum 100; default offset is 0. A limit below 1 resets to 20, a negative offset becomes 0, and malformed integers return 400. Increase offset by the returned limit until no more results remain. Lists can change while paginating.
Other shapes are intentionally different:
| List | Envelope |
|---|---|
| Workspaces | owned_workspaces, member_workspaces arrays |
| Workspace members, pending invitations, developer search | Array |
| Database users | users array and engine |
| Developer tokens | tokens, available_scopes, count |
| Editor table/collection/key list | results, engine |
| Editor table data | Engine-dependent rows/columns, with engine |
| Metrics history | database_id, hours, data_points, metrics |
| Query analytics lists | Database identifiers, queries, count |
Editor and analytics limits have their own defaults and validation; see those operations.
Errors
Read status and body together. Common error shapes include:
{"error":"workspace_id is required"}
{"display_name":["Name must be at least 2 characters."]}
{"error":"The requested limit is unavailable.","code":"LIMIT_EXCEEDED","limit":5}
The last example illustrates structure; error wording and extra fields vary by operation. Editor execution can instead return status: "error" and message. Gateways can return non-JSON errors, so handle parsing failures without losing HTTP status.
400 usually indicates validation/state; 401 authentication; 403 scope/role/subscription/plan; 404 absent or hidden resources; 429 throttling; 500/502/503 service or engine failure. Preserve X-Request-ID where returned and use the diagnostic table.
No idempotency-key contract is provided. Retry reads with bounded backoff; reconcile outcomes before repeating create, clone, restore or destructive operations. A client timeout is not a rollback signal.