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

# Create database

> Provision a new PostgreSQL database.

Creates a new PostgreSQL database with its own user, password, and PgBouncer pool entry.

<Tip>
  Database names must match `^[a-z][a-z0-9-]{1,48}[a-z0-9]$` — lowercase letters, numbers, and hyphens, 3-50 characters.
</Tip>

## Request body

| Field         | Type   | Required | Description                                        |
| ------------- | ------ | -------- | -------------------------------------------------- |
| `name`        | string | Yes      | Database identifier (becomes DB name and username) |
| `displayName` | string | Yes      | Human-friendly label                               |

```json theme={null}
{
  "name": "my-app",
  "displayName": "My Application"
}
```

## Example

```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":"my-app","displayName":"My Application"}'
```

## Response

```json 201 Created theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "my-app",
  "displayName": "My Application",
  "host": "db.dbhost.app",
  "port": 6432,
  "database": "my-app",
  "username": "my-app",
  "password": "generated-secret-token",
  "status": "active",
  "connectionString": "postgresql://my-app:generated-secret-token@db.dbhost.app:6432/my-app?sslmode=verify-full"
}
```

## Errors

| Status | Code               | Description                                                |
| ------ | ------------------ | ---------------------------------------------------------- |
| 400    | `VALIDATION_ERROR` | Request body is missing fields or the name is invalid      |
| 401    | `UNAUTHORIZED`     | Missing or invalid API key                                 |
| 403    | `KEY_SCOPE_DENIED` | The API key is valid but does not have full account access |
| 403    | `PLAN_LIMIT`       | Your plan does not allow API access or more databases      |
| 500    | `AGENT_ERROR`      | The VPS agent failed to create the database                |