Database API
Create managed Postgres databases, connect your apps, branch per environment and run SQL, from your own code, CI or AI agents.
The Database API gives you the same control as the Database part of the dashboard: create a project's Postgres database, get its connection string, give each environment its own branch, change compute, buy credits, and run SQL.
https://api.helipod.io/api/databasesAuthenticate with a Helipod API key that has Database API enabled:
curl https://api.helipod.io/api/databases \
-H "Authorization: Bearer hel_your_key"How it is organised
project
└── database (one per project, serverless Postgres)
└── branch per environment (production is the primary, staging, ...)- Each project can have one database. It starts on the free plan.
- Each environment of the project can have its own branch: a full copy of the data at the moment it was created, with its own connection string. Production uses the primary branch.
- Compute scales up when there is load and down to zero when idle, so an idle database costs nothing.
Things to know
The connection string is a secret
It contains the password. Store it as a secret variable on your service, never in code.
SQL is read-only by default
Statements that change data or schema need allowWrite: true.
Paid plans are prepaid credits
Buy compute hours from your wallet. They don't expire. When they run out, the database is suspended until you top up.
Dry runs and idempotency
Upgrades and compute changes accept ?dryRun=true; creating a database and upgrading accept Idempotency-Key.
Endpoints
| Method and path | |
|---|---|
| Plans | GET /plans |
| Databases | GET POST /, GET DELETE /{databaseId} |
| Connection | GET /{databaseId}/connection |
| Branches | GET POST /{databaseId}/branches, DELETE /{databaseId}/branches/{environmentId} |
| Compute and plan | GET PATCH /{databaseId}/settings, POST /{databaseId}/upgrade, POST /{databaseId}/suspend, POST /{databaseId}/resume, GET /{databaseId}/usage, GET /{databaseId}/balance, GET /{databaseId}/stats |
| SQL | GET /{databaseId}/tables, GET /{databaseId}/tables/{table}/columns, GET /{databaseId}/tables/{table}/rows, POST /{databaseId}/query, POST /{databaseId}/query/classify |
Access
- A key with project reach sees that project's database. A whole-account key sees the databases of every project you own.
- A database the key cannot reach answers
404 DATABASE_NOT_FOUND, the same as one that doesn't exist. - The AI agent tools for these endpoints are in the MCP server (
list_databases,get_database_connection,query_database, ...).