HTTP API
The data API runs Cypher over HTTPS. It is what the JavaScript and Python SDKs call, and you can call it from any language.
https://db.namidb.com/v1Authentication
Send an API key on every request:
Authorization: Bearer nmdb_live_…X-NamiDB-Key: nmdb_live_… works too. The key decides the organization; the
path names the database. Management tokens (nmdb_mgmt_…) are refused here.
Routes
| Method | Path | Purpose |
|---|---|---|
POST | /v1/{database}/cypher | Run one Cypher statement |
GET | /v1/{database}/schema | Labels, relationship types, constraints and indexes |
GET | /v1/databases | Databases this key can reach |
POST | /v1/{database}/mcp | MCP for AI agents, see MCP |
GET | /v1/{database}/queries | Statements running on the database now (read-write keys) |
POST | /v1/{database}/queries/{id}/cancel | Cancel one of them (read-write keys) |
GET | /v1/health | Liveness, no key needed |
POST /v1/{database}/cypher
curl https://db.namidb.com/v1/movies/cypher \ -H "Authorization: Bearer $NAMIDB_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "MATCH (m:Movie) WHERE m.released >= $year RETURN m.title AS title", "params": {"year": 1990}}'| Field | Type | Required | Notes |
|---|---|---|---|
query | string | yes | Exactly one statement. |
params | object | no | Values for $name parameters. Always pass values as parameters rather than building query strings. |
The body is limited to 2 MiB (413 payload_too_large). Send larger loads
in batches; the SDKs’ bulk helpers do that for you.
Response
{"columns": ["title"], "rows": [{"title": "Heat"}, {"title": "The Matrix"}]}A statement that wrote adds write_outcome:
{ "columns": [], "rows": [], "write_outcome": { "nodes_created": 1, "edges_created": 0, "nodes_deleted": 0, "edges_deleted": 0, "properties_set": 2 }}columnslists the result columns inRETURNorder; each row is an object keyed by column name.- Results are limited to 64 MiB (
413 result_too_large): paginate withSKIP/LIMITor return fewer properties. - Each statement has the plan’s query timeout: 10 s on Free, 30 s on Pro,
60 s on Scale (engine error
timeout, status 504). EXPLAIN …returns the plan as rows of oneplancolumn.
Values
Results use the engine’s JSON encoding:
| Cypher | JSON |
|---|---|
| Node | {"_kind": "node", "id", "label", "labels", "properties"} |
| Relationship | {"_kind": "rel", "edge_type", "src", "dst", "properties"} |
| Path | array alternating nodes and relationships |
DATETIME | RFC 3339 string in UTC |
BYTES | base64 string |
VECTOR | array of numbers |
INTEGER | number (beyond 2^53, JavaScript loses precision: use strings for large ids) |
The full table, including dates, is on the self-hosted HTTP API page; the engine is the same.
GET /v1/{database}/schema
{ "database": "movies", "labels": ["Movie", "Person"], "relationship_types": ["ACTED_IN"], "constraints": [{"name": "movie_title", "type": "UNIQUENESS", "entityType": "NODE", "labelsOrTypes": ["Movie"], "properties": ["title"]}], "indexes": []}constraints and indexes are the rows of SHOW CONSTRAINTS and
SHOW INDEXES. The route reads schema metadata only and never scans data. It
counts as one read request.
GET /v1/databases
{"databases": [{"name": "movies", "status": "ready", "readOnly": false}]}readOnly is true for a database over the plan’s limit after a downgrade.
Running queries and cancel
curl https://db.namidb.com/v1/movies/queries -H "Authorization: Bearer $NAMIDB_API_KEY"# {"database":"movies","queries":[{"id":8,"protocol":"http","statement":"MATCH (a)-[*1..6]-(b) RETURN count(*)","elapsed_ms":8123}]}
curl -X POST https://db.namidb.com/v1/movies/queries/8/cancel -H "Authorization: Bearer $NAMIDB_API_KEY"# {"database":"movies","id":8,"cancelled":true}- Read-write keys only (
403 read_only_key), since statement text may include literals. - Lists the longest-running first.
statementis whitespace-collapsed and at most 300 characters; parameters are never included. - A cancelled statement stops at its next check, within milliseconds, and
its client gets the engine’s
cancellederror (409).404 query_not_foundwhen it is no longer running. - Not counted as requests. Listing never wakes a sleeping database (it simply has nothing running), and polling does not keep an idle one awake.
The console’s Activity tab is the same feature with a Cancel button.
Errors
Every error has one shape:
{"error": {"code": "read_only_key", "message": "…", "request_id": "c1f0…"}}Branch on code, never on message. The most common:
| Status | Code | Meaning |
|---|---|---|
| 400 | bad_request, parse_error, … | Malformed request or Cypher the engine rejects |
| 401 | unauthorized | Missing, invalid, revoked or expired key |
| 403 | read_only_key, database_not_in_scope, ip_not_allowed, org_paused, org_suspended, access_banned | Not allowed |
| 404 | database_not_found | No such database |
| 413 | payload_too_large, result_too_large, query_memory_limit | Over 2 MiB in, 64 MiB out, or more working memory than one query may use |
| 429 | rate_limited, plan_limit | Wait for Retry-After |
| 502 / 503 | engine_unavailable, engine_starting, database_unavailable, control_plane_unavailable, memory_pressure | Transient or restoring |
| 504 | timeout | Over the plan’s query timeout |
Every code, with what to do about it: Errors.
Headers
Every response carries:
x-request-id: quote it when you contact support.x-namidb-engine-ms: time spent in the engine, without network and queueing.Retry-Afteron429and on503 engine_starting.
CORS
Every /v1/* route can be called from any origin without credentials
(Access-Control-Allow-Origin: *). Allowed request headers:
authorization, content-type, x-namidb-key, mcp-protocol-version.
Exposed: x-request-id, x-namidb-engine-ms, retry-after.
A key in browser code is visible to every visitor. Keep keys on a server or an edge function; if one must reach the browser, use a read-only key scoped to one database, with an IP allowlist where possible.
Retries
- Safe to retry:
rate_limited,engine_starting,control_plane_unavailable(the statement never ran), and any read. - Don’t blindly retry writes after a timeout or a connection error: the
write may have committed. Use
MERGEwith a key so a repeat is harmless.
The SDKs implement exactly these rules.