Skip to content

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/v1

Authentication

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

MethodPathPurpose
POST/v1/{database}/cypherRun one Cypher statement
GET/v1/{database}/schemaLabels, relationship types, constraints and indexes
GET/v1/databasesDatabases this key can reach
POST/v1/{database}/mcpMCP for AI agents, see MCP
GET/v1/{database}/queriesStatements running on the database now (read-write keys)
POST/v1/{database}/queries/{id}/cancelCancel one of them (read-write keys)
GET/v1/healthLiveness, no key needed

POST /v1/{database}/cypher

Terminal window
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}}'
FieldTypeRequiredNotes
querystringyesExactly one statement.
paramsobjectnoValues 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
}
}
  • columns lists the result columns in RETURN order; each row is an object keyed by column name.
  • Results are limited to 64 MiB (413 result_too_large): paginate with SKIP / LIMIT or 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 one plan column.

Values

Results use the engine’s JSON encoding:

CypherJSON
Node{"_kind": "node", "id", "label", "labels", "properties"}
Relationship{"_kind": "rel", "edge_type", "src", "dst", "properties"}
Patharray alternating nodes and relationships
DATETIMERFC 3339 string in UTC
BYTESbase64 string
VECTORarray of numbers
INTEGERnumber (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

Terminal window
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. statement is 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 cancelled error (409). 404 query_not_found when 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:

StatusCodeMeaning
400bad_request, parse_error, …Malformed request or Cypher the engine rejects
401unauthorizedMissing, invalid, revoked or expired key
403read_only_key, database_not_in_scope, ip_not_allowed, org_paused, org_suspended, access_bannedNot allowed
404database_not_foundNo such database
413payload_too_large, result_too_large, query_memory_limitOver 2 MiB in, 64 MiB out, or more working memory than one query may use
429rate_limited, plan_limitWait for Retry-After
502 / 503engine_unavailable, engine_starting, database_unavailable, control_plane_unavailable, memory_pressureTransient or restoring
504timeoutOver 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-After on 429 and on 503 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 MERGE with a key so a repeat is harmless.

The SDKs implement exactly these rules.