Saltearse al contenido

API HTTP

La API de datos ejecuta Cypher sobre HTTPS. Es lo que llaman los SDKs de JavaScript y Python, y puedes llamarla desde cualquier lenguaje.

https://db.namidb.com/v1

Autenticación

Envía una API key en cada petición:

Authorization: Bearer nmdb_live_…

X-NamiDB-Key: nmdb_live_… también funciona. La key decide la organización; la ruta nombra la base de datos. Los tokens de gestión (nmdb_mgmt_…) se rechazan aquí.

Rutas

MétodoRutaPropósito
POST/v1/{database}/cypherEjecutar una sentencia Cypher
GET/v1/{database}/schemaLabels, tipos de relación, constraints e índices
GET/v1/databasesBases de datos a las que llega esta key
POST/v1/{database}/mcpMCP para agentes de IA, consulta MCP
GET/v1/{database}/queriesSentencias que se están ejecutando ahora en la base de datos (keys de lectura y escritura)
POST/v1/{database}/queries/{id}/cancelCancelar una de ellas (keys de lectura y escritura)
GET/v1/healthLiveness, no requiere key

POST /v1/{database}/cypher

Ventana de terminal
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}}'
CampoTipoObligatorioNotas
querystringsíExactamente una sentencia.
paramsobjectnoValores para los parámetros $name. Pasa siempre los valores como parámetros en lugar de armar strings de consulta.

El cuerpo está limitado a 2 MiB (413 payload_too_large). Envía las cargas más grandes en lotes; los helpers de carga masiva de los SDKs lo hacen por ti.

Respuesta

{"columns": ["title"], "rows": [{"title": "Heat"}, {"title": "The Matrix"}]}

Una sentencia que escribió agrega write_outcome:

{
"columns": [],
"rows": [],
"write_outcome": {
"nodes_created": 1, "edges_created": 0,
"nodes_deleted": 0, "edges_deleted": 0,
"properties_set": 2
}
}
  • columns lista las columnas del resultado en el orden del RETURN; cada fila es un objeto con el nombre de la columna como clave.
  • Los resultados están limitados a 64 MiB (413 result_too_large): pagina con SKIP / LIMIT o devuelve menos propiedades.
  • Cada sentencia tiene el timeout de consulta del plan: 10 s en Free, 30 s en Pro, 60 s en Scale (error del motor timeout, estado 504).
  • EXPLAIN … devuelve el plan como filas de una única columna plan.

Valores

Los resultados usan la codificación JSON del motor:

CypherJSON
Nodo{"_kind": "node", "id", "label", "labels", "properties"}
Relación{"_kind": "rel", "edge_type", "src", "dst", "properties"}
Caminoarray que alterna nodos y relaciones
DATETIMEstring RFC 3339 en UTC
BYTESstring base64
VECTORarray de números
INTEGERnúmero (por encima de 2^53, JavaScript pierde precisión: usa strings para ids grandes)

La tabla completa, incluidas las fechas, está en la página de la API HTTP de self-hosted; el motor es el mismo.

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 e indexes son las filas de SHOW CONSTRAINTS y SHOW INDEXES. La ruta lee solo metadatos del esquema y nunca recorre los datos. Cuenta como una petición de lectura.

GET /v1/databases

{"databases": [{"name": "movies", "status": "ready", "readOnly": false}]}

readOnly es true para una base de datos que supera el límite del plan después de bajar de plan.

Consultas en curso y cancelación

Ventana de terminal
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}
  • Solo keys de lectura y escritura (403 read_only_key), ya que el texto de la sentencia puede incluir literales.
  • Lista primero las que llevan más tiempo en ejecución. statement tiene los espacios en blanco colapsados y como máximo 300 caracteres; nunca se incluyen los parámetros.
  • Una sentencia cancelada se detiene en su siguiente punto de control, en milisegundos, y su cliente recibe el error cancelled del motor (409). 404 query_not_found cuando ya no se está ejecutando.
  • No cuentan como peticiones. Listarlas nunca despierta una base de datos dormida (simplemente no tiene nada en ejecución), y consultarlas periódicamente no mantiene despierta a una inactiva.

La pestaña Activity de la consola es la misma funcionalidad con un botón Cancel.

Errores

Todos los errores tienen la misma forma:

{"error": {"code": "read_only_key", "message": "…", "request_id": "c1f0…"}}

Decide según code, nunca según message. Los más comunes:

EstadoCódigoSignificado
400bad_request, parse_error, …Petición mal formada o Cypher que el motor rechaza
401unauthorizedKey ausente, inválida, revocada o vencida
403read_only_key, database_not_in_scope, ip_not_allowed, org_paused, org_suspended, access_bannedNo permitido
404database_not_foundNo existe esa base de datos
413payload_too_large, result_too_large, query_memory_limitMás de 2 MiB de entrada, 64 MiB de salida, o más memoria de trabajo de la que puede usar una consulta
429rate_limited, plan_limitEspera lo que indique Retry-After
502 / 503engine_unavailable, engine_starting, database_unavailable, control_plane_unavailable, memory_pressureTransitorio o en restauración
504timeoutSuperó el timeout de consulta del plan

Todos los códigos, con qué hacer en cada caso: Errores.

Cabeceras

Cada respuesta incluye:

  • x-request-id: inclúyelo cuando contactes a soporte.
  • x-namidb-engine-ms: tiempo pasado en el motor, sin red ni cola.
  • Retry-After en 429 y en 503 engine_starting.

CORS

Todas las rutas /v1/* se pueden llamar desde cualquier origen sin credenciales (Access-Control-Allow-Origin: *). Cabeceras de petición permitidas: authorization, content-type, x-namidb-key, mcp-protocol-version. Expuestas: x-request-id, x-namidb-engine-ms, retry-after.

Una key en código de navegador es visible para todos los visitantes. Mantén las keys en un servidor o en una función edge; si una tiene que llegar al navegador, usa una key de solo lectura con alcance sobre una sola base de datos, con una IP allowlist cuando sea posible.

Reintentos

  • Seguros de reintentar: rate_limited, engine_starting, control_plane_unavailable (la sentencia nunca se ejecutó) y cualquier lectura.
  • No reintentes escrituras a ciegas después de un timeout o un error de conexión: la escritura puede haberse confirmado. Usa MERGE con una clave para que una repetición sea inofensiva.

Los SDKs implementan exactamente estas reglas.