HTTP API Reference
/v1/ with no aliases, some routes are renamed or removed, and Enterprise route families are absent from the open build. Use HTTP route restructure for the mapping, and the server's own GET /openapi.json as the contract (222 paths, 255 operations in the open 3.0 build).RelataDB exposes a REST API on the HTTP port (default 9090). All endpoints require Bearer token authentication via the Authorization header.
Authentication
Authorization: Bearer <token>RELATA_BEARER_TOKEN does not authenticate the data plane. The env-configured bearer token never authenticates ordinary HTTP data-plane routes (/query, /ingest, /search, …) on any profile, with no opt-out — only a registry-minted, tenant-scoped token does. Mint one with POST /admin/tokens (requires RELATA_ADMIN_TOKEN, on the loopback-only admin listener), or via the CLI: relata tenant members <org> --add <pid> --role admin. See Auth & Security for the full setup flow and Tokens below for the self-service surface.
Query
| Method | Endpoint | Description |
|---|---|---|
POST | /query | Execute a SQL (or Cypher) query |
POST | /query/arrow | Execute and return Arrow IPC |
POST | /query/stream | Streaming query results (SSE) |
GET | /export | Export query results as CSV/JSON |
# $TENANT_TOKEN is a registry-minted token from POST /admin/tokens (see below) —
# RELATA_BEARER_TOKEN itself is not accepted on this route.
curl -X POST http://localhost:9090/query \
-H "Authorization: Bearer $TENANT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"sql":"SELECT * FROM Person LIMIT 5","purpose":"analytics"}'Search
| Method | Endpoint | Description |
|---|---|---|
POST | /search | Full-text / vector / hybrid search |
POST | /multi-search | Multi-query with rank fusion |
Tokens
| Method | Endpoint | Description |
|---|---|---|
POST | /admin/tokens | Mint a token (admin listener only; RELATA_ADMIN_TOKEN) — pass tenant_id to bootstrap a tenant-scoped token directly |
GET | /admin/tokens/audit | Platform-wide token lifecycle audit (admin only) |
POST | /tokens/self/rotate | Rotate the caller's own token (self-service, no admin token needed) |
GET | /tokens/self | List the caller's own tenant-scoped tokens (self-service) |
GET | /tokens/self/audit | Audit trail of the caller's own token lifecycle events (self-service) |
DELETE | /tokens/self/:id | Revoke one of the caller's own tokens (self-service) |
Ingest
| Method | Endpoint | Description |
|---|---|---|
POST | /ingest | Ingest rows — NDJSON, a bare JSON array, or a {"rows": [...]} wrapper object (all three accepted since 2.4.0, #4972). Rows failing ontology required-property validation are rejected in the response, not silently dropped (#5047) |
POST | /ingest/bulk | Bulk ingest |
POST | /rag/ingest | Ingest pre-extracted document chunks into DocumentSource/DocumentChunk (renamed from /ingest/document) |
GET | /rag/ingest/:task_id | Poll async document-ingest task status |
POST | /ingest/media | Ingest media (image/audio/video) |
GET | /ingest/tasks/:id | Check ingest task status |
Tenants
The open edition has one tenant, default. GET /v1/tenants/me returns the caller's tenant context. Tenant administration (/v1/tenants*, members, sharing, quotas, lifecycle) and platform administration (/platform/*) belong to Relata Enterprise DB and are absent from the open build's OpenAPI contract.
Audit & Provenance
| Method | Endpoint | Description |
|---|---|---|
GET | /audit/count | Entry count |
GET | /audit/entries | List entries |
GET | /audit/log | Raw log |
Health & System
| Method | Endpoint | Description |
|---|---|---|
GET | /health | Health check |
GET | /health/live | Liveness |
GET | /health/ready | Readiness |
GET | /version | Version |
GET | /status | Detailed status |
GET | /metrics | Prometheus metrics |
GET | /config | Server config |
GET | /openapi.json | OpenAPI spec |
Admin
| Method | Endpoint | Description |
|---|---|---|
POST | /admin/backup | Trigger backup — since 2.4.0 a capture failure refuses with 503 instead of a false green 201/row_count: 0 (#5041) |
GET | /admin/backups | List backups |
POST | /admin/restore | Restore |
POST | /admin/compact | Compact storage |
POST | /admin/reindex | Reindex a type |
POST | /admin/rotate-dek | Rotate encryption key |
GET | /admin/system | System info |
GET | /admin/dashboard | Admin dashboard |
See also
- SDKs — Python / TypeScript / Go clients
- Error codes — HTTP error reference