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

# Managed database creation

> Reserve an exact database identity before provisioning managed roles.

<Note>
  Managed databases are in preview and require account activation. Use an API
  key with full account scope. The server chooses role names, connection budgets
  and the database endpoint.
</Note>

Send a stable `Idempotency-Key` header with `name` and `displayName`. Ordinary
creation returns `202` while pending and `201` when completed. Responses contain
operation metadata, never passwords. Retrieve credentials separately.

## Reserve before creating

To obtain a stable target identity without dispatching database SQL or admitting
connections, add `reserveOnly: true`:

```json theme={null}
{
  "name": "example-staging",
  "displayName": "Example staging",
  "reserveOnly": true
}
```

The `202` response contains `operationId`, `generation`, `status: "reserved"` and
`targetDatabaseId`. The target database does not yet exist. Its reservation
counts against the account's database quota, including pending reservations and
any lower pending-plan limit. An unlimited admin plan retains its existing
quota semantics.

Repeat without `reserveOnly`, or with `reserveOnly: false`, using the same names
and idempotency key to create and admit that exact identity. A completed replay
returns completed metadata without changing the database. If SQL was already
dispatched with an unresolved outcome, a reservation request returns `409` and
does not reset or restart the operation.

Do not send credentials, generated role names, budgets or endpoint settings.
Unknown request fields and non-boolean `reserveOnly` values are rejected. All
responses use `Cache-Control: no-store`.

## Reserve a clone target

`POST /api/v1/databases/{id}/managed-clones` accepts the same `reserveOnly`
boolean alongside `backupId`, `name` and `displayName`. The source database,
verified backup and future target identity are reserved together. A reserved
response contains no credentials and dispatches no SQL or import. Continue
using the same source, backup, target and idempotency key with `reserveOnly`
false or omitted. Claimed or unknown SQL/import outcomes require reconciliation
and cannot be converted back into reservations.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.