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/v1Autenticació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étodo | Ruta | Propósito |
|---|---|---|
POST | /v1/{database}/cypher | Ejecutar una sentencia Cypher |
GET | /v1/{database}/schema | Labels, tipos de relación, constraints e índices |
GET | /v1/databases | Bases de datos a las que llega esta key |
POST | /v1/{database}/mcp | MCP para agentes de IA, consulta MCP |
GET | /v1/{database}/queries | Sentencias que se están ejecutando ahora en la base de datos (keys de lectura y escritura) |
POST | /v1/{database}/queries/{id}/cancel | Cancelar una de ellas (keys de lectura y escritura) |
GET | /v1/health | Liveness, no requiere key |
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}}'| Campo | Tipo | Obligatorio | Notas |
|---|---|---|---|
query | string | sí | Exactamente una sentencia. |
params | object | no | Valores 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 }}columnslista las columnas del resultado en el orden delRETURN; 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 conSKIP/LIMITo 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 columnaplan.
Valores
Los resultados usan la codificación JSON del motor:
| Cypher | JSON |
|---|---|
| Nodo | {"_kind": "node", "id", "label", "labels", "properties"} |
| Relación | {"_kind": "rel", "edge_type", "src", "dst", "properties"} |
| Camino | array que alterna nodos y relaciones |
DATETIME | string RFC 3339 en UTC |
BYTES | string base64 |
VECTOR | array de números |
INTEGER | nú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
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.
statementtiene 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
cancelleddel motor (409).404 query_not_foundcuando 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:
| Estado | Código | Significado |
|---|---|---|
| 400 | bad_request, parse_error, … | Petición mal formada o Cypher que el motor rechaza |
| 401 | unauthorized | Key ausente, inválida, revocada o vencida |
| 403 | read_only_key, database_not_in_scope, ip_not_allowed, org_paused, org_suspended, access_banned | No permitido |
| 404 | database_not_found | No existe esa base de datos |
| 413 | payload_too_large, result_too_large, query_memory_limit | Más de 2 MiB de entrada, 64 MiB de salida, o más memoria de trabajo de la que puede usar una consulta |
| 429 | rate_limited, plan_limit | Espera lo que indique Retry-After |
| 502 / 503 | engine_unavailable, engine_starting, database_unavailable, control_plane_unavailable, memory_pressure | Transitorio o en restauración |
| 504 | timeout | Superó 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-Afteren429y en503 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
MERGEcon una clave para que una repetición sea inofensiva.
Los SDKs implementan exactamente estas reglas.