Management API
The management API runs a NamiDB Cloud organization from code: create and delete databases, mint and rotate API keys, issue management tokens for other tools, take backups, restore (to a point in time too), clone and export, manage IP allowlists, read usage, manage members and invitations, and open support tickets. Use it from CI pipelines, scripts and infrastructure-as-code.
https://app.namidb.com/api/v1The machine-readable contract is the OpenAPI 3.1 document at
https://app.namidb.com/api/v1/openapi.json.
Load it into Postman, Insomnia or a code generator. Where this page and the
document disagree, the document wins.
Management API or data API?
| Management API | Data API | |
|---|---|---|
| Does | Manages databases, keys, backups, people | Runs Cypher (HTTP, Bolt, MCP) |
| Base URL | https://app.namidb.com/api/v1 | https://db.namidb.com/v1 |
| Credential | Management token nmdb_mgmt_… | API key nmdb_live_… |
| SDK class | ManagementClient | NamiDB |
Authentication
Send a management token as a bearer token:
curl https://app.namidb.com/api/v1/organization \ -H "Authorization: Bearer $NAMIDB_MANAGEMENT_TOKEN"A token belongs to one organization, so no path names the organization. Its scope decides what it may call:
| Scope | Allows |
|---|---|
read | Every GET except invitations and management tokens |
write | read, plus databases, backups, restores, clones, exports and support tickets |
admin | write, plus API keys, IP allowlists, members, invitations and management tokens |
Each operation below lists the scope it needs. A token with too little scope
gets 403 insufficient_scope.
Conventions
- Request and response bodies are JSON (
Content-Type: application/json), at most 64 KiB per request. - Times are ISO 8601 in UTC. IDs are UUIDs; databases are addressed by name.
- Every response carries
X-Request-Id. Quote it to support.
Errors
{ "error": { "code": "name_taken", "message": "You already have a database with that name.", "request_id": "…" } }Branch on code, not message. Validation errors add details.field.
| Status | Codes |
|---|---|
| 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 |
What each one means: Errors.
Rate limits
300 requests per minute per token, reported in X-RateLimit-Limit and
X-RateLimit-Remaining. Some writes also have per-organization budgets:
20 database deletions, 30 backups, 20 restores and clones together and 30
invitations per hour, and 20 exports per 24 hours. Past a limit:
429 rate_limited with Retry-After in seconds.
Pagination
Lists return the newest items first:
{ "data": [ … ], "next_cursor": "WyIyMDI2LTExLTAxVDEyOjAwOjAwWiIsIjk…" }Pass ?limit= (1–100, default 50) and ?cursor=<next_cursor>. The last page
has next_cursor: null.
Idempotency
Every POST accepts Idempotency-Key (1–255 printable ASCII characters):
- for 24 hours, a retry with the same key and body returns the first response
with
Idempotent-Replayed: true(including a response that carried a new API key), and nothing runs twice; - the same key with a different request:
422 idempotency_key_reused; - a retry while the first is still running:
409 idempotency_in_progress.
The SDKs, CLI and Terraform provider send one on every create and reuse it across their retries.
Organization
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 is active, paused or suspended. limits are the plan’s, or
those of your Enterprise agreement while one is in force; null means no
limit.
Databases
| Operation | Scope | |
|---|---|---|
GET /databases | read | List databases (paginated) |
POST /databases {"name"} | write | Create one. 201. Counts against the plan limit (403 plan_limit); 409 name_taken / name_purging; 400 reserved_name |
GET /databases/{database} | read | Get one by name |
DELETE /databases/{database} | write | Delete it. 204. Data is erased in the background; keys scoped only to it are revoked |
A 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 or failed. read_only: over the plan’s
database limit after a downgrade.
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 and restores
| Operation | Scope | |
|---|---|---|
GET /databases/{database}/backups | read | The database’s backups, newest first (paginated) |
POST /databases/{database}/backups | write | Back up now. 202, status: "requested". One at a time per database (409 backup_in_progress) |
GET /backups/{backup_id} | read | Poll until succeeded or failed |
POST /restores {"backup_id", "database_name"} | write | Restore a succeeded backup into a new database. 202. 409 backup_not_ready if the backup isn’t restorable |
POST /restores {"database", "at", "database_name"} | write | Restore database as it was at at (ISO 8601) into a new database. The same as a point_in_time clone (below), and it answers the same Clone. 400 when backup_id comes with database or at, or one of them is missing |
GET /restores/{restore_id} | read | Poll until succeeded or failed |
A Backup has id, database_id, database_name, kind (manual,
scheduled, clone for a fresh-snapshot clone, point_in_time for an exact
copy from the restore-point window, pre_upgrade for one taken
automatically before an engine upgrade), status (requested,
running, succeeded, failed, deleting, expired), bytes, error,
created_at, started_at, finished_at, expires_at,
source_created_at (when the newest change it holds was committed; null for
older backups) and as_of (for a point_in_time backup, the instant it
holds).
A Restore has id, backup_id, database_id and database_name (the
new database), status (requested, running, succeeded, failed),
error, created_at, started_at, finished_at.
Clones and point-in-time restores
| Operation | Scope | |
|---|---|---|
POST /databases/{database}/clones {"name", "source"?, "at"?} | write | New database from this one. 202 |
GET /clones/{clone_id} | read | Poll until succeeded or failed |
source:
latest_backup(default): the newest finished backup;fresh_snapshot: back the database up now, then copy that;point_in_timewithat(ISO 8601): inside the plan’s restore-point window (Pro 48 hours, Scale 7 days) the database exactly as it was atat, to the second; before the window, and on Free, the newest backup that holds nothing committed afterat. A time inside the window that the restore points don’t reach yet falls back to a backup. See Point-in-time restore.
409 no_backup / no_backup_before when there is nothing to copy;
400 bad_request (details.field: "at") for a time in the future.
A Clone has id, mode, status (snapshotting, restoring,
succeeded, failed), source_database_id, source_database_name,
database_id, database_name (the new database), backup_id,
requested_point, recovery_point (changes after this time are not
included), recovery_source (restore_point or backup), error,
created_at, finished_at. recovery_point and recovery_source are
null while a point in time is being copied (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"}'Exports
| Operation | Scope | |
|---|---|---|
POST /databases/{database}/exports | write | Queue an export: a point-in-time snapshot of the database as of when it starts. 202. One per database at a time (409 export_in_progress), 20 per organization per day |
GET /databases/{database}/exports | read | A database’s exports, newest first |
GET /exports/{export_id} | read | Poll until succeeded or failed |
GET /exports/{export_id}/files/{file} | read | Download nodes.jsonl, relationships.jsonl, import.cypher or manifest.json. 410 export_expired after 7 days. Audited |
An Export has id, database_id, database_name, status
(requested, running, succeeded, failed, expired), created_at,
finished_at, expires_at, nodes, relationships, bytes, error, and,
while it can be downloaded, files: [{name, bytes, sha256, url}]. Fetch
each url with the same token. manifest.json records the snapshot time as
snapshot.taken_at; see Export.
curl -fL https://app.namidb.com/api/v1/exports/$EXPORT_ID/files/import.cypher \ -H "Authorization: Bearer $NAMIDB_MANAGEMENT_TOKEN" -o import.cypherExports and their downloads follow the organization’s IP allowlist and its
“require SSO” setting (403 ip_not_allowed, 403 token_inactive).
IP allowlists
| Operation | Scope | |
|---|---|---|
GET /ip-allowlist (?api_key_id=) | read | The organization’s list, or one key’s own list |
POST /ip-allowlist {"cidr", "label"?, "api_key_id"?} | admin | Add an IPv4 or IPv6 address or range. 201. Normalised; /0 refused; entries per list by plan (403 plan_limit) |
DELETE /ip-allowlist/{rule_id} | admin | Remove an entry. 204 |
An IpRule has id, cidr, label, api_key_id (null for the
organization’s list), created_at. See IP allowlists.
API keys
| Operation | Scope | |
|---|---|---|
GET /api-keys | read | List keys, revoked and expired ones included. Secrets are never listed |
POST /api-keys {"name", "role"?, "databases"?, "expires_at"?} | admin | Create a key. 201; the response’s token is the full key, shown once |
GET /api-keys/{key_id} | read | Get one |
POST /api-keys/{key_id}/rotate {"overlap_days"?} | admin | Replace it. 201. Same name, role, databases and allowlist; the old key works for overlap_days (1, 7 or 30; default 7) |
DELETE /api-keys/{key_id} | admin | Revoke it. 204. Refused on the data API within seconds |
role:read-write(default) orread-only.databases: database names; omit (ornull) for every database, including future ones.expires_at: within 2 years, and within the organization’s key lifetime policy (422 lifetime_policy).
An ApiKey has 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. A new or rotated key adds token; a rotation also returns
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"}'Management tokens
An admin token can issue tokens for other tools, for example a short-lived
write token for a CI job. Creating tokens in the console is described in
API keys and tokens.
| Operation | Scope | |
|---|---|---|
GET /management-tokens | admin | List tokens, revoked and expired ones included. Secrets are never listed |
POST /management-tokens {"name", "scope"?, "expires_at"?} | admin | Create a token. 201; the response’s token is the full token, shown once. scope defaults to read |
GET /management-tokens/{token_id} | admin | Get one |
DELETE /management-tokens/{token_id} | admin | Revoke it, and every token it created. 204. They stop working at once |
A token created through the API:
- acts for the same person as the token that created it (
created_by), and stops working when that person loses the owner or admin role or no longer meets the organization’s two-factor or SSO requirement; - is never broader: its scope is at most the calling token’s
(
403 insufficient_scope); - never outlives it: when the calling token expires,
expires_atis required and must not be later (422 lifetime_policy); it also stays within 2 years and the organization’s key lifetime policy; - works only while the token that created it does (
minted_by): when that token is revoked, everything it created is revoked too, and when it expires or becomes inactive, so do the tokens it created.
The person needs two-factor authentication on their account
(403 aal2_required), as in the console. At most 25 active tokens per
organization (403 plan_limit). A token may revoke itself; revoking a
revoked token changes nothing.
A ManagementToken has id, name, prefix, last4, scope, status
(active, inactive, expired, revoked), created_by, minted_by (the
token that created it through the API; null for one created in the console),
created_at, expires_at, last_used_at, last_used_ip, revoked_at, and
current (true for the token making the request). A new token adds 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"}'Usage
GET /usage · read
The current billing period, with the same numbers as the console’s Usage page:
{ "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 }}Members and invitations
| Operation | Scope | |
|---|---|---|
GET /members | read | user_id, email, name, role, joined_at |
DELETE /members/{user_id} | admin | Remove an admin or member. 204. Owners are removed by another owner, in the console |
GET /invitations | admin | Pending invitations |
POST /invitations {"email", "role"?} | admin | Invite as member (default), admin, developer, billing or viewer. 201. email_sent: false means the email failed: revoke and invite again |
DELETE /invitations/{invitation_id} | admin | Revoke it. 204 |
Tokens never grant the owner role.
Support tickets
| Operation | Scope | |
|---|---|---|
GET /support/tickets | read | The organization’s tickets, newest first |
POST /support/tickets {"subject", "body", "category"?, "severity"?, "database"?} | write | Open a ticket. 201 |
GET /support/tickets/{number} | read | The ticket and its messages |
POST /support/tickets/{number}/messages {"body"} | write | Reply. 201. Reopens a resolved ticket; a closed one answers 409 conflict |
category:database,connectivity,billing,account,security,featureorother(default).severity:low,normal(default),highorurgent. Response targets follow the plan: see Support.- Tickets opened with a token are filed for the token’s creator, who receives the emails. Add attachments in the console.
A SupportTicket has 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; the detail adds
messages: [{id, author (customer, support, system), body, created_at}].
Clients
- JavaScript SDK and
Python SDK:
ManagementClient. - CLI:
namidb databases,keys,tokens,backups,restores, … - Terraform provider: databases (copies and point-in-time restores included), API keys, management tokens and IP allowlist entries.