Projects
A project is one app’s backend. Each has a production environment with its own database, served at https://<slug>.flatstack.app.
Creating a project
POST /v1/projects with { "name", "slug"?, "region"?, "engine"? }.
slugis the subdomain. Leave it out and one is made from the name. Use lowercase letters, numbers and single hyphens, 3 to 40 characters. Some names, such asapiandwww, are reserved.regioniseu(the default) orus. It sets where the database lives, and you can’t change it later.engineisd1(the default) or, on Pro and Studio,postgres. See Postgres.
Your plan sets how many projects you can have; extra projects add more. Over the limit, creating returns 403 plan_limit_reached.
The response’s status is ready once the database (for Postgres, a Neon project and its connection through Hyperdrive), the app’s Worker and the subdomain are set up. If setting up stopped partway, status is failed; call POST /v1/projects/{id}/provision to finish. It picks up where it stopped and never creates anything twice. Until your first deploy, the subdomain answers 503 not_deployed.
Managing projects
| Request | Who | What it does |
|---|---|---|
GET /v1/projects |
Everyone | Lists projects. Add ?deleted=true for deleted ones you can still restore. |
GET /v1/projects/{id} |
Everyone | One project. |
PATCH /v1/projects/{id} |
Owners, admins | { "name" }. The subdomain stays the same. |
DELETE /v1/projects/{id} |
Owners | Needs { "confirm": true }. The app stops being served at once. |
POST /v1/projects/{id}/restore |
Owners | Brings a deleted project back within 7 days. After that it’s permanently deleted. |
Moving a project to another account
Both accounts’ owners confirm.
| Request | Who | What it does |
|---|---|---|
POST /v1/projects/{id}/transfers |
Sending owner | { "toAccountId" }. The other account has 7 days to accept. |
GET /v1/project-transfers |
Everyone | Pending transfers in and out of your account. |
POST /v1/project-transfers/{id}/accept |
Receiving owner | Moves the project. Your account needs a free project slot. |
POST /v1/project-transfers/{id}/cancel |
Either owner | Cancels a pending transfer. |
The project’s data, environment variables, secrets and domains move with it. Its deploy tokens and the sending account’s webhooks for it are removed, so create new ones after the move. Usage, invoices and audit history stay with the sending account. If the sending account has always-on Postgres for the project, it must remove that add-on first.
As Markdown: api/projects.md