Projects and deployments
Objects
Project
{
"name": "expenses",
"status": "ready",
"url": "https://expenses.apps.contoso.com",
"productionDeploymentId": "d9a1b7",
"liveDeploymentId": "d9a1b7",
"latestDeployment": { "…": "a Deployment" },
"lifecycle": "active",
"createdAt": "2026-11-02T09:14:00.000Z"
}
Deployment
{
"id": "d9a1b7",
"status": "ready",
"kind": "node",
"type": "web",
"previewUrl": "https://expenses--d9a1b7.apps.contoso.com",
"production": true,
"error": null,
"createdAt": "2026-11-14T16:02:11.000Z"
}
| Field | Values |
|---|---|
status | queued, building, deploying, ready, failed |
kind | dockerfile, node, nextjs, python, vite-static, static |
type | web, api, worker, cron, static |
lifecycle (project) | active, archived, disabled |
List projects
GET /api/projects
Projects you own. With ?scope=all, every project you can view (owned, developer, and through an admin role), with owner and your role.
Auth: any signed-in user.
Response 200: { "projects": [Project] }.
Create a project
POST /api/projects
{ "name": "q3-variance" }
Names are DNS-safe (lowercase letters, digits, dashes; no --). Waits briefly for provisioning.
Auth: builders (everyone by default; IT can limit it to a group).
Response 201 (created) or 200 (already yours): { "project": Project, "created": true }.
Errors: 400 INVALID_NAME, 403 NOT_A_BUILDER, 409 NAME_TAKEN, 409 NAME_BEING_FREED (just deleted, still tearing down), 402 (licence).
Get a project
GET /api/projects/:name
Auth: view.
Response 200: the Project plus deployments (latest 10), perms ({ role, label, canView, canManage, canOwn, … }) and owner ({ id, name, email, department }).
Deploy
POST /api/projects/:name/deployments?create=true&promote=true&purpose=…
Content-Type: application/gzip
<.tar.gz of the source folder>
| Query | Description |
|---|---|
create | true creates the project if it doesn't exist |
promote | false builds a preview only. Default true. |
purpose | One line for approvers when the code uses integrations |
Auth: manage (or any builder, when creating).
Response 202: { "deployment": Deployment }. Follow it with the events stream or GET /api/deployments/:id.
Errors: 413 BUNDLE_TOO_LARGE (over 50 MB), 400 EMPTY_BUNDLE, 400 BAD_BUNDLE (not a gzipped tarball), 409 PROJECT_ARCHIVED, 409 PROJECT_DISABLED, 402 (licence).
tar -czf /tmp/app.tgz -C ./my-app .
curl -X POST -H "Authorization: Bearer dev-token" -H "Content-Type: application/gzip" \
--data-binary @/tmp/app.tgz "http://localhost:4780/api/projects/my-app/deployments?create=true"
List deployments
GET /api/projects/:name/deployments
Auth: view.
Response 200: { "deployments": [Deployment] } (latest 50).
Get a deployment
GET /api/deployments/:id
Response 200: { "project": "expenses", "deployment": Deployment, "live": true }.
Access requests created by a deployment
GET /api/deployments/:id/requests
What a deploy asked for: integrations the code uses that weren't granted yet.
Response 200: { "requests": [Request] } (see Integrations and requests).
Logs
GET /api/projects/:name/logs?type=all&tail=200&deployment=:id
| Query | Description |
|---|---|
type | build, runtime or all (default) |
tail | Lines, 1–5000. Default 200. |
deployment | Default: the live deployment |
Response 200: { "deploymentId": "d9a1b7", "build": "…", "runtime": "…" }.
Errors: 404 NO_DEPLOYMENTS, 404 DEPLOYMENT_NOT_FOUND.
Promote
POST /api/projects/:name/promote
{ "deploymentId": "d8f3a2" }
Makes a ready deployment serve production. Auth: manage. Waits up to a minute for the Edge to switch.
Response 200: the Project plus previousDeploymentId and switched (whether the Edge already serves it).
Errors: 400 MISSING_DEPLOYMENT, 404 DEPLOYMENT_NOT_FOUND, 409 NOT_READY, 409 PROJECT_NOT_ACTIVE.
Roll back
POST /api/projects/:name/rollback
{ "to": "d8f3a2" }
to is optional (default: the previous ready deployment). Instant; no rebuild. Auth: manage.
Response 200: the Project plus previousDeploymentId and switched, as for promote.
Errors: 409 NO_ROLLBACK_TARGET, plus the promote errors.
Live status stream
GET /api/projects/:name/events?deployment=:id
Accept: text/event-stream
Server-sent events. Emits status whenever the project or its latest deployment changes. With ?deployment=, each event is { project, deployment, live } and the stream ends with a done event once the deployment is settled (failed, or ready and live). An unknown deployment sends an error event. Streams close after 15 minutes.
event: status
data: {"project":{…},"deployment":{"id":"d9a1b7","status":"building",…},"live":false}
event: done
data: {"project":{…},"deployment":{"id":"d9a1b7","status":"ready",…},"live":true}