API reference

AetherDB exposes a REST API at https://aetherdb.cloud and a gRPC server on port 50051. All protected endpoints require a JWT Bearer token.

Base URL

https://aetherdb.cloud

Authentication

Include your JWT token in the Authorization header:

Authorization: Bearer eyJhbGci...

Endpoints overview

Public

GET  /health              — Server health check
POST /auth/register       — Create account + provision schema
POST /auth/login          — Sign in, get JWT token

Protected (JWT required)

GET  /db/me               — Current user info
GET  /db/schema           — System schema

POST /db/query            — Raw SQL query (system)
POST /db/ai/query         — AI natural language query (system)

GET  /tenant/info         — Your connection string
GET  /tenant/schema       — Your tables
POST /tenant/tables       — Create a table
POST /tenant/query        — Query your data
POST /tenant/insert       — Insert into your tables
POST /tenant/ai/query     — AI query on your data

GET  /db/projects         — List projects
POST /db/projects         — Create project
POST /db/projects/:id/keys — Generate API key
DELETE /db/projects/:id/keys/:keyId — Revoke key

GET  /db/realtime/subscribe — SSE stream
POST /db/realtime/enable    — Enable realtime on a table

GET  /mcp/tools           — List MCP tools (public)
POST /mcp/call            — Call an MCP tool (public)

Response format

All responses are JSON. Errors follow this format:

{ "error": "description of what went wrong" }

Rate limits

Currently no rate limits are enforced. This will change when billing is introduced.