PostgreSQL API

Manage managed PostgreSQL databases. See Managed PostgreSQL for the conceptual model.

Endpoints

Method	Path	Description
`POST`	`/db/postgres`	Create an instance
`GET`	`/db/postgres`	List instances
`DELETE`	`/db/postgres/{id}`	Delete an instance
`GET`	`/db/postgres/logs/{id}?max=N`	Fetch database logs

All requests require Authorization: Bearer <token> and project scoping.

The instance object

{
  "id": "…",
  "project_id": "…",
  "name": "my-db",
  "volume_id": "…",
  "postgres_version": "16",
  "postgres_user": "app",
  "postgres_db": "app",
  "status": "running",
  "url": "postgres://app:…@host:5432/app"
}

Field	Type	Description
`name`	string	Friendly instance name
`volume_id`	string	Volume that stores the data
`postgres_version`	string	Postgres major version (e.g. `16`)
`postgres_user`	string	Connection username
`postgres_db`	string	Default database name
`status`	string	Lifecycle status
`url`	string	Connection string

Create an instance

curl -X POST https://api.cumin.dev/db/postgres \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "…",
    "name": "my-db",
    "volume_id": "<volume-id>",
    "postgres_version": "16",
    "postgres_user": "app",
    "postgres_password": "a-strong-password",
    "postgres_db": "app"
  }'

Response:

{ "id": "…" }

You must create a volume first and pass its id as volume_id.

List instances

curl https://api.cumin.dev/db/postgres \
  -H "Authorization: Bearer $TOKEN"

Fetch logs

curl "https://api.cumin.dev/db/postgres/logs/<db-id>?max=100" \
  -H "Authorization: Bearer $TOKEN"

Delete an instance

curl -X DELETE https://api.cumin.dev/db/postgres/<db-id> \
  -H "Authorization: Bearer $TOKEN"

Connecting from an app

Set the instance url as the DATABASE_URL environment variable on your app — see Apps API and Environment variables.

Next steps

Managed PostgreSQL — the conceptual model
Volumes API — the storage behind databases