API de gestión
La API de gestión opera una organización de NamiDB Cloud desde código: crear y eliminar bases de datos, generar y rotar API keys, emitir tokens de gestión para otras herramientas, tomar backups, restaurar (también a un punto en el tiempo), clonar y exportar, gestionar IP allowlists, leer el uso, gestionar miembros e invitaciones, y abrir tickets de soporte. Úsala desde pipelines de CI, scripts e infraestructura como código.
https://app.namidb.com/api/v1El contrato legible por máquinas es el documento OpenAPI 3.1 en
https://app.namidb.com/api/v1/openapi.json.
Cárgalo en Postman, Insomnia o un generador de código. Donde esta página y el
documento no coincidan, prevalece el documento.
¿API de gestión o API de datos?
| API de gestión | API de datos | |
|---|---|---|
| Qué hace | Gestiona bases de datos, keys, backups, personas | Ejecuta Cypher (HTTP, Bolt, MCP) |
| URL base | https://app.namidb.com/api/v1 | https://db.namidb.com/v1 |
| Credencial | Token de gestión nmdb_mgmt_… | API key nmdb_live_… |
| Clase del SDK | ManagementClient | NamiDB |
Autenticación
Envía un token de gestión como bearer token:
curl https://app.namidb.com/api/v1/organization \ -H "Authorization: Bearer $NAMIDB_MANAGEMENT_TOKEN"Un token pertenece a una organización, así que ninguna ruta nombra la organización. Su scope decide qué puede llamar:
| Scope | Permite |
|---|---|
read | Todos los GET excepto invitaciones y tokens de gestión |
write | read, más bases de datos, backups, restauraciones, clones, exportaciones y tickets de soporte |
admin | write, más API keys, IP allowlists, miembros, invitaciones y tokens de gestión |
Cada operación de abajo indica el scope que necesita. Un token con un scope
insuficiente recibe 403 insufficient_scope.
Convenciones
- Los cuerpos de petición y respuesta son JSON
(
Content-Type: application/json), como máximo 64 KiB por petición. - Las fechas son ISO 8601 en UTC. Los IDs son UUIDs; las bases de datos se identifican por nombre.
- Cada respuesta incluye
X-Request-Id. Inclúyelo al hablar con soporte.
Errores
{ "error": { "code": "name_taken", "message": "You already have a database with that name.", "request_id": "…" } }Decide según code, no según message. Los errores de validación agregan
details.field.
| Estado | Códigos |
|---|---|
| 400 | bad_request, reserved_name |
| 401 | unauthorized, token_expired, token_revoked |
| 403 | insufficient_scope, token_inactive, org_suspended, org_export_only, ip_not_allowed, forbidden, plan_limit, aal2_required |
| 404 | not_found, database_not_found |
| 409 | conflict, name_taken, name_purging, database_unavailable, backup_in_progress, backup_not_ready, export_in_progress, no_backup, no_backup_before, key_inactive, already_rotated, already_member, already_invited, invite_closed, last_owner, idempotency_in_progress |
| 410 | export_expired |
| 413 | payload_too_large |
| 415 | unsupported_media_type |
| 422 | lifetime_policy, idempotency_key_reused |
| 429 | rate_limited |
| 500 | internal |
| 501 | not_implemented |
| 503 | control_plane_unavailable |
Qué significa cada uno: Errores.
Límites de uso
300 peticiones por minuto por token, informadas en X-RateLimit-Limit y
X-RateLimit-Remaining. Algunas escrituras también tienen presupuestos por
organización: 20 eliminaciones de bases de datos, 30 backups, 20
restauraciones y clones en conjunto y 30 invitaciones por hora, y 20
exportaciones cada 24 horas. Superado un límite: 429 rate_limited con
Retry-After en segundos.
Paginación
Las listas devuelven primero los elementos más nuevos:
{ "data": [ … ], "next_cursor": "WyIyMDI2LTExLTAxVDEyOjAwOjAwWiIsIjk…" }Pasa ?limit= (1–100, 50 por defecto) y ?cursor=<next_cursor>. La última
página tiene next_cursor: null.
Idempotencia
Todo POST acepta Idempotency-Key (de 1 a 255 caracteres ASCII imprimibles):
- durante 24 horas, un reintento con la misma key y el mismo cuerpo devuelve
la primera respuesta con
Idempotent-Replayed: true(incluida una respuesta que traía una API key nueva), y nada se ejecuta dos veces; - la misma key con una petición distinta:
422 idempotency_key_reused; - un reintento mientras la primera todavía se ejecuta:
409 idempotency_in_progress.
Los SDKs, la CLI y el proveedor de Terraform envían una en cada creación y la reutilizan en sus reintentos.
Organización
GET /organization · read
{ "id": "5b0c…", "slug": "acme", "name": "Acme", "plan": "pro", "spend_cap": true, "require_mfa": false, "status": "active", "storage_status": "ready", "created_at": "2026-11-01T12:00:00Z", "limits": { "databases": 20, "api_keys": 50, "members": null }}status es active, paused o suspended. limits son los del plan, o los
de tu acuerdo Enterprise mientras esté vigente; null significa sin límite.
Bases de datos
| Operación | Scope | |
|---|---|---|
GET /databases | read | Lista las bases de datos (paginado) |
POST /databases {"name"} | write | Crea una. 201. Cuenta contra el límite del plan (403 plan_limit); 409 name_taken / name_purging; 400 reserved_name |
GET /databases/{database} | read | Obtiene una por nombre |
DELETE /databases/{database} | write | La elimina. 204. Los datos se borran en segundo plano; las keys con alcance solo sobre ella se revocan |
Una Database:
{ "id": "0d2e…", "name": "movies", "status": "ready", "read_only": false, "created_at": "2026-11-01T12:00:00Z", "restored_from_backup": null, "endpoints": { "http": "https://db.namidb.com/v1/movies/cypher", "bolt": "neo4j+s://db.namidb.com:7687" }}status: ready, restoring o failed. read_only: por encima del límite de
bases de datos del plan después de bajar de plan.
curl -X POST https://app.namidb.com/api/v1/databases \ -H "Authorization: Bearer $NAMIDB_MANAGEMENT_TOKEN" \ -H "Content-Type: application/json" -H "Idempotency-Key: create-movies" \ -d '{"name": "movies"}'Backups y restauraciones
| Operación | Scope | |
|---|---|---|
GET /databases/{database}/backups | read | Los backups de la base de datos, los más nuevos primero (paginado) |
POST /databases/{database}/backups | write | Hace un backup ahora. 202, status: "requested". Uno a la vez por base de datos (409 backup_in_progress) |
GET /backups/{backup_id} | read | Consulta hasta que esté en succeeded o failed |
POST /restores {"backup_id", "database_name"} | write | Restaura un backup terminado con éxito en una base de datos nueva. 202. 409 backup_not_ready si el backup no se puede restaurar |
POST /restores {"database", "at", "database_name"} | write | Restaura database tal como estaba en at (ISO 8601) en una base de datos nueva. Es lo mismo que un clon point_in_time (abajo) y responde el mismo Clone. 400 cuando backup_id viene junto con database o at, o falta alguno de ellos |
GET /restores/{restore_id} | read | Consulta hasta que esté en succeeded o failed |
Un Backup tiene id, database_id, database_name, kind (manual,
scheduled, clone para un clon de snapshot nuevo, point_in_time para una
copia exacta desde la ventana de puntos de restauración, pre_upgrade para
uno tomado automáticamente antes de una actualización del motor), status
(requested, running, succeeded, failed, deleting, expired),
bytes, error, created_at, started_at, finished_at, expires_at,
source_created_at (cuándo se confirmó el cambio más reciente que contiene;
null en backups antiguos) y as_of (en un backup point_in_time, el
instante que contiene).
Un Restore tiene id, backup_id, database_id y database_name (la
base de datos nueva), status (requested, running, succeeded, failed),
error, created_at, started_at, finished_at.
Clones y restauraciones a un punto en el tiempo
| Operación | Scope | |
|---|---|---|
POST /databases/{database}/clones {"name", "source"?, "at"?} | write | Base de datos nueva a partir de esta. 202 |
GET /clones/{clone_id} | read | Consulta hasta que esté en succeeded o failed |
source:
latest_backup(por defecto): el backup terminado más reciente;fresh_snapshot: hace un backup de la base de datos ahora y luego lo copia;point_in_timeconat(ISO 8601): dentro de la ventana de puntos de restauración del plan (Pro 48 horas, Scale 7 días), la base de datos exactamente como estaba enat, al segundo; antes de la ventana, y en Free, el backup más reciente que no contiene nada confirmado después deat. Un momento dentro de la ventana al que todavía no llegan los puntos de restauración usa un backup. Ver Restauración a un punto en el tiempo.
409 no_backup / no_backup_before cuando no hay nada que copiar;
400 bad_request (details.field: "at") para un momento en el futuro.
Un Clone tiene id, mode, status (snapshotting, restoring,
succeeded, failed), source_database_id, source_database_name,
database_id, database_name (la base de datos nueva), backup_id,
requested_point, recovery_point (los cambios posteriores a ese momento no
se incluyen), recovery_source (restore_point o backup), error,
created_at, finished_at. recovery_point y recovery_source son null
mientras se copia un punto en el tiempo (snapshotting).
curl -X POST https://app.namidb.com/api/v1/restores \ -H "Authorization: Bearer $NAMIDB_MANAGEMENT_TOKEN" -H "Content-Type: application/json" \ -d '{"database": "movies", "at": "2026-11-02T09:30:00Z", "database_name": "movies-before-incident"}'Exportaciones
| Operación | Scope | |
|---|---|---|
POST /databases/{database}/exports | write | Encola una exportación: un snapshot de la base de datos al momento en que empieza. 202. Una por base de datos a la vez (409 export_in_progress), 20 por organización por día |
GET /databases/{database}/exports | read | Las exportaciones de una base de datos, las más nuevas primero |
GET /exports/{export_id} | read | Consulta hasta que esté en succeeded o failed |
GET /exports/{export_id}/files/{file} | read | Descarga nodes.jsonl, relationships.jsonl, import.cypher o manifest.json. 410 export_expired después de 7 días. Queda auditado |
Un Export tiene id, database_id, database_name, status
(requested, running, succeeded, failed, expired), created_at,
finished_at, expires_at, nodes, relationships, bytes, error y,
mientras se puede descargar, files: [{name, bytes, sha256, url}]. Descarga
cada url con el mismo token. manifest.json registra el momento del snapshot
como snapshot.taken_at; ver Exportar.
curl -fL https://app.namidb.com/api/v1/exports/$EXPORT_ID/files/import.cypher \ -H "Authorization: Bearer $NAMIDB_MANAGEMENT_TOKEN" -o import.cypherLas exportaciones y sus descargas respetan la IP allowlist de la organización y
su opción “require SSO” (403 ip_not_allowed, 403 token_inactive).
IP allowlists
| Operación | Scope | |
|---|---|---|
GET /ip-allowlist (?api_key_id=) | read | La lista de la organización, o la lista propia de una key |
POST /ip-allowlist {"cidr", "label"?, "api_key_id"?} | admin | Agrega una dirección o un rango IPv4 o IPv6. 201. Se normaliza; /0 se rechaza; entradas por lista según el plan (403 plan_limit) |
DELETE /ip-allowlist/{rule_id} | admin | Quita una entrada. 204 |
Un IpRule tiene id, cidr, label, api_key_id (null para la lista
de la organización), created_at. Consulta
IP allowlists.
API keys
| Operación | Scope | |
|---|---|---|
GET /api-keys | read | Lista las keys, incluidas las revocadas y vencidas. Los secretos nunca se listan |
POST /api-keys {"name", "role"?, "databases"?, "expires_at"?} | admin | Crea una key. 201; el token de la respuesta es la key completa, que se muestra una sola vez |
GET /api-keys/{key_id} | read | Obtiene una |
POST /api-keys/{key_id}/rotate {"overlap_days"?} | admin | La reemplaza. 201. Mismo nombre, rol, bases de datos y allowlist; la key anterior funciona durante overlap_days (1, 7 o 30; 7 por defecto) |
DELETE /api-keys/{key_id} | admin | La revoca. 204. La API de datos la rechaza en cuestión de segundos |
role:read-write(por defecto) oread-only.databases: nombres de bases de datos; omítelo (o usanull) para todas las bases de datos, incluidas las futuras.expires_at: dentro de 2 años, y dentro de la política de vida útil de keys de la organización (422 lifetime_policy).
Una ApiKey tiene id, name, prefix, last4, role, database_ids,
databases, status (active, rotating, expired, revoked),
created_at, expires_at, last_used_at, revoked_at, rotated_from,
superseded_by. Una key nueva o rotada agrega token; una rotación también
devuelve previous_key: {id, expires_at}.
curl -X POST https://app.namidb.com/api/v1/api-keys \ -H "Authorization: Bearer $NAMIDB_MANAGEMENT_TOKEN" -H "Content-Type: application/json" \ -H "Idempotency-Key: movies-app-key-1" \ -d '{"name": "movies-app", "role": "read-only", "databases": ["movies"], "expires_at": "2027-02-01T00:00:00Z"}'Tokens de gestión
Un token admin puede emitir tokens para otras herramientas, por ejemplo un
token write de corta duración para un job de CI. Cómo crear tokens en la
consola se describe en
API keys y tokens.
| Operación | Scope | |
|---|---|---|
GET /management-tokens | admin | Lista los tokens, incluidos los revocados y vencidos. Los secretos nunca se listan |
POST /management-tokens {"name", "scope"?, "expires_at"?} | admin | Crea un token. 201; el token de la respuesta es el token completo, que se muestra una sola vez. scope es read por defecto |
GET /management-tokens/{token_id} | admin | Obtiene uno |
DELETE /management-tokens/{token_id} | admin | Lo revoca, junto con cada token que creó. 204. Dejan de funcionar de inmediato |
Un token creado a través de la API:
- actúa por la misma persona que el token que lo creó (
created_by), y deja de funcionar cuando esa persona pierde el rol de owner o admin o deja de cumplir el requisito de autenticación en dos pasos o de SSO de la organización; - nunca es más amplio: su scope es como máximo el del token que lo llama
(
403 insufficient_scope); - nunca dura más que él: cuando el token que lo llama vence,
expires_ates obligatorio y no puede ser posterior (422 lifetime_policy); además queda dentro de 2 años y de la política de vida útil de las keys de la organización; - funciona solo mientras funcione el token que lo creó (
minted_by): cuando ese token se revoca, todo lo que creó se revoca también, y cuando vence o queda inactivo, también lo hacen los tokens que creó.
La persona necesita la autenticación en dos pasos en su cuenta
(403 aal2_required), igual que en la consola. Como máximo 25 tokens activos
por organización (403 plan_limit). Un token puede revocarse a sí mismo;
revocar un token ya revocado no cambia nada.
Un ManagementToken tiene id, name, prefix, last4, scope,
status (active, inactive, expired, revoked), created_by,
minted_by (el token que lo creó a través de la API; null si se creó en la
consola), created_at, expires_at, last_used_at, last_used_ip,
revoked_at y current (true para el token que hace la petición). Un token
nuevo agrega token.
curl -X POST https://app.namidb.com/api/v1/management-tokens \ -H "Authorization: Bearer $NAMIDB_MANAGEMENT_TOKEN" -H "Content-Type: application/json" \ -H "Idempotency-Key: ci-token-2026-11-04" \ -d '{"name": "ci-deploy", "scope": "write", "expires_at": "2026-11-05T00:00:00Z"}'Uso
GET /usage · read
El periodo de facturación actual, con los mismos números que la página Usage de la consola:
{ "plan": "pro", "period_start": "2026-11-01T00:00:00Z", "period_end": "2026-12-01T00:00:00Z", "storage": { "bytes_now": 5368709120, "gb_hours": 1200.5, "gb_average": 5.0, "included_gb": 100, "used_fraction": 0.05, "over_quota": false }, "write_requests": { "count": 120000, "included": 1000000, "used_fraction": 0.12, "over_quota": false }, "read_requests": { "count": 2400000, "included": 10000000, "used_fraction": 0.24, "over_quota": false }, "estimated_overage_usd": { "storage": 0, "writes": 0, "reads": 0, "total": 0 }, "enforcement": { "writes_blocked": false, "reads_blocked": false }}Miembros e invitaciones
| Operación | Scope | |
|---|---|---|
GET /members | read | user_id, email, name, role, joined_at |
DELETE /members/{user_id} | admin | Quita a un admin o miembro. 204. A los owners los quita otro owner, en la consola |
GET /invitations | admin | Invitaciones pendientes |
POST /invitations {"email", "role"?} | admin | Invita como member (por defecto), admin, developer, billing o viewer. 201. email_sent: false significa que el email falló: revoca e invita de nuevo |
DELETE /invitations/{invitation_id} | admin | La revoca. 204 |
Los tokens nunca otorgan el rol de owner.
Tickets de soporte
| Operación | Scope | |
|---|---|---|
GET /support/tickets | read | Los tickets de la organización, los más nuevos primero |
POST /support/tickets {"subject", "body", "category"?, "severity"?, "database"?} | write | Abre un ticket. 201 |
GET /support/tickets/{number} | read | El ticket y sus messages |
POST /support/tickets/{number}/messages {"body"} | write | Responde. 201. Reabre un ticket resuelto; uno cerrado responde 409 conflict |
category:database,connectivity,billing,account,security,featureuother(por defecto).severity:low,normal(por defecto),highourgent. Los objetivos de respuesta siguen el plan: consulta Soporte.- Los tickets abiertos con un token se registran a nombre de quien creó el token, que recibe los emails. Agrega adjuntos desde la consola.
Un SupportTicket tiene number, subject, status (open,
waiting_on_customer, resolved, closed), category, severity,
database_name, response_due_at, first_response_at, resolved_at,
created_at, last_message_at; el detalle agrega
messages: [{id, author (customer, support, system), body, created_at}].
Clientes
- SDK de JavaScript y
SDK de Python:
ManagementClient. - CLI:
namidb databases,keys,tokens,backups,restores, … - Proveedor de Terraform: bases de datos (incluidas copias y restauraciones a un punto en el tiempo), API keys, tokens de gestión y entradas de IP allowlists.