REST API

The public API lives at https://api.databasezy.com/v1. The full OpenAPI 3.1 document is served by this site at /openapi.json and is the source of the generated client in packages/api-client and the zb CLI.

Authentication

Every request carries an org-scoped API key:

shell

curl -sS https://api.databasezy.com/v1/orgs \
  -H "Authorization: Bearer zb_live_..."

Create keys under Settings → API keys or with zb api-keys create. The secret is shown once. A key inherits the intersection of its owner’s role and its scopes, and it sees only its own organization. Keys are hashed with argon2id at rest and can be revoked instantly.

Conventions

• Org scoping. Every path is under /v1/orgs/{org_id}; a resource is always resolved through the caller’s org, never by bare id. Looking up someone else’s resource returns 404, not 403.
• Ids are ULIDs with a type prefix (org_, inst_, proj_, key_).
• Pagination is cursor-based: ?limit=50&cursor=...; responses include next_cursor.
• Idempotency: send Idempotency-Key on POST; replays within 24 h return the original response.
• Rate limits: 600 requests/min per key (burst 100), 60/min unauthenticated, 10/min on auth endpoints and 5/min on credential reveal. 429 responses carry Retry-After.
• Errors are application/problem+json with type, title, status, detail and a request_id you can quote to support.

Resources

Databasezy API v1.0.0. Servers: https://api.databasezy.com , http://localhost:8080 (local dev).

system

system operations

Method	Path	Summary
GET	/healthz	Liveness/readiness probe.

catalogue

catalogue operations

Method	Path	Summary
GET	/v1/engines	List catalogue engines with their availability (`coming_soon` ones cannot be ordered).
GET	/v1/plans	List plans with quotas and allowed placements.
GET	/v1/regions	List regions.
GET	/v1/sizes	List instance sizes.

members

members operations

Method	Path	Summary
POST	/v1/invites/{token}/accept	Accept an invite with the token from the email. The signed-in user joins the org
GET	/v1/orgs/{org_id}/invites	Pending invites.
POST	/v1/orgs/{org_id}/invites	Invite someone by email. Counts pending invites against the seat quota.
DELETE	/v1/orgs/{org_id}/invites/{invite_id}	Revoke a pending invite.
GET	/v1/orgs/{org_id}/members	List members with their role and MFA status, plus the seat summary.
PATCH	/v1/orgs/{org_id}/members/{user_id}	Change a member's org role. The new role may not exceed the caller's; only owners
DELETE	/v1/orgs/{org_id}/members/{user_id}	Remove a member (or leave the org yourself). The last owner cannot be removed; only

account

account operations

Method	Path	Summary
GET	/v1/me	The caller: profile, session assurance (MFA / aal) and organizations with roles.

orgs

orgs operations

Method	Path	Summary
GET	/v1/orgs	List the organizations the caller belongs to (an API key sees only its own org).
POST	/v1/orgs	Create an organization. The caller becomes its `owner`. API keys cannot create orgs.
GET	/v1/orgs/{org_id}	Get one organization.
POST	/v1/orgs/{org_id}/actions/close	Close the organization (owner, MFA session): every live instance is deleted with

alerts

alerts operations

Method	Path	Summary
GET	/v1/orgs/{org_id}/alerts	Recent alerts for the org: quota thresholds, backup and instance failures, security
POST	/v1/orgs/{org_id}/alerts/{alert_id}/actions/acknowledge	Acknowledge an alert (hides it from `include_acknowledged=false` views).

api-keys

api-keys operations

Method	Path	Summary
GET	/v1/orgs/{org_id}/api-keys	List active API keys (metadata only), service-account keys included and flagged.
POST	/v1/orgs/{org_id}/api-keys	Create an API key. The response contains the secret `key`; it is never shown again.
DELETE	/v1/orgs/{org_id}/api-keys/{key_id}	Revoke an API key immediately.
POST	/v1/orgs/{org_id}/api-keys/{key_id}/actions/unsuspend	Lift a suspension placed by an automatic security response (docs/20 §3). The key

approvals

approvals operations

Method	Path	Summary
GET	/v1/orgs/{org_id}/approvals	Approval requests visible to the caller: org admins see all; team leads see their
GET	/v1/orgs/{org_id}/approvals/{approval_id}	One approval request (requester, team leads and org admins).
POST	/v1/orgs/{org_id}/approvals/{approval_id}/actions/approve	Approve: the stored request goes through the normal create path (validation, team
POST	/v1/orgs/{org_id}/approvals/{approval_id}/actions/deny	Deny with a reason (required).

audit

audit operations

Method	Path	Summary
GET	/v1/orgs/{org_id}/audit	The org's audit log, newest first (credential reveals, member and key changes,
GET	/v1/orgs/{org_id}/audit/export	CSV export of the filtered audit log (up to 50 000 rows; narrow `from`/`to` for
GET	/v1/orgs/{org_id}/audit/siem-deliveries	SIEM deliveries of the org's audit log.
POST	/v1/orgs/{org_id}/audit/siem-deliveries	Stream the org's audit log to a webhook or S3 bucket.
DELETE	/v1/orgs/{org_id}/audit/siem-deliveries/{delivery_id}	Remove a SIEM delivery.
POST	/v1/orgs/{org_id}/audit/siem-deliveries/{delivery_id}/actions/{action}	`enable` or `disable` a SIEM delivery.

backups

backups operations

Method	Path	Summary
GET	/v1/orgs/{org_id}/backups/health	Monthly customer-visible backup health (docs/09 §6): Team and Enterprise only.
GET	/v1/orgs/{org_id}/instances/{instance_id}/backup-settings	Backup settings: plan caps, the customer's overrides and the effective schedule.
PATCH	/v1/orgs/{org_id}/instances/{instance_id}/backup-settings	Update the backup settings within the plan caps (docs/09 §2 knobs). The backup
GET	/v1/orgs/{org_id}/instances/{instance_id}/backups	Backups of an instance, newest first.
POST	/v1/orgs/{org_id}/instances/{instance_id}/backups	Request a manual snapshot. Counted against the plan's manual quota
GET	/v1/orgs/{org_id}/instances/{instance_id}/backups/{backup_id}	One backup.
POST	/v1/orgs/{org_id}/instances/{instance_id}/backups/{backup_id}/actions/restore	Restore a backup. Default `new_instance`: a new instance is created from the
GET	/v1/orgs/{org_id}/instances/{instance_id}/pitr-window	The PITR window for an instance: engine support, plan days and the restorable range.
GET	/v1/orgs/{org_id}/instances/{instance_id}/restores	Restores from or into an instance, newest first.
GET	/v1/orgs/{org_id}/instances/{instance_id}/restores/{restore_id}	One restore from or into the instance, with the live progress of an in-place

instances

instances operations

Method	Path	Summary
GET	/v1/orgs/{org_id}/ca.pem	CA chains of every cell hosting the org's instances (all cells when none is
GET	/v1/orgs/{org_id}/instances	List all instances in the org.
GET	/v1/orgs/{org_id}/instances/{instance_id}	Get an instance.
PATCH	/v1/orgs/{org_id}/instances/{instance_id}	Change size, storage, engine version, placement, maintenance window or name.
DELETE	/v1/orgs/{org_id}/instances/{instance_id}	Delete an instance. Sets `desired_status=deleted`; data is retained for the plan's
POST	/v1/orgs/{org_id}/instances/{instance_id}/actions/erase	Full erasure (owner, docs/11 §9): purge immediately including the last backup,
POST	/v1/orgs/{org_id}/instances/{instance_id}/actions/pause	Pause an instance (scale to zero, storage kept).
POST	/v1/orgs/{org_id}/instances/{instance_id}/actions/resume	Resume a paused instance.
GET	/v1/orgs/{org_id}/instances/{instance_id}/branches	Branches of an instance (instances with `branch_of` = this one).
POST	/v1/orgs/{org_id}/instances/{instance_id}/branches	Create a branch of an instance.
GET	/v1/orgs/{org_id}/instances/{instance_id}/ca.pem	The CA chain of the instance's cell (PEM), for `sslrootcert` / `--tlsCAFile`.
GET	/v1/orgs/{org_id}/instances/{instance_id}/capacity	What the instance can hold: storage use and growth, connections, memory pressure.
GET	/v1/orgs/{org_id}/instances/{instance_id}/changes	Size / storage / version / placement changes of an instance, newest first.
POST	/v1/orgs/{org_id}/instances/{instance_id}/console-sessions	Open a web console session on an instance.
POST	/v1/orgs/{org_id}/instances/{instance_id}/credentials/reveal	Mint a one-time URL that reveals the instance credentials once (GET on the cell
POST	/v1/orgs/{org_id}/instances/{instance_id}/credentials/rotate	Mint a one-time URL that requests a credential rotation (POST on the cell
GET	/v1/orgs/{org_id}/instances/{instance_id}/logs	Engine logs: a single-use URL on the cell operator that streams the engine pod's
GET	/v1/orgs/{org_id}/instances/{instance_id}/metrics	Hourly resource series for one instance from metering.
GET	/v1/orgs/{org_id}/projects/{project_id}/instances	List instances in a project.
POST	/v1/orgs/{org_id}/projects/{project_id}/instances	Create an instance. Validates engine, version, size, region and placement against the

compliance

compliance operations

Method	Path	Summary
GET	/v1/orgs/{org_id}/compliance	Compliance status: BAA, MFA policy, secure placement availability.
POST	/v1/orgs/{org_id}/compliance/baa/sign	Sign the BAA (owner, MFA session). Requires a plan that offers secure placement

usage

usage operations

Method	Path	Summary
GET	/v1/orgs/{org_id}/cost-report	Monthly cost report per team and cost centre (CSV or JSON).
GET	/v1/orgs/{org_id}/usage	Usage grouped by team, cost centre, instance or metric (list-price costs).

growth

growth operations

Method	Path	Summary
GET	/v1/orgs/{org_id}/credits	Credits granted to the org (referrals, promo codes, programmes).
GET	/v1/orgs/{org_id}/programmes/applications	The org's programme applications and their review status.
POST	/v1/orgs/{org_id}/programmes/applications	Apply for the startup or open-source credits programme (reviewed by staff).
GET	/v1/orgs/{org_id}/referrals	The org's referral code and credits earned.
POST	/v1/orgs/{org_id}/referrals	Create (or return) the org's referral code.

enterprise

enterprise operations

Method	Path	Summary
GET	/v1/orgs/{org_id}/enterprise	The enterprise account this org is the parent of.
POST	/v1/orgs/{org_id}/enterprise	Turn this org into an enterprise parent (owner, Enterprise plan).
PATCH	/v1/orgs/{org_id}/enterprise	Contract terms, consolidated invoicing and global policies (owner of the parent).
GET	/v1/orgs/{org_id}/enterprise/sso	SAML SSO / SCIM status (placeholder until ZB-166).
PUT	/v1/orgs/{org_id}/enterprise/sso	Record the SAML IdP metadata (status `pending_verification`; the SAML bridge of
GET	/v1/orgs/{org_id}/enterprise/subsidiaries	Subsidiary orgs.
POST	/v1/orgs/{org_id}/enterprise/subsidiaries	Attach an org the caller also owns as a subsidiary.
DELETE	/v1/orgs/{org_id}/enterprise/subsidiaries/{subsidiary_id}	Detach a subsidiary (it keeps its own plan and invoices from the next period).

events

events operations

Method	Path	Summary
GET	/v1/orgs/{org_id}/events	Stream every customer event of the org.
GET	/v1/orgs/{org_id}/instances/{instance_id}/events	Stream the events of one instance.

network

network operations

Method	Path	Summary
GET	/v1/orgs/{org_id}/instances/{instance_id}/domains	Custom domains of an instance.
POST	/v1/orgs/{org_id}/instances/{instance_id}/domains	Add a custom domain. The response carries the CNAME to create; the domain is
DELETE	/v1/orgs/{org_id}/instances/{instance_id}/domains/{domain_id}	Remove the custom domain (the cell drops its route and certificate).
POST	/v1/orgs/{org_id}/instances/{instance_id}/domains/{domain_id}/actions/verify	Re-check the CNAME of a pending (or failed) domain.
GET	/v1/orgs/{org_id}/instances/{instance_id}/network	Allow-list, mTLS and custom domain of an instance.
PUT	/v1/orgs/{org_id}/instances/{instance_id}/network	Replace the allow-list and/or the client CA bundle (mTLS). Requires an MFA session.

migrations

migrations operations

Method	Path	Summary
GET	/v1/orgs/{org_id}/instances/{instance_id}/migrations	Migration history for an instance, newest first.
POST	/v1/orgs/{org_id}/instances/{instance_id}/migrations	Start a migration into an instance. `upload` sources get a pre-signed PUT URL;
GET	/v1/orgs/{org_id}/instances/{instance_id}/migrations/{migration_id}	Status, progress, preflight report and verification of one migration.
POST	/v1/orgs/{org_id}/instances/{instance_id}/migrations/{migration_id}/actions/cancel	Cancel a migration that has not finished. The cell stops the job and deletes the
POST	/v1/orgs/{org_id}/instances/{instance_id}/migrations/{migration_id}/actions/cutover	Stop continuous sync and reset sequences (`copy_and_sync` migrations that are
GET	/v1/orgs/{org_id}/migrations	Every migration in the org (all target instances), newest first. Team-scoped

billing

billing operations

Method	Path	Summary
GET	/v1/orgs/{org_id}/invoices	Finalised invoices (from billing) with hosted and PDF links.
PUT	/v1/orgs/{org_id}/spending-cap	Set the org's monthly spending cap. New instances and resizes that would take the

roles

roles operations

Method	Path	Summary
GET	/v1/orgs/{org_id}/me/permissions	The caller's effective org and team permissions (org role + custom roles + team
GET	/v1/orgs/{org_id}/permissions	The permission catalogue, grouped by area with human labels.
GET	/v1/orgs/{org_id}/predefined-roles	Predefined roles with their default and effective (org-edited) permission sets.
PATCH	/v1/orgs/{org_id}/predefined-roles/{role}	Replace a predefined role's permission set for this org (Team and Enterprise). Every
POST	/v1/orgs/{org_id}/predefined-roles/{role}/actions/reset	Reset a predefined role to the default permission set.
GET	/v1/orgs/{org_id}/project-roles	Project role assignments in the org. Callers without org-wide `projects:read` see
GET	/v1/orgs/{org_id}/projects/{project_id}/members	Members with a role on this project.
PUT	/v1/orgs/{org_id}/projects/{project_id}/members/{user_id}	Give a member a role on one project (Team and Enterprise): `admin`, `developer` or
DELETE	/v1/orgs/{org_id}/projects/{project_id}/members/{user_id}	Remove a member's role on a project. Allowed on every plan so a downgraded org can
GET	/v1/orgs/{org_id}/roles	List custom roles.
POST	/v1/orgs/{org_id}/roles	Create a custom role. Its permissions must be a subset of the creator's.
DELETE	/v1/orgs/{org_id}/roles/{role_id}	Delete a custom role and its assignments.
GET	/v1/orgs/{org_id}/roles/{role_id}/assignments	Assignments of a custom role.
POST	/v1/orgs/{org_id}/roles/{role_id}/assignments	Assign a custom role to an org member at org scope, or at one team's scope (team
DELETE	/v1/orgs/{org_id}/roles/{role_id}/assignments/{assignment_id}	Remove an assignment.

observability

observability operations

Method	Path	Summary
GET	/v1/orgs/{org_id}/metrics	Prometheus exposition for the org's instances (API key with `usage:read`).

projects

projects operations

Method	Path	Summary
GET	/v1/orgs/{org_id}/projects	List projects.
POST	/v1/orgs/{org_id}/projects	Create a project.
GET	/v1/orgs/{org_id}/projects/{project_id}	Get a project.
PATCH	/v1/orgs/{org_id}/projects/{project_id}	Rename a project or change its slug.
DELETE	/v1/orgs/{org_id}/projects/{project_id}	Delete an empty project.

service-accounts

service-accounts operations

Method	Path	Summary
GET	/v1/orgs/{org_id}/service-accounts	List service accounts (disabled ones included, with `disabled_at`).
POST	/v1/orgs/{org_id}/service-accounts	Create a service account and its first key (the secret is returned once).
GET	/v1/orgs/{org_id}/service-accounts/{service_account_id}	Get one service account.
POST	/v1/orgs/{org_id}/service-accounts/{service_account_id}/actions/disable	Disable a service account: every key is revoked immediately.
POST	/v1/orgs/{org_id}/service-accounts/{service_account_id}/keys	Mint an additional key for the account (rotation). Inherits the account's role.

sso

sso operations

Method	Path	Summary
GET	/v1/orgs/{org_id}/sso/connections	SSO connections of the org.
POST	/v1/orgs/{org_id}/sso/connections	Add an OIDC or SAML connection. OIDC connections are active at once (rendered into
GET	/v1/orgs/{org_id}/sso/connections/{connection_id}	One connection.
PATCH	/v1/orgs/{org_id}/sso/connections/{connection_id}	Rename, enable/disable, rotate OIDC settings or change the default role.
DELETE	/v1/orgs/{org_id}/sso/connections/{connection_id}	Remove a connection (and its SAML bridge registration). Domains enforcing it fall
GET	/v1/orgs/{org_id}/sso/domains	Claimed and verified email domains.
POST	/v1/orgs/{org_id}/sso/domains	Claim a domain; the answer names the TXT record that proves ownership.
PATCH	/v1/orgs/{org_id}/sso/domains/{domain_id}	Turn SSO enforcement on or off (verified domains with an active connection only).
DELETE	/v1/orgs/{org_id}/sso/domains/{domain_id}	Release a domain (ends enforcement for it).
POST	/v1/orgs/{org_id}/sso/domains/{domain_id}/actions/verify	Look up the TXT record and mark the domain verified. A domain is verified by at
GET	/v1/orgs/{org_id}/sso/scim-groups	Groups pushed by the IdP and what they map to.
PATCH	/v1/orgs/{org_id}/sso/scim-groups/{group_id}	Set the team role and / or org role a group grants; members are updated at once.
GET	/v1/orgs/{org_id}/sso/scim-tokens	Active SCIM tokens (never the secret).
POST	/v1/orgs/{org_id}/sso/scim-tokens	Issue a SCIM bearer token for the IdP (shown once; stored as SHA-256).
DELETE	/v1/orgs/{org_id}/sso/scim-tokens/{token_id}	Revoke a SCIM token.
GET	/v1/sso/discover	Which SSO provider (if any) an email should sign in with. Unauthenticated,

support

support operations

Method	Path	Summary
GET	/v1/orgs/{org_id}/support-grants	List grants (active and past). Auditors may read.
POST	/v1/orgs/{org_id}/support-grants	Issue a support grant.
DELETE	/v1/orgs/{org_id}/support-grants/{grant_id}	Revoke a grant immediately.

teams

teams operations

Method	Path	Summary
GET	/v1/orgs/{org_id}/teams	List teams. The default "Everyone" team is created on first use.
POST	/v1/orgs/{org_id}/teams	Create a team (org admin). Plan limits: Free/Solo 1, Team and Enterprise unlimited.
GET	/v1/orgs/{org_id}/teams/{team_id}	Get a team.
PATCH	/v1/orgs/{org_id}/teams/{team_id}	Update a team. Org admins change everything; a team lead may rename the team and set
DELETE	/v1/orgs/{org_id}/teams/{team_id}	Delete an empty team (org admin). The default team cannot be deleted; move projects
GET	/v1/orgs/{org_id}/teams/{team_id}/budget	Month-to-date spend against the team budget, plus live instance / storage counts.
GET	/v1/orgs/{org_id}/teams/{team_id}/members	Team members and their team roles.
PUT	/v1/orgs/{org_id}/teams/{team_id}/members/{user_id}	Add an org member to the team or change their team role. Org admins, or the team's
DELETE	/v1/orgs/{org_id}/teams/{team_id}/members/{user_id}	Remove a user from the team.

webhooks

webhooks operations

Method	Path	Summary
GET	/v1/orgs/{org_id}/webhooks	List webhook endpoints.
POST	/v1/orgs/{org_id}/webhooks	Register a webhook endpoint. The signing `secret` is returned exactly once.
GET	/v1/orgs/{org_id}/webhooks/{webhook_id}	Get one webhook endpoint.
PATCH	/v1/orgs/{org_id}/webhooks/{webhook_id}	Update URL, description, filters or enabled state.
DELETE	/v1/orgs/{org_id}/webhooks/{webhook_id}	Delete a webhook endpoint. Pending deliveries are dropped.
POST	/v1/orgs/{org_id}/webhooks/{webhook_id}/actions/rotate-secret	Rotate the signing secret. The new secret is returned once; deliveries after this
GET	/v1/orgs/{org_id}/webhooks/{webhook_id}/deliveries	Delivery log for one endpoint, newest first.

Calling any route from the CLI

Migrations (see How migrations work), backups and restore, network allow-lists and mTLS, credential rotation, members and teams, usage, audit, support grants and webhooks are all in the table above. zb api <METHOD> <path> calls any of them with your saved credentials and replaces {org} in the path with your current organization.