HTTP API
namidb-server exposes a small JSON API under /v0. Every request and
response body is JSON (Content-Type: application/json), except
/v0/metrics, which is Prometheus text.
Authentication
Send a bearer token on every private route:
Authorization: Bearer <token>| Status | Meaning |
|---|---|
| 401 | Missing or unknown token, or (multi-tenant) a token not scoped to the requested namespace. |
| 403 | A read-only token attempted a write, DDL or admin action. |
/v0/livez, /v0/health, /v0/version and /v0/metrics never require a
token. See Authentication for token
files, JWT and policy hooks.
Routes
| Method | Path | Auth | Purpose |
|---|---|---|---|
POST | /v0/cypher | token | Run one Cypher statement |
GET | /v0/livez | public | Liveness |
GET | /v0/health | public | Readiness |
GET | /v0/version | public | Build version |
GET | /v0/metrics | public | Prometheus metrics |
POST | /v0/admin/flush | read-write | Flush the in-memory table |
POST | /v0/admin/compact | read-write | Drain level 0, blocking |
POST | /v0/admin/backup | read-write | Online backup, also as of an earlier instant (as_of) |
GET | /v0/admin/restore-points | read-write | The restore point window |
GET | /v0/admin/queries | read-write | List in-flight queries |
POST | /v0/admin/queries/:id/cancel | read-write | Cancel a query |
In multi-tenant mode, every route except
/v0/version and /v0/metrics also exists as /:namespace/v0/…, the
unprefixed form takes the X-NamiDB-Namespace header, and
POST /:namespace/v0/admin/restore is added.
POST /v0/cypher
Request
{ "query": "MATCH (p:Person) WHERE p.age >= $min RETURN p.name AS name", "params": {"min": 18}}| Field | Type | Required | Notes |
|---|---|---|---|
query | string | yes | Exactly one statement. |
params | object | no | Values for $name parameters. |
The body is limited to 2 MiB; send larger batches in several requests.
Response
A read:
{"columns": ["name"], "rows": [{"name": "Alice"}, {"name": "Bob"}]}A write adds write_outcome:
{ "columns": ["name"], "rows": [{"name": "Ada"}], "write_outcome": { "nodes_created": 1, "edges_created": 0, "nodes_deleted": 0, "edges_deleted": 0, "properties_set": 0 }}columnslists the result columns inRETURNorder. Each row is an object keyed by column name; the keys inside a row object are not ordered, so usecolumnsfor display order.- DDL (
CREATE INDEX, …) returns{"columns": [], "rows": []}. EXPLAIN …returns oneplancolumn with one row per plan line.
curl -s localhost:8080/v0/cypher \ -H "Authorization: Bearer $NAMIDB_AUTH_TOKEN" -H 'Content-Type: application/json' \ -d '{"query": "EXPLAIN MATCH (a:N) RETURN a"}'# {"columns":["plan"],"rows":[{"plan":"Project [a=a]"},{"plan":" NodeScan label=N alias=a"}]}Value mapping
| Cypher | JSON in results | JSON as a parameter |
|---|---|---|
NULL | null | null |
BOOLEAN | true / false | true / false |
INTEGER | number | integer number |
FLOAT | number (NaN / Infinity become null) | number with a fraction or exponent |
STRING | string | string |
LIST | array | array |
MAP | object | object |
VECTOR | array of numbers | array of numbers |
BYTES | base64 string | — |
DATE | string holding days since 1970-01-01 ("20758" for 2026-11-01) | — |
DATETIME | RFC 3339 string in UTC ("2026-11-01T10:00:00+00:00") | — |
| Node | {"_kind": "node", "id", "label", "labels", "properties"} | — |
| Relationship | {"_kind": "rel", "edge_type", "src", "dst", "properties"} | — |
| Path | array alternating node and relationship objects | — |
For dates, return toString(d) to get ISO text ("2026-11-01"), and pass
dates and datetimes as strings converted in the query:
date($day), datetime($ts).
A node object:
{"_kind": "node", "id": "01a19a39-6785-71b1-8e40-34a60eef3b9f", "label": "Person", "labels": ["Person"], "properties": {"age": 30, "name": "Alice"}}label is the first label (kept for older clients); labels is the full
set. A relationship:
{"_kind": "rel", "edge_type": "KNOWS", "src": "01a19a39-6785-71b1-8e40-34a60eef3b9f", "dst": "01a19a39-67f6-7202-b0ad-0369cfce38c3", "properties": {"since": 2020}}Errors
A failed statement returns a JSON body with machine-readable fields:
{ "error": "read execution failed: EvalError: integer division by zero at [7..10)", "code": "eval_error", "neo4j_code": "Neo.ClientError.Statement.ArgumentError", "gql_status": "22000"}| Condition | HTTP | code | neo4j_code | gql_status |
|---|---|---|---|---|
| Syntax error | 400 | parse_error | Neo.ClientError.Statement.SyntaxError | 42001 |
| Semantic / planning error | 400 | plan_error | Neo.ClientError.Statement.SemanticError | 42000 |
| Feature not supported | 400 | unsupported | Neo.ClientError.Statement.NotSupported | 0A000 |
Evaluation error (division by zero, missing $param, type mismatch) | 400 | eval_error | Neo.ClientError.Statement.ArgumentError | 22000 |
Constraint violation (unique key, vector dimension, DELETE of a connected node) | 409 | constraint | Neo.ClientError.Schema.ConstraintValidationFailed | 23000 |
| Statement timeout | 504 | timeout | Neo.ClientError.Transaction.TransactionTimedOut | 57014 |
| Cancelled by an administrator | 409 | cancelled | Neo.TransientError.Transaction.Terminated | 57014 |
| Row cap, search result limits or per-query memory budget | 413 | row_cap, search_result_limit, search_document_limit, query_memory_limit | Neo.ClientError.Statement.ResourceLimitExceeded | 54000 |
| Transient resource pressure | 503 | search_index_cache_capacity, search_workspace_capacity, memory_pressure | Neo.TransientError.General.DatabaseUnavailable | 53000 |
| Unclassified server fault | 500 | — | Neo.DatabaseError.General.UnknownError | 50N42 |
Some failures carry only an error string: 401 / 403 auth failures, 413 for
an oversized body, 408 when the whole HTTP request exceeds
--http-request-timeout, and 503 when the server sheds load (writer lock
timeout, read admission queue full). Since 3.2.1 a statement refused or
stopped for memory gets the full body with code: "memory_pressure"
(Memory).
Retry policy. Retry 503 with backoff; it is transient by design. Do not blindly retry 504 or 413: the same statement exceeds the same budget again. Fix 400 and 409 in the request.
GET /v0/health
{"status": "ok", "namespace": "prod", "manifest_version": 8, "epoch": 0, "writer": "ok", "memtable_bytes": 0, "memory_resident_bytes": 26001408, "memory_max_bytes": 0, "memory_pressure": false}| Field | Meaning |
|---|---|
status | ok, or degraded (HTTP 503) when the writer is degraded or the memory ceiling is reached |
manifest_version | Current committed version; increases with every commit |
epoch | Writer epoch; increases each time a writer claims the namespace |
writer | ok or degraded; writer_error explains a degraded writer |
memtable_bytes | Unflushed in-memory table size (single-tenant only) |
memory_resident_bytes, memory_max_bytes, memory_pressure | Process memory vs. --memory-max-bytes (0 = no ceiling) |
Use it as a readiness probe. Use GET /v0/livez ({"status":"ok"}, no
locks, no namespace access) as the liveness probe.
GET /v0/version
{"version": "3.3.0", "build_target": "namidb-server"}GET /v0/metrics
Prometheus text exposition. Metric names and labels are listed in Monitoring.
POST /v0/admin/flush
Turns the in-memory table into level-0 data files now.
{"ssts_written": 1, "bloom_sidecars_written": 0, "manifest_version": 2}It is serialised process-wide, stays available under memory pressure, runs outside the HTTP request timeout, and finishes even if the client disconnects.
POST /v0/admin/compact
Drains level 0 completely and returns when done. Run it after a bulk load.
{"passes": 1, "l0_before": 5, "l0_after": 0, "source_ssts_removed": 5, "new_ssts_written": 1, "manifest_version": 11, "truncated": false}truncated: true means the drain hit its 128-pass bound; call it again. A
concurrent call gets 503. See Maintenance.
POST /v0/admin/backup
Copies a point-in-time snapshot to an allowlisted location. Disabled (403)
unless the server runs with --backup-target-uri.
{"to": "s3://backups/namidb/nightly?ns=prod®ion=us-east-1", "verify": true}| Field | Default | Meaning |
|---|---|---|
to | required | Destination namespace URI, inside the allowlist |
version | current | Manifest version to copy |
as_of | — | Copy the namespace as it was at this RFC 3339 instant (or manifest version); exclusive with version |
force | false | Overwrite a destination that already holds a namespace |
verify | false | Re-read and check every copied object |
{"bytes_copied": 38889, "objects_copied": 14, "source_created_at": "2026-11-04T06:53:07.714138144Z", "source_version": 8}Rules and status codes: Backup and restore.
GET /v0/admin/restore-points
The restore point window: the instants a backup’s as_of can copy. Kept
only when the server runs with --restore-point-retention; otherwise the
window is the current version. limit (1–1000, default 100) and before
page through the points, newest first.
{"enabled": true, "retention_secs": 604800, "lease_expires_at": "2026-11-11T07:08:07Z", "earliest": {"version": 0, "created_at": "2026-11-04T06:53:07.699556648Z"}, "latest": {"version": 2, "created_at": "2026-11-04T06:53:11.764359941Z"}, "points": [{"version": 2, "created_at": "2026-11-04T06:53:11.764359941Z"}], "next_before": 2}Details and errors: Restore points.
GET /v0/admin/queries
{"queries": [ {"id": 8, "protocol": "http", "namespace": "prod", "statement": "MATCH (a:N), (b:N), (c:N) RETURN count(*)", "elapsed_ms": 2077}]}Longest-running first. statement is the whitespace-collapsed text,
truncated to 300 characters; parameters are never included.
POST /v0/admin/queries/:id/cancel
{"cancelled": 8}The query is flagged and stops at its next cancellation check with 409
code: "cancelled" (“query cancelled by administrator”); a write is rolled
back. Cancellation is cooperative, and since 3.3.0 every operator checks
for it at least once per 1,024 rows, so a statement stops within
milliseconds. 404 means the query already finished (or never existed). In multi-tenant mode both routes only see the
namespace in the path or header.