HTTP API reference
A running RhyDB instance exposes health and information endpoints and accepts plain-text queries, and optionally write statements, 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 "data.group(by := {}, aggs := {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 'data.limit(100)' \
https://rhydb.example.org/query \
--output result.arrow
POST /admin/query
Send an insertInto, update, delete or createTable write statement as a plain-text request body. RhyDB applies it to the most recent state in its data directory and saves the result as a new data version, which is served once the server has picked it up. A write that fails leaves the data version unchanged.
curl -X POST \
--data "source.filter(country = 'Switzerland').project({primaryKey, country}).insertInto(archive)" \
https://rhydb.example.org/admin/query
The response is a single row that summarizes the write, as NDJSON or, with Accept: application/vnd.apache.arrow.stream, as an Apache Arrow IPC stream. Its data-version header names the version the write produced, and its result-ordering header is [].
| Statement | Response |
|---|---|
insertInto | {“insertedRows”: 42} |
update | {“updatedRows”: 2} |
delete | {“deletedRows”: 2} |
createTable | {“createdTable”: “archive”} |
The endpoint is only served when the instance sets api.allowAdminEndpoint to true; otherwise it returns 404
and the instance is read-only. It has no authentication of its own, so a public instance that enables it must
restrict access to it, for example in its reverse proxy.
GET /info
Return information about the loaded database, including the RhyDB version and number of sequence records.
{
"version": "0.17.3",
"sequenceCount": 1000000,
"horizontalBitmapsSize": 60000000,
"verticalBitmapsSize": 58000000
}
GET /lineageDefinition/{columnName}
Return the lineage definition file of a lineage column as YAML (application/yaml), as stored in the built-in lineage_definitions table. A column that does not exist or has no lineage definition returns 400.
curl https://rhydb.example.org/lineageDefinition/pangoLineage
A:
aliases:
- a
A.1:
aliases:
- a.1
parents:
- A
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 |
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.
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.
