Skip to content

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

The 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 APIData API
DoesManages databases, keys, backups, peopleRuns Cypher (HTTP, Bolt, MCP)
Base URLhttps://app.namidb.com/api/v1https://db.namidb.com/v1
CredentialManagement token nmdb_mgmt_…API key nmdb_live_…
SDK classManagementClientNamiDB

Authentication

Send a management token as a bearer token:

Terminal window
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:

ScopeAllows
readEvery GET except invitations and management tokens
writeread, plus databases, backups, restores, clones, exports and support tickets
adminwrite, 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.

StatusCodes
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

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

OperationScope
GET /databasesreadList databases (paginated)
POST /databases {"name"}writeCreate one. 201. Counts against the plan limit (403 plan_limit); 409 name_taken / name_purging; 400 reserved_name
GET /databases/{database}readGet one by name
DELETE /databases/{database}writeDelete 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.

Terminal window
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

OperationScope
GET /databases/{database}/backupsreadThe database’s backups, newest first (paginated)
POST /databases/{database}/backupswriteBack up now. 202, status: "requested". One at a time per database (409 backup_in_progress)
GET /backups/{backup_id}readPoll until succeeded or failed
POST /restores {"backup_id", "database_name"}writeRestore a succeeded backup into a new database. 202. 409 backup_not_ready if the backup isn’t restorable
POST /restores {"database", "at", "database_name"}writeRestore 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}readPoll 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

OperationScope
POST /databases/{database}/clones {"name", "source"?, "at"?}writeNew database from this one. 202
GET /clones/{clone_id}readPoll until succeeded or failed

source:

  • latest_backup (default): the newest finished backup;
  • fresh_snapshot: back the database up now, then copy that;
  • point_in_time with at (ISO 8601): inside the plan’s restore-point window (Pro 48 hours, Scale 7 days) the database exactly as it was at at, to the second; before the window, and on Free, the newest backup that holds nothing committed after at. 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).

Terminal window
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

OperationScope
POST /databases/{database}/exportswriteQueue 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}/exportsreadA database’s exports, newest first
GET /exports/{export_id}readPoll until succeeded or failed
GET /exports/{export_id}/files/{file}readDownload 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.

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

Exports and their downloads follow the organization’s IP allowlist and its “require SSO” setting (403 ip_not_allowed, 403 token_inactive).

IP allowlists

OperationScope
GET /ip-allowlist (?api_key_id=)readThe organization’s list, or one key’s own list
POST /ip-allowlist {"cidr", "label"?, "api_key_id"?}adminAdd an IPv4 or IPv6 address or range. 201. Normalised; /0 refused; entries per list by plan (403 plan_limit)
DELETE /ip-allowlist/{rule_id}adminRemove 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

OperationScope
GET /api-keysreadList keys, revoked and expired ones included. Secrets are never listed
POST /api-keys {"name", "role"?, "databases"?, "expires_at"?}adminCreate a key. 201; the response’s token is the full key, shown once
GET /api-keys/{key_id}readGet one
POST /api-keys/{key_id}/rotate {"overlap_days"?}adminReplace 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}adminRevoke it. 204. Refused on the data API within seconds
  • role: read-write (default) or read-only.
  • databases: database names; omit (or null) 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}.

Terminal window
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.

OperationScope
GET /management-tokensadminList tokens, revoked and expired ones included. Secrets are never listed
POST /management-tokens {"name", "scope"?, "expires_at"?}adminCreate a token. 201; the response’s token is the full token, shown once. scope defaults to read
GET /management-tokens/{token_id}adminGet one
DELETE /management-tokens/{token_id}adminRevoke 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_at is 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.

Terminal window
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

OperationScope
GET /membersreaduser_id, email, name, role, joined_at
DELETE /members/{user_id}adminRemove an admin or member. 204. Owners are removed by another owner, in the console
GET /invitationsadminPending invitations
POST /invitations {"email", "role"?}adminInvite as member (default), admin, developer, billing or viewer. 201. email_sent: false means the email failed: revoke and invite again
DELETE /invitations/{invitation_id}adminRevoke it. 204

Tokens never grant the owner role.

Support tickets

OperationScope
GET /support/ticketsreadThe organization’s tickets, newest first
POST /support/tickets {"subject", "body", "category"?, "severity"?, "database"?}writeOpen a ticket. 201
GET /support/tickets/{number}readThe ticket and its messages
POST /support/tickets/{number}/messages {"body"}writeReply. 201. Reopens a resolved ticket; a closed one answers 409 conflict
  • category: database, connectivity, billing, account, security, feature or other (default).
  • severity: low, normal (default), high or urgent. 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.