Skip to main content
POST
/
api
/
v1
/
databases
Create database
curl --request POST \
  --url https://api.example.com/api/v1/databases
Creates a new PostgreSQL database with its own user, password, and PgBouncer pool entry.
Database names must match ^[a-z][a-z0-9-]{1,48}[a-z0-9]$ — lowercase letters, numbers, and hyphens, 3-50 characters.

​
Request body

FieldTypeRequiredDescription
namestringYesDatabase identifier (becomes DB name and username)
displayNamestringYesHuman-friendly label
{
  "name": "my-app",
  "displayName": "My Application"
}

​
Example

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

201 Created
{
  "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

StatusCodeDescription
400VALIDATION_ERRORRequest body is missing fields or the name is invalid
401UNAUTHORIZEDMissing or invalid API key
403KEY_SCOPE_DENIEDThe API key is valid but does not have full account access
403PLAN_LIMITYour plan does not allow API access or more databases
500AGENT_ERRORThe VPS agent failed to create the database