HTTP API

namidb-server exposes a small JSON-over-HTTP API on top of the engine. Four endpoints, one auth scheme, one envelope.

For starting the server, flags, and concurrency model, see HTTP server.

Routes (v0)

Method	Path	Auth	Description
`GET`	`/v0/health`	public	Liveness + manifest version + epoch
`GET`	`/v0/version`	public	Server build version
`POST`	`/v0/cypher`	bearer	Run a Cypher query (read or write)
`POST`	`/v0/admin/flush`	bearer	Force a memtable to L0 SST flush

Authentication

POST endpoints require Authorization: Bearer <token> where <token> matches the server’s --auth-token flag (or the NAMIDB_AUTH_TOKEN env var). GET endpoints (/v0/health, /v0/version) are public.

If the server is started without an auth token, every request is accepted; the daemon prints a loud warning at boot and shouldn’t be exposed to the public internet.

`POST /v0/cypher`

Request

{
  "query": "MATCH (p:Person) WHERE p.age >= $min RETURN p.name AS name",
  "params": {"min": 18}
}

params is optional. The query string follows the supported subset.

Read response

{
  "columns": ["name"],
  "rows": [{"name": "Alice"}, {"name": "Bob"}]
}

Columns follow the projection order in the query’s RETURN, not the row map’s natural key order.

Write response

{
  "columns": ["a"],
  "rows": [{
    "a": {
      "_kind": "node",
      "id": "...",
      "label": "Person",
      "properties": {}
    }
  }],
  "write_outcome": {
    "nodes_created": 1,
    "edges_created": 0,
    "nodes_deleted": 0,
    "edges_deleted": 0,
    "properties_set": 0
  }
}

Write responses include a write_outcome object with per-operation counters. Counters increment per executor operation, not per net state change.

JSON ↔ Cypher type mapping

Cypher `RuntimeValue`	JSON
`Null`	`null`
`Bool`	`true` / `false`
`Integer`	number (i64)
`Float`	number (f64)
`String`	string
`Bytes`	base64 string
`Vector(f32)`	array of numbers
`List`	array
`Map`	object
`Date`	ISO-8601 date string
`DateTime` (UTC, microseconds)	RFC-3339 timestamp string
`Node`	`{"_kind": "node", "id", "label", "properties"}`
`Rel`	`{"_kind": "rel", "edge_type", "src", "dst", "properties"}`
`Path`	array of alternating node / rel objects

End-to-end `curl` round-trip

TOKEN=$(openssl rand -hex 32)

namidb-server --store memory://demo --listen 127.0.0.1:8080 --auth-token "$TOKEN" &

# Health
curl -s http://127.0.0.1:8080/v0/health | jq .

# Create
curl -s -X POST http://127.0.0.1:8080/v0/cypher \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"query": "CREATE (a:Person {name: \"Alice\", age: 30}) RETURN a.name AS name"}' \
  | jq .

# Read
curl -s -X POST http://127.0.0.1:8080/v0/cypher \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"query": "MATCH (p:Person) RETURN p.name AS name, p.age AS age"}' \
  | jq .

`POST /v0/admin/flush`

Forces the memtable to be flushed into L0 SSTs immediately. Useful when --flush-interval 0s disabled the background loop and a sidecar is driving the flush schedule instead.

curl -s -X POST http://127.0.0.1:8080/v0/admin/flush \
  -H "Authorization: Bearer $TOKEN"

On the roadmap

The server README lists these endpoints as planned but not landed yet:

/v0/cypher/stream — NDJSON streaming for large read result sets.
/v0/cypher/arrow — Arrow IPC body for zero-copy DataFrame ingestion.
/v0/metrics — Prometheus exposition (counters, latency histogram, cache hit rates).

What’s next

HTTP server — flags, env vars, concurrency model.
Bolt (Neo4j drivers) — when you want a binary, session-oriented protocol instead of REST.
Configuration — every env var the server reads.