Skip to main content
DBHost provides two APIs:
  1. Control plane API (https://dbhost.app/api/v1/) — User-facing REST API authenticated with API keys. Use this from your applications, scripts, and CI/CD pipelines. Paid users can issue either selected-database keys or full-account keys.
  2. VPS agent API (https://agent.dbhost.app/) — Internal API for direct VPS operations. Authenticated with a shared secret. Used by the control plane; not intended for end users.
This reference documents the control plane API.

​
API key scope model

Paid users can create two API key scope types:
  • Selected databases — Recommended least-privilege option. The key only sees and operates on its assigned databases.
  • Full account access — Can create and manage every database in the owning account.
Selected-database keys only list their assigned databases. For database-specific routes, out-of-scope access behaves like a missing resource and returns DATABASE_NOT_FOUND. Full-account-only routes, such as database creation, return KEY_SCOPE_DENIED when used with a selected-database key.

​
Base URL

​
Common cURL examples

List databases visible to the authenticated key:
Create a database with a full-account key:
Trigger a backup:

​
Response format

Most successful responses return JSON. File downloads such as backup exports return the raw attachment body, and some delete routes return 204 No Content. Asynchronous v1 operations return 202 Accepted, preserve a human-readable message, and include an operation object. Read status with GET /api/v1/operations/{id}. Generally available operation types include backup. The service also defines restore, clone, delete, and recover for exact-target limited rollouts; their presence in the schema is not general availability. Statuses are queued, running, succeeded, failed, and canceled. Errors use a standard envelope:

​
Rate limits

The v1 API applies route-aware limits after authentication and uses shared control-plane PostgreSQL buckets so limits remain consistent across serverless instances. A limited response uses 429 RATE_LIMITED and includes Retry-After plus the applicable rate-limit headers. Clients should honor Retry-After, add jitter, and avoid retrying non-idempotent requests without an idempotency key. Requests are authenticated and rate-limited before their bodies are read.

​
Generally available v1 resources

The additive v1 resource contracts are:
  • POST /api/v1/databases/{id}/lifecycle
  • PATCH /api/v1/databases/{id}/environment
  • GET|POST /api/v1/databases/{id}/network/allowlist
  • DELETE /api/v1/databases/{id}/network/allowlist/{entryId}
  • GET|POST /api/v1/databases/{id}/members
  • PATCH|DELETE /api/v1/databases/{id}/members/{membershipId}
  • GET /api/v1/databases/{id}/invitations
  • POST /api/v1/databases/{id}/invitations/{invitationId}/resend
  • DELETE /api/v1/databases/{id}/invitations/{invitationId}
  • GET /api/v1/operations/{id}
  • GET|POST /api/v1/webhooks
  • POST /api/v1/webhooks/{id}/rotate
  • DELETE /api/v1/webhooks/{id}

​
Limited rollout resources

The following contracts exist for operator-approved, exact database targets. They are not part of the normal customer or published CLI workflow. A feature flag alone is insufficient; non-enrolled databases fail closed with FEATURE_NOT_AVAILABLE.
  • DELETE /api/v1/databases/{id}
  • POST /api/v1/databases/{id}/clone
  • GET /api/v1/databases/deleted
  • GET /api/v1/databases/{id}/deletion-backup
  • POST /api/v1/databases/{id}/recover
  • POST /api/v1/databases/{id}/backups/{filename} (restore)
  • POST /api/v1/databases/{id}/backups/restore-upload/init
  • POST /api/v1/databases/{id}/backups/restore-upload/complete
Database creation, collaborator/invitation management, and customer webhooks require a full-account API key. A selected-database key can use database-specific lifecycle, environment, network, and backup routes only for its selected active databases. Exact-target authorization is an additional, independent requirement for every limited rollout resource.