HTTP API reference

A running RhyDB instance exposes health and information endpoints and accepts plain-text queries over HTTP.

POST /query

Send the query as a plain-text request body. NDJSON is the default response format.

curl -X POST \
  -H 'Content-Type: text/plain' \
  -H 'Accept: application/x-ndjson' \
  --data "default.groupBy({count := count()})" \
  https://rhydb.example.org/query

Each non-empty response line is an independent JSON object:

{ "count": 9430508 }

Apache Arrow output

Send Accept: application/vnd.apache.arrow.stream to receive an Apache Arrow IPC stream. Arrow preserves the result schema, is efficient for large results, and lets clients detect a truncated stream through its end marker.

curl -X POST \
  -H 'Content-Type: text/plain' \
  -H 'Accept: application/vnd.apache.arrow.stream' \
  --data 'default.limit(100)' \
  https://rhydb.example.org/query \
  --output result.arrow

GET /info

Return information about the loaded database, including the RhyDB version and number of sequence records.

{
    "version": "0.14.1",
    "sequenceCount": 1000000,
    "horizontalBitmapsSize": 60000000,
    "verticalBitmapsSize": 58000000
}

GET /health

Return 200 with {"status":"UP"} when the server is ready. During startup, the endpoint may return 503 and a Retry-After header.

Response headers

Header	Meaning
`data-version`	Unix timestamp identifying the database snapshot used for the query.
`X-Request-Id`	The supplied request identifier, or a generated identifier for log correlation.
`result-ordering`	On a successful `POST /query`, a JSON array with one entry per sort key of the result — each with `field`, `order` and `nullPlacement`. An empty array means the row order is unspecified.

Errors

Errors are JSON regardless of the requested result format.

{
    "error": "Bad request",
    "message": "description of the problem"
}

400: malformed or invalid query.
404: unknown endpoint.
405: method not allowed.
500: internal server error.
503: database not ready.

●

Browser access

A static web console sends requests directly from the browser. The RhyDB instance must be reachable from that browser and allow the site’s origin through its CORS policy.