HTTP API Reference

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>

Create tokens via the CLI: relata tenant members <org> --add <pid> --role admin, or via POST /tokens.

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
curl -X POST http://localhost:9090/query \
  -H "Authorization: Bearer $RELATA_BEARER_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

Ingest

MethodEndpointDescription
POST/ingestIngest CSV/JSON data
POST/ingest/bulkBulk ingest
POST/ingest/documentIngest a document (with auto-chunking)
POST/ingest/mediaIngest media (image/audio/video)
GET/ingest/tasks/:idCheck ingest task status

Tenants (3 surfaces)

/tenants — tenant admin

MethodEndpointDescription
POST/tenantsCreate tenant
GET/tenantsList tenants
GET/tenants/meCaller's tenant context
GET/tenants/:idTenant detail
PATCH/tenants/:idUpdate name/classification
POST/tenants/:id/suspendSuspend
POST/tenants/:id/reactivateReactivate
DELETE/tenants/:idSoft-delete
GET/PUT/tenants/:id/quotaGet/set quota
GET/tenants/:id/usageUsage
POST/GET/DELETE/PATCH/tenants/:id/members[/:pid]Membership CRUD
POST/GET/DELETE/tenants/:id/sharing[/:aid]Sharing agreements
GET/PUT/tenants/:id/config/searchSearch config

/api/v1/tenants — control-plane

MethodEndpointDescription
POST/api/v1/tenantsProvision with inline quota
GET/api/v1/tenantsList with usage
GET/api/v1/tenants/:idConfig + usage
POST/api/v1/tenants/:id/suspendSuspend (402 on queries)
POST/api/v1/tenants/:id/resumeResume
DELETE/api/v1/tenants/:idHard purge (removes rows)
GET/api/v1/tenants/:id/usageBilling snapshot
GET/api/v1/tenants/usage/summaryCross-tenant summary

/platform/tenants — platform admin

MethodEndpointDescription
GET/platform/tenantsList all
GET/platform/tenants/:idDetail
PATCH/platform/tenants/:id/tierAssign tier
POST/platform/tenants/:id/suspendSuspend
POST/platform/tenants/:id/reactivateReactivate
DELETE/platform/tenants/:idTombstone
GET/platform/licenseLicense status
GET/platform/usageUsage summary

Audit & Provenance

MethodEndpointDescription
GET/audit/countEntry count
GET/audit/entriesList entries
GET/audit/proofMerkle proof
GET/audit/logRaw log
POST/api/v1/audit/exportExport (control-plane)

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
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

Cluster

MethodEndpointDescription
GET/cluster/nodesList nodes
GET/cluster/topologyTopology view
POST/cluster/rebalanceRebalance
POST/cluster/drain/:nodeDrain a node

See also