Saltearse al contenido

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>
EstadoSignificado
401Token ausente o desconocido, o (multi-tenant) un token sin alcance sobre el namespace solicitado.
403Un 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étodoRutaAutenticaciónPropósito
POST/v0/cyphertokenEjecuta una sentencia Cypher
GET/v0/livezpúblicaLiveness
GET/v0/healthpúblicaReadiness
GET/v0/versionpúblicaVersión del build
GET/v0/metricspúblicaMétricas de Prometheus
POST/v0/admin/flushlectura y escrituraHace flush de la tabla en memoria
POST/v0/admin/compactlectura y escrituraVacía el nivel 0, bloqueante
POST/v0/admin/backuplectura y escrituraBackup en línea, también a un instante anterior (as_of)
GET/v0/admin/restore-pointslectura y escrituraLa ventana de puntos de restauración
GET/v0/admin/querieslectura y escrituraLista las consultas en curso
POST/v0/admin/queries/:id/cancellectura y escrituraCancela 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}
}
CampoTipoObligatorioNotas
querystringsíExactamente una sentencia.
paramsobjectnoValores 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
}
}
  • columns lista las columnas del resultado en el orden del RETURN. Cada fila es un objeto indexado por nombre de columna; las claves dentro de un objeto de fila no tienen orden, así que usa columns para el orden de presentación.
  • El DDL (CREATE INDEX, …) retorna {"columns": [], "rows": []}.
  • EXPLAIN … retorna una columna plan con una fila por línea del plan.
Ventana de terminal
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

CypherJSON en los resultadosJSON como parámetro
NULLnullnull
BOOLEANtrue / falsetrue / false
INTEGERnúmeronúmero entero
FLOATnúmero (NaN / Infinity se convierten en null)número con parte fraccionaria o exponente
STRINGstringstring
LISTarrayarray
MAPobjectobject
VECTORarray de númerosarray de números
BYTESstring base64—
DATEstring con los días desde 1970-01-01 ("20758" para 2026-11-01)—
DATETIMEstring 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"}—
Caminoarray 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ónHTTPcodeneo4j_codegql_status
Error de sintaxis400parse_errorNeo.ClientError.Statement.SyntaxError42001
Error semántico / de planificación400plan_errorNeo.ClientError.Statement.SemanticError42000
Funcionalidad no soportada400unsupportedNeo.ClientError.Statement.NotSupported0A000
Error de evaluación (división entre cero, $param faltante, tipos incompatibles)400eval_errorNeo.ClientError.Statement.ArgumentError22000
Violación de restricción (clave única, dimensión del vector, DELETE de un nodo conectado)409constraintNeo.ClientError.Schema.ConstraintValidationFailed23000
Timeout de la sentencia504timeoutNeo.ClientError.Transaction.TransactionTimedOut57014
Cancelada por un administrador409cancelledNeo.TransientError.Transaction.Terminated57014
Límite de filas, límites de resultados de búsqueda o presupuesto de memoria por consulta413row_cap, search_result_limit, search_document_limit, query_memory_limitNeo.ClientError.Statement.ResourceLimitExceeded54000
Presión transitoria de recursos503search_index_cache_capacity, search_workspace_capacity, memory_pressureNeo.TransientError.General.DatabaseUnavailable53000
Fallo del servidor no clasificado500—Neo.DatabaseError.General.UnknownError50N42

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}
CampoSignificado
statusok, o degraded (HTTP 503) cuando el writer está degradado o se alcanzó el tope de memoria
manifest_versionVersión confirmada actual; aumenta con cada commit
epochEpoch del writer; aumenta cada vez que un writer reclama el namespace
writerok o degraded; writer_error explica un writer degradado
memtable_bytesTamaño de la tabla en memoria sin flush (solo single-tenant)
memory_resident_bytes, memory_max_bytes, memory_pressureMemoria 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&region=us-east-1", "verify": true}
CampoPor defectoSignificado
toobligatorioURI del namespace de destino, dentro de la allowlist
versionla actualVersió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
forcefalseSobrescribe un destino que ya contiene un namespace
verifyfalseVuelve 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.