Protocols

Relata DB 3.0
This page describes Relata DB 3.0, the current release. See What is new in 3.0.

Relata DB 3.0 serves a small set of client interfaces from one binary and one governed store. The compatibility wire protocols served through 2.5.8 are retired; see Compatibility and retired doors.

Served interfaces

InterfaceDefault port and pathAuthentication
HTTP/JSONRELATA_PORT (9090), /v1/* and probesRegistry token in Authorization: Bearer
OpenAPI 3.1GET /openapi.jsonas for HTTP
GraphQLPOST /v1/graphqlas for HTTP; read-only
MCPPOST /mcp (JSON-RPC 2.0, buffered JSON, no SSE, no session); tool routes under /v1/mcp/*as for HTTP
A2A/v1/a2a/tasks, /v1/a2a/checkpoints/*, agent card at /.well-known/agent.jsonbearer
Search/v1/search, /v1/search/multi, /v1/search/savedas for HTTP
OTLP/HTTP JSON/v1/traces, /v1/logs, /v1/metrics (need RELATA_OTLP_ENABLED)as for HTTP
Adminloopback 127.0.0.1:9091, /admin/*RELATA_ADMIN_TOKEN

The HTTP listener binds to loopback by default; set RELATA_HTTP_BIND to expose it, and use TLS when you do. The data plane does not accept the bootstrap secret RELATA_BEARER_TOKEN; it accepts tokens minted from the registry on the admin listener. GraphQL and MCP are API styles on the same shared listener, not separate sockets.

Probes (/health, /health/live, /health/ready, /version) are unversioned.

Query surface notes

  • POST /v1/query is read-only. SQL is the primary language; a Cypher subset is accepted with the x-query-dialect: cypher header and translated to SQL.
  • POST /v1/query/arrow returns Arrow IPC for columnar clients; POST /v1/query/stream streams results.
  • GraphQL supports field selection, limit, where, variables and restricted introspection. Mutations, subscriptions, fragments, unions and interfaces are not supported.
  • Governed reads and writes can be made citeable: see Retrieval evidence.

Retired

PostgreSQL wire, Arrow Flight, the S3-compatible listener, Redis RESP, MongoDB wire, ClickHouse HTTP and native TCP, Neo4j HTTP, Bolt and /sparql. The public gRPC data API is also not part of the supported surface; internal cluster gRPC is authenticated and Enterprise track. Migration paths: Migrating from retired doors.