> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dbhost.app/llms.txt
> Use this file to discover all available pages before exploring further.

# API introduction

> Programmatic access to DBHost for creating and managing databases.

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

```
https://dbhost.app/api/v1
```

## Common cURL examples

List databases visible to the authenticated key:

```bash theme={null}
curl -H "Authorization: Bearer dbh_your_api_key_here" \
  https://dbhost.app/api/v1/databases
```

Create a database with a full-account key:

```bash theme={null}
curl -X POST https://dbhost.app/api/v1/databases \
  -H "Authorization: Bearer dbh_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"analytics-v2","displayName":"Analytics V2"}'
```

Trigger a backup:

```bash theme={null}
curl -X POST \
  -H "Authorization: Bearer dbh_your_api_key_here" \
  https://dbhost.app/api/v1/databases/<database-id>/backups
```

## 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:

```json theme={null}
{
  "error": {
    "code": "DATABASE_NOT_FOUND",
    "message": "Database 'foo' does not exist",
    "details": []
  }
}
```

## 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.