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


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