API reference

Real endpoints for real platform work

The public surface is organized around the same product model used in the console: authentication, organizations, projects, groups, tables, credentials, backups, audit, and secure operational actions.

Authentication model

Access token

Short-lived bearer token, signed with `EdDSA/Ed25519`, intended for API calls and server-side request mediation.

Refresh token

Long-lived rotating token, stored hashed on the server and revoked per session when credentials change.

Envelope

Every successful response returns `success`, `data`, `meta`, and `error` in a stable shape for easier client integration.

Operating system quick start

Linux / macOS

curl -X POST https://your-domain.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "owner@company.tld",
    "password": "your-password"
  }'

Windows PowerShell

Invoke-RestMethod \
  -Method Get \
  -Uri "https://your-domain.com/api/healthz"

Health and auth

`GET /api/healthz` checks runtime health.

`POST /api/v1/auth/login` exchanges email and password for access and refresh tokens.

`POST /api/v1/auth/refresh` rotates the refresh token and returns a fresh access token.

`GET /api/v1/auth/me` returns the active user plus effective permissions.

Platform graph

`GET /api/v1/organizations` and `POST /api/v1/organizations` read and create organizations.

`GET /api/v1/projects` and `POST /api/v1/projects` manage projects under an organization.

`GET /api/v1/groups` and `POST /api/v1/groups` manage groups inside a project.

`GET /api/v1/tables` and `POST /api/v1/tables` expose managed table creation and discovery.

Operations

`GET /api/v1/credentials` lists masked connection profiles visible to the actor.

`POST /api/v1/credentials/:id/reveal` reveals a URI only when policy allows it.

`GET /api/v1/backups/runs` and `POST /api/v1/backups/runs` inspect or trigger backups.

`GET /api/v1/audit/events` returns the audit trail for sensitive operational activity.

Common request patterns

Read organizations

fetch("https://your-domain.com/api/v1/organizations", {
  headers: {
    Authorization: `Bearer ${accessToken}`
  }
});

Create an organization

curl -X POST https://your-domain.com/api/v1/organizations \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "imagine-labs",
    "name": "Imagine Labs"
  }'

Invite a user

curl -X POST https://your-domain.com/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "operator@imagine.tech",
    "display_name": "Platform Operator",
    "locale": "en"
  }'

Response envelope

{
  "success": true,
  "data": { "...": "resource payload" },
  "meta": { "...": "context" },
  "error": null
}

This stable response format makes it straightforward to build shell scripts, PowerShell automation, server-side routes, or SDK wrappers around BaserDB without inventing a different parser for each domain.