Skip to content

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>
StatusMeaning
401Missing or unknown token, or (multi-tenant) a token not scoped to the requested namespace.
403A 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

MethodPathAuthPurpose
POST/v0/cyphertokenRun one Cypher statement
GET/v0/livezpublicLiveness
GET/v0/healthpublicReadiness
GET/v0/versionpublicBuild version
GET/v0/metricspublicPrometheus metrics
POST/v0/admin/flushread-writeFlush the in-memory table
POST/v0/admin/compactread-writeDrain level 0, blocking
POST/v0/admin/backupread-writeOnline backup, also as of an earlier instant (as_of)
GET/v0/admin/restore-pointsread-writeThe restore point window
GET/v0/admin/queriesread-writeList in-flight queries
POST/v0/admin/queries/:id/cancelread-writeCancel 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}
}
FieldTypeRequiredNotes
querystringyesExactly one statement.
paramsobjectnoValues 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
}
}
  • columns lists the result columns in RETURN order. Each row is an object keyed by column name; the keys inside a row object are not ordered, so use columns for display order.
  • DDL (CREATE INDEX, …) returns {"columns": [], "rows": []}.
  • EXPLAIN … returns one plan column with one row per plan line.
Terminal window
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

CypherJSON in resultsJSON as a parameter
NULLnullnull
BOOLEANtrue / falsetrue / false
INTEGERnumberinteger number
FLOATnumber (NaN / Infinity become null)number with a fraction or exponent
STRINGstringstring
LISTarrayarray
MAPobjectobject
VECTORarray of numbersarray of numbers
BYTESbase64 string—
DATEstring holding days since 1970-01-01 ("20758" for 2026-11-01)—
DATETIMERFC 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"}—
Patharray 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"
}
ConditionHTTPcodeneo4j_codegql_status
Syntax error400parse_errorNeo.ClientError.Statement.SyntaxError42001
Semantic / planning error400plan_errorNeo.ClientError.Statement.SemanticError42000
Feature not supported400unsupportedNeo.ClientError.Statement.NotSupported0A000
Evaluation error (division by zero, missing $param, type mismatch)400eval_errorNeo.ClientError.Statement.ArgumentError22000
Constraint violation (unique key, vector dimension, DELETE of a connected node)409constraintNeo.ClientError.Schema.ConstraintValidationFailed23000
Statement timeout504timeoutNeo.ClientError.Transaction.TransactionTimedOut57014
Cancelled by an administrator409cancelledNeo.TransientError.Transaction.Terminated57014
Row cap, search result limits or per-query memory budget413row_cap, search_result_limit, search_document_limit, query_memory_limitNeo.ClientError.Statement.ResourceLimitExceeded54000
Transient resource pressure503search_index_cache_capacity, search_workspace_capacity, memory_pressureNeo.TransientError.General.DatabaseUnavailable53000
Unclassified server fault500—Neo.DatabaseError.General.UnknownError50N42

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}
FieldMeaning
statusok, or degraded (HTTP 503) when the writer is degraded or the memory ceiling is reached
manifest_versionCurrent committed version; increases with every commit
epochWriter epoch; increases each time a writer claims the namespace
writerok or degraded; writer_error explains a degraded writer
memtable_bytesUnflushed in-memory table size (single-tenant only)
memory_resident_bytes, memory_max_bytes, memory_pressureProcess 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&region=us-east-1", "verify": true}
FieldDefaultMeaning
torequiredDestination namespace URI, inside the allowlist
versioncurrentManifest version to copy
as_of—Copy the namespace as it was at this RFC 3339 instant (or manifest version); exclusive with version
forcefalseOverwrite a destination that already holds a namespace
verifyfalseRe-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.