Projects
Create, list, rename and delete projects and their environments with a Helipod API key of any product.
A project holds everything you run on Helipod: services, VPS, a database, email, and the environments they live in. These endpoints work with any Helipod API key, whichever products it has. A key made only for the Email API can create the project it will send email from.
| Base URL | https://api.helipod.io/api |
| Projects | GET POST /projects, GET PATCH DELETE /projects/{projectId} |
| Environments | POST /projects/{projectId}/environments, PATCH DELETE /environments/{environmentId} |
The Container API has had the same endpoints under /containers for longer (Projects, Environments). They answer the same, but there the key needs the Container API.
List projects
/projectscurl https://api.helipod.io/api/projects \
-H "Authorization: Bearer hel_your_key"{
"success": true,
"data": [
{
"id": "3b0cd5ac-ac26-4012-9b28-17466f73788c",
"name": "My Shop",
"description": "Online store",
"createdAt": "2026-09-01T08:00:00.000Z",
"environments": [
{ "id": "e1d4a0f2-6c11-4a9e-8a0e-5f2b7d1c9a33", "name": "Production" }
]
}
]
}A key with project access returns only its project. A whole-account key returns every project you own; projects someone else invited you to are not included, because their owner pays for them.
/projects/{projectId}404 if the key can't reach it.Create a project
/projectsIdempotency-KeyProduction environment. Needs a whole-account key.Prop
Type
curl -X POST https://api.helipod.io/api/projects \
-H "Authorization: Bearer hel_your_key" -H "Content-Type: application/json" \
-H "Idempotency-Key: customer-toko-maju" \
-d '{ "name": "Toko Maju", "description": "Customer since November" }'Returns 201 with the project object. Send an Idempotency-Key so a retry after a timeout returns the same project instead of making a second one. A key limited to one project gets 403 KEY_PROJECT_SCOPED. Creating a project costs nothing; what you put in it is billed as usual.
Rename a project
/projects/{projectId}Prop
Type
Send at least one of them (400 NOTHING_TO_UPDATE otherwise). Returns the project object. A project key can rename its own project.
Delete a project
/projects/{projectId}Prop
Type
curl -X DELETE https://api.helipod.io/api/projects/$PROJECT \
-H "Authorization: Bearer hel_your_key" -H "Content-Type: application/json" \
-d '{ "confirm": "Toko Maju" }'{ "success": true, "data": { "id": "3b0cd5ac-ac26-4012-9b28-17466f73788c", "deleted": true, "deletedEnvironments": 1 } }Only empty projects can be deleted
While the project still has services, VPS, databases or an active email plan, the call answers 409 PROJECT_NOT_EMPTY and error lists what is left. Delete those first. A missing or wrong confirm answers 400 CONFIRMATION_REQUIRED, and only the project's owner can delete it (403 FORBIDDEN). This can't be undone.
Environments
An environment (Production, staging, preview, ...) is a separate copy of your setup inside a project: its own services, and its own database branch when the project has a database.
/projects/{projectId}/environments201 with { "id", "name", "projectId" }.Prop
Type
/environments/{environmentId}{ "name": "..." } with the same rules./environments/{environmentId}{ "confirm": "<its exact name>" }; 409 ENVIRONMENT_NOT_EMPTY while it has services.Deleting an environment also deletes its database branch and the resources of its integrations, so it needs a key with the Container API or the Database API (403 SCOPE_NOT_ALLOWED otherwise). Creating and renaming work with any key.
Errors
| Code | Status | Meaning |
|---|---|---|
INVALID_API_KEY | 401 | No key, or a key that does not exist or was revoked. |
KEY_PROJECT_SCOPED | 403 | Creating or deleting a project needs a whole-account key. |
PROJECT_NOT_FOUND | 404 | No such project, or the key can't reach it. |
PROJECT_NOT_EMPTY | 409 | Delete what is left in the project first. |
CONFIRMATION_REQUIRED | 400 | confirm is missing or is not the exact name. |
All other codes are listed on Requests and errors.