HTTP API Reference

Relata DB 3.0
Paths on this page are the 2.5.8 paths. In 3.0 every public data-plane route moves under /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

MethodEndpointDescription
POST/queryExecute a SQL (or Cypher) query
POST/query/arrowExecute and return Arrow IPC
POST/query/streamStreaming query results (SSE)
GET/exportExport 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"}'
MethodEndpointDescription
POST/searchFull-text / vector / hybrid search
POST/multi-searchMulti-query with rank fusion

Tokens

MethodEndpointDescription
POST/admin/tokensMint a token (admin listener only; RELATA_ADMIN_TOKEN) — pass tenant_id to bootstrap a tenant-scoped token directly
GET/admin/tokens/auditPlatform-wide token lifecycle audit (admin only)
POST/tokens/self/rotateRotate the caller's own token (self-service, no admin token needed)
GET/tokens/selfList the caller's own tenant-scoped tokens (self-service)
GET/tokens/self/auditAudit trail of the caller's own token lifecycle events (self-service)
DELETE/tokens/self/:idRevoke one of the caller's own tokens (self-service)

Ingest

MethodEndpointDescription
POST/ingestIngest 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/bulkBulk ingest
POST/rag/ingestIngest pre-extracted document chunks into DocumentSource/DocumentChunk (renamed from /ingest/document)
GET/rag/ingest/:task_idPoll async document-ingest task status
POST/ingest/mediaIngest media (image/audio/video)
GET/ingest/tasks/:idCheck 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

MethodEndpointDescription
GET/audit/countEntry count
GET/audit/entriesList entries
GET/audit/logRaw log

Health & System

MethodEndpointDescription
GET/healthHealth check
GET/health/liveLiveness
GET/health/readyReadiness
GET/versionVersion
GET/statusDetailed status
GET/metricsPrometheus metrics
GET/configServer config
GET/openapi.jsonOpenAPI spec

Admin

MethodEndpointDescription
POST/admin/backupTrigger backup — since 2.4.0 a capture failure refuses with 503 instead of a false green 201/row_count: 0 (#5041)
GET/admin/backupsList backups
POST/admin/restoreRestore
POST/admin/compactCompact storage
POST/admin/reindexReindex a type
POST/admin/rotate-dekRotate encryption key
GET/admin/systemSystem info
GET/admin/dashboardAdmin dashboard

See also

  • SDKs — Python / TypeScript / Go clients
  • Error codes — HTTP error reference