API HTTP
namidb-server expone una API JSON pequeña bajo /v0. Todos los cuerpos de
petición y respuesta son JSON (Content-Type: application/json), excepto
/v0/metrics, que es texto de Prometheus.
Autenticación
Envía un bearer token en cada ruta privada:
Authorization: Bearer <token>| Estado | Significado |
|---|---|
| 401 | Token ausente o desconocido, o (multi-tenant) un token sin alcance sobre el namespace solicitado. |
| 403 | Un token de solo lectura intentó una escritura, DDL o una acción de administración. |
/v0/livez, /v0/health, /v0/version y /v0/metrics nunca requieren un
token. Consulta Autenticación
para archivos de tokens, JWT y hooks de políticas.
Rutas
| Método | Ruta | Autenticación | Propósito |
|---|---|---|---|
POST | /v0/cypher | token | Ejecuta una sentencia Cypher |
GET | /v0/livez | pública | Liveness |
GET | /v0/health | pública | Readiness |
GET | /v0/version | pública | Versión del build |
GET | /v0/metrics | pública | Métricas de Prometheus |
POST | /v0/admin/flush | lectura y escritura | Hace flush de la tabla en memoria |
POST | /v0/admin/compact | lectura y escritura | Vacía el nivel 0, bloqueante |
POST | /v0/admin/backup | lectura y escritura | Backup en línea, también a un instante anterior (as_of) |
GET | /v0/admin/restore-points | lectura y escritura | La ventana de puntos de restauración |
GET | /v0/admin/queries | lectura y escritura | Lista las consultas en curso |
POST | /v0/admin/queries/:id/cancel | lectura y escritura | Cancela una consulta |
En modo multi-tenant, todas las rutas
excepto /v0/version y /v0/metrics también existen como
/:namespace/v0/…, la forma sin prefijo toma el header
X-NamiDB-Namespace, y se agrega POST /:namespace/v0/admin/restore.
POST /v0/cypher
Petición
{ "query": "MATCH (p:Person) WHERE p.age >= $min RETURN p.name AS name", "params": {"min": 18}}| Campo | Tipo | Obligatorio | Notas |
|---|---|---|---|
query | string | sí | Exactamente una sentencia. |
params | object | no | Valores para los parámetros $name. |
El cuerpo está limitado a 2 MiB; envía los lotes más grandes en varias peticiones.
Respuesta
Una lectura:
{"columns": ["name"], "rows": [{"name": "Alice"}, {"name": "Bob"}]}Una escritura agrega write_outcome:
{ "columns": ["name"], "rows": [{"name": "Ada"}], "write_outcome": { "nodes_created": 1, "edges_created": 0, "nodes_deleted": 0, "edges_deleted": 0, "properties_set": 0 }}columnslista las columnas del resultado en el orden delRETURN. Cada fila es un objeto indexado por nombre de columna; las claves dentro de un objeto de fila no tienen orden, así que usacolumnspara el orden de presentación.- El DDL (
CREATE INDEX, …) retorna{"columns": [], "rows": []}. EXPLAIN …retorna una columnaplancon una fila por línea del plan.
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"}]}Mapeo de valores
| Cypher | JSON en los resultados | JSON como parámetro |
|---|---|---|
NULL | null | null |
BOOLEAN | true / false | true / false |
INTEGER | número | número entero |
FLOAT | número (NaN / Infinity se convierten en null) | número con parte fraccionaria o exponente |
STRING | string | string |
LIST | array | array |
MAP | object | object |
VECTOR | array de números | array de números |
BYTES | string base64 | — |
DATE | string con los días desde 1970-01-01 ("20758" para 2026-11-01) | — |
DATETIME | string RFC 3339 en UTC ("2026-11-01T10:00:00+00:00") | — |
| Nodo | {"_kind": "node", "id", "label", "labels", "properties"} | — |
| Relación | {"_kind": "rel", "edge_type", "src", "dst", "properties"} | — |
| Camino | array que alterna objetos de nodos y de relaciones | — |
Para las fechas, retorna toString(d) para obtener texto ISO
("2026-11-01"), y pasa fechas y datetimes como strings convertidos en la
consulta: date($day), datetime($ts).
Un objeto de nodo:
{"_kind": "node", "id": "01a19a39-6785-71b1-8e40-34a60eef3b9f", "label": "Person", "labels": ["Person"], "properties": {"age": 30, "name": "Alice"}}label es el primer label (se conserva para clientes antiguos); labels
es el conjunto completo. Una relación:
{"_kind": "rel", "edge_type": "KNOWS", "src": "01a19a39-6785-71b1-8e40-34a60eef3b9f", "dst": "01a19a39-67f6-7202-b0ad-0369cfce38c3", "properties": {"since": 2020}}Errores
Una sentencia fallida retorna un cuerpo JSON con campos legibles por máquina:
{ "error": "read execution failed: EvalError: integer division by zero at [7..10)", "code": "eval_error", "neo4j_code": "Neo.ClientError.Statement.ArgumentError", "gql_status": "22000"}| Condición | HTTP | code | neo4j_code | gql_status |
|---|---|---|---|---|
| Error de sintaxis | 400 | parse_error | Neo.ClientError.Statement.SyntaxError | 42001 |
| Error semántico / de planificación | 400 | plan_error | Neo.ClientError.Statement.SemanticError | 42000 |
| Funcionalidad no soportada | 400 | unsupported | Neo.ClientError.Statement.NotSupported | 0A000 |
Error de evaluación (división entre cero, $param faltante, tipos incompatibles) | 400 | eval_error | Neo.ClientError.Statement.ArgumentError | 22000 |
Violación de restricción (clave única, dimensión del vector, DELETE de un nodo conectado) | 409 | constraint | Neo.ClientError.Schema.ConstraintValidationFailed | 23000 |
| Timeout de la sentencia | 504 | timeout | Neo.ClientError.Transaction.TransactionTimedOut | 57014 |
| Cancelada por un administrador | 409 | cancelled | Neo.TransientError.Transaction.Terminated | 57014 |
| Límite de filas, límites de resultados de búsqueda o presupuesto de memoria por consulta | 413 | row_cap, search_result_limit, search_document_limit, query_memory_limit | Neo.ClientError.Statement.ResourceLimitExceeded | 54000 |
| Presión transitoria de recursos | 503 | search_index_cache_capacity, search_workspace_capacity, memory_pressure | Neo.TransientError.General.DatabaseUnavailable | 53000 |
| Fallo del servidor no clasificado | 500 | — | Neo.DatabaseError.General.UnknownError | 50N42 |
Algunos fallos solo llevan un string error: los fallos de autenticación
401 / 403, 413 para un cuerpo demasiado grande, 408 cuando la petición HTTP
completa supera --http-request-timeout, y 503 cuando el servidor descarta
carga (timeout del lock del writer, cola de admisión de lecturas llena).
Desde 3.2.1, una sentencia rechazada o detenida por memoria recibe el cuerpo
completo con code: "memory_pressure"
(Memoria).
Política de reintentos. Reintenta los 503 con backoff; son transitorios por diseño. No reintentes a ciegas los 504 ni los 413: la misma sentencia vuelve a superar el mismo presupuesto. Corrige los 400 y los 409 en la petición.
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}| Campo | Significado |
|---|---|
status | ok, o degraded (HTTP 503) cuando el writer está degradado o se alcanzó el tope de memoria |
manifest_version | Versión confirmada actual; aumenta con cada commit |
epoch | Epoch del writer; aumenta cada vez que un writer reclama el namespace |
writer | ok o degraded; writer_error explica un writer degradado |
memtable_bytes | Tamaño de la tabla en memoria sin flush (solo single-tenant) |
memory_resident_bytes, memory_max_bytes, memory_pressure | Memoria del proceso frente a --memory-max-bytes (0 = sin tope) |
Úsalo como readiness probe. Usa GET /v0/livez ({"status":"ok"}, sin
locks y sin acceso a namespaces) como liveness probe.
GET /v0/version
{"version": "3.3.0", "build_target": "namidb-server"}GET /v0/metrics
Exposición en texto de Prometheus. Los nombres y labels de las métricas están en Monitoreo.
POST /v0/admin/flush
Convierte ahora la tabla en memoria en archivos de datos de nivel 0.
{"ssts_written": 1, "bloom_sidecars_written": 0, "manifest_version": 2}Se serializa en todo el proceso, sigue disponible bajo presión de memoria, se ejecuta fuera del timeout de la petición HTTP y termina aunque el cliente se desconecte.
POST /v0/admin/compact
Vacía por completo el nivel 0 y retorna al terminar. Ejecútalo después de una carga masiva.
{"passes": 1, "l0_before": 5, "l0_after": 0, "source_ssts_removed": 5, "new_ssts_written": 1, "manifest_version": 11, "truncated": false}truncated: true significa que el vaciado llegó a su límite de 128
pasadas; vuelve a llamarlo. Una llamada concurrente recibe 503. Consulta
Mantenimiento.
POST /v0/admin/backup
Copia un snapshot point-in-time a una ubicación permitida en la allowlist.
Está desactivado (403) salvo que el servidor se ejecute con
--backup-target-uri.
{"to": "s3://backups/namidb/nightly?ns=prod®ion=us-east-1", "verify": true}| Campo | Por defecto | Significado |
|---|---|---|
to | obligatorio | URI del namespace de destino, dentro de la allowlist |
version | la actual | Versión del manifest a copiar |
as_of | — | Copia el namespace tal como estaba en este instante RFC 3339 (o versión del manifest); excluyente con version |
force | false | Sobrescribe un destino que ya contiene un namespace |
verify | false | Vuelve a leer y comprueba cada objeto copiado |
{"bytes_copied": 38889, "objects_copied": 14, "source_created_at": "2026-11-04T06:53:07.714138144Z", "source_version": 8}Reglas y códigos de estado: Backup y restore.
GET /v0/admin/restore-points
La ventana de puntos de restauración: los instantes que puede copiar el
as_of de un backup. Solo se conserva cuando el servidor se ejecuta con
--restore-point-retention; si no, la ventana es la versión actual.
limit (1–1000, 100 por defecto) y before recorren los puntos, del más
reciente al más antiguo.
{"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}Detalles y errores: Puntos de restauración.
GET /v0/admin/queries
{"queries": [ {"id": 8, "protocol": "http", "namespace": "prod", "statement": "MATCH (a:N), (b:N), (c:N) RETURN count(*)", "elapsed_ms": 2077}]}Las de mayor duración primero. statement es el texto con los espacios en
blanco colapsados, truncado a 300 caracteres; los parámetros nunca se
incluyen.
POST /v0/admin/queries/:id/cancel
{"cancelled": 8}La consulta se marca y se detiene en su siguiente punto de verificación de
cancelación con 409 code: "cancelled" (“query cancelled by
administrator”); una escritura se revierte. La cancelación es cooperativa,
y desde 3.3.0 cada operador la revisa al menos una vez cada 1.024 filas,
así que una sentencia se detiene en milisegundos. 404 significa que la consulta ya terminó (o nunca
existió). En modo multi-tenant, ambas rutas solo ven el namespace de la
ruta o del header.