Saltearse al contenido

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/v1

El 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ónAPI de datos
Qué haceGestiona bases de datos, keys, backups, personasEjecuta Cypher (HTTP, Bolt, MCP)
URL basehttps://app.namidb.com/api/v1https://db.namidb.com/v1
CredencialToken de gestión nmdb_mgmt_…API key nmdb_live_…
Clase del SDKManagementClientNamiDB

Autenticación

Envía un token de gestión como bearer token:

Ventana de terminal
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:

ScopePermite
readTodos los GET excepto invitaciones y tokens de gestión
writeread, más bases de datos, backups, restauraciones, clones, exportaciones y tickets de soporte
adminwrite, 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.

EstadoCódigos
400bad_request, reserved_name
401unauthorized, token_expired, token_revoked
403insufficient_scope, token_inactive, org_suspended, org_export_only, ip_not_allowed, forbidden, plan_limit, aal2_required
404not_found, database_not_found
409conflict, 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
410export_expired
413payload_too_large
415unsupported_media_type
422lifetime_policy, idempotency_key_reused
429rate_limited
500internal
501not_implemented
503control_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ónScope
GET /databasesreadLista las bases de datos (paginado)
POST /databases {"name"}writeCrea una. 201. Cuenta contra el límite del plan (403 plan_limit); 409 name_taken / name_purging; 400 reserved_name
GET /databases/{database}readObtiene una por nombre
DELETE /databases/{database}writeLa 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.

Ventana de terminal
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ónScope
GET /databases/{database}/backupsreadLos backups de la base de datos, los más nuevos primero (paginado)
POST /databases/{database}/backupswriteHace un backup ahora. 202, status: "requested". Uno a la vez por base de datos (409 backup_in_progress)
GET /backups/{backup_id}readConsulta hasta que esté en succeeded o failed
POST /restores {"backup_id", "database_name"}writeRestaura 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"}writeRestaura 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}readConsulta 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ónScope
POST /databases/{database}/clones {"name", "source"?, "at"?}writeBase de datos nueva a partir de esta. 202
GET /clones/{clone_id}readConsulta 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_time con at (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 en at, al segundo; antes de la ventana, y en Free, el backup más reciente que no contiene nada confirmado después de at. 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).

Ventana de terminal
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ónScope
POST /databases/{database}/exportswriteEncola 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}/exportsreadLas exportaciones de una base de datos, las más nuevas primero
GET /exports/{export_id}readConsulta hasta que esté en succeeded o failed
GET /exports/{export_id}/files/{file}readDescarga 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.

Ventana de terminal
curl -fL https://app.namidb.com/api/v1/exports/$EXPORT_ID/files/import.cypher \
-H "Authorization: Bearer $NAMIDB_MANAGEMENT_TOKEN" -o import.cypher

Las 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ónScope
GET /ip-allowlist (?api_key_id=)readLa lista de la organización, o la lista propia de una key
POST /ip-allowlist {"cidr", "label"?, "api_key_id"?}adminAgrega 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}adminQuita 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ónScope
GET /api-keysreadLista las keys, incluidas las revocadas y vencidas. Los secretos nunca se listan
POST /api-keys {"name", "role"?, "databases"?, "expires_at"?}adminCrea una key. 201; el token de la respuesta es la key completa, que se muestra una sola vez
GET /api-keys/{key_id}readObtiene una
POST /api-keys/{key_id}/rotate {"overlap_days"?}adminLa 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}adminLa revoca. 204. La API de datos la rechaza en cuestión de segundos
  • role: read-write (por defecto) o read-only.
  • databases: nombres de bases de datos; omítelo (o usa null) 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}.

Ventana de terminal
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ónScope
GET /management-tokensadminLista los tokens, incluidos los revocados y vencidos. Los secretos nunca se listan
POST /management-tokens {"name", "scope"?, "expires_at"?}adminCrea 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}adminObtiene uno
DELETE /management-tokens/{token_id}adminLo 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_at es 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.

Ventana de terminal
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ónScope
GET /membersreaduser_id, email, name, role, joined_at
DELETE /members/{user_id}adminQuita a un admin o miembro. 204. A los owners los quita otro owner, en la consola
GET /invitationsadminInvitaciones pendientes
POST /invitations {"email", "role"?}adminInvita 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}adminLa revoca. 204

Los tokens nunca otorgan el rol de owner.

Tickets de soporte

OperaciónScope
GET /support/ticketsreadLos tickets de la organización, los más nuevos primero
POST /support/tickets {"subject", "body", "category"?, "severity"?, "database"?}writeAbre un ticket. 201
GET /support/tickets/{number}readEl ticket y sus messages
POST /support/tickets/{number}/messages {"body"}writeResponde. 201. Reabre un ticket resuelto; uno cerrado responde 409 conflict
  • category: database, connectivity, billing, account, security, feature u other (por defecto).
  • severity: low, normal (por defecto), high o urgent. 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