Skip to main content

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"
}
FieldValues
statusqueued, building, deploying, ready, failed
kinddockerfile, node, nextjs, python, vite-static, static
typeweb, 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>
QueryDescription
createtrue creates the project if it doesn't exist
promotefalse builds a preview only. Default true.
purposeOne 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
QueryDescription
typebuild, runtime or all (default)
tailLines, 1–5000. Default 200.
deploymentDefault: 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}
Was this page helpful?