Databases
Overview

Database Overview

Learn how to manage PostgreSQL databases with the Cloudheed API.

Endpoints

MethodEndpointDescription
POST/v1/databasesCreate database
GET/v1/databasesList databases
GET/v1/databases/{id}Get database details
PATCH/v1/databases/{id}Rename database
DELETE/v1/databases/{id}Delete database
POST/v1/databases/{id}/startStart database
POST/v1/databases/{id}/stopStop database
POST/v1/databases/{id}/restartRestart database
POST/v1/databases/{id}/resizeUpgrade tier
POST/v1/databases/{id}/reset-passwordReset password

Database Object

{
  "id": "db-abc123",
  "name": "my-database",
  "type": "postgres",
  "region": "fsn1",
  "tier": "micro",
  "version": "17",
  "status": "running",
  "host": "db-abc123.db.cloudheed.cloud",
  "port": 5432,
  "database": "postgres",
  "username": "cloudheed",
  "connection_string": "postgresql://cloudheed:****@db-abc123.db.cloudheed.cloud:5432/postgres?sslmode=require",
  "created_at": "2026-03-17T10:00:00Z",
  "updated_at": "2026-03-17T10:00:00Z"
}

Database Status Values

StatusDescription
pendingDatabase creation requested
provisioningServer and container being set up
runningDatabase is active and accepting connections
stoppedDatabase is stopped (no compute charges)
failedProvisioning or operation failed
deletingDatabase is being deleted

List Databases

curl https://api.cloudheed.com/v1/databases \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "databases": [
    {
      "id": "db-abc123",
      "name": "production-db",
      "region": "fsn1",
      "tier": "small",
      "status": "running"
    },
    {
      "id": "db-xyz789",
      "name": "staging-db",
      "region": "fsn1",
      "tier": "micro",
      "status": "running"
    }
  ]
}

Get Database Details

curl https://api.cloudheed.com/v1/databases/db-abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Rename Database

curl -X PATCH https://api.cloudheed.com/v1/databases/db-abc123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "new-database-name"
  }'

Delete Database

curl -X DELETE https://api.cloudheed.com/v1/databases/db-abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Deleted databases are retained for 7 days and can be restored by contacting support.

Next Steps

AuthenticationCreate Database