Deploys

Deployment endpoints live under /deployments on the v1 API. A deployment is one attempt to build and run a project at a specific commit or container image.

The deployment resource#

List deployments#

GET /deployments returns deployments across your organization, newest first. Requires a valid credential; no additional scope.

curl "https://platform.nupaas.com/api/v1/deployments?project_id=prj_REPLACE&limit=25" \
  -H "Authorization: Bearer plat_REPLACE_WITH_YOUR_KEY"

{
  "data": [
    {
      "id": "dep_REPLACE",
      "project_id": "prj_REPLACE",
      "status": "active",
      "commit_sha": "9f21c0a4b8e15d3f7c62a09e4d1b8577fa30cc12",
      "branch": "main",
      "triggered_by": "api",
      "created_at": "2026-02-03T11:07:44Z"
    }
  ],
  "pagination": { "next_cursor": null, "has_more": false }
}

Note the filter is project_id with an underscore, not projectId, and that it is optional — so a request that names it wrongly is not obviously broken, it just returns every project's deployments. Assert that the results are narrowed rather than assuming the filter applied.

Create a deployment#

POST /deployments. Requires the write scope. There are two shapes: build from a branch, or run an existing image.

curl -X POST https://platform.nupaas.com/api/v1/deployments \
  -H "Authorization: Bearer plat_REPLACE_WITH_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"prj_REPLACE","branch":"main"}'

curl -X POST https://platform.nupaas.com/api/v1/deployments \
  -H "Authorization: Bearer plat_REPLACE_WITH_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"prj_REPLACE","image_ref":"nginx:alpine","port":8080}'

The response returns the new deployment under data. The call is asynchronous: a success response means the deployment was accepted, not that it is running. Use polling to wait for the outcome.

Get a deployment#

GET /deployments/{id}. Requires a valid credential; no additional scope. This is the endpoint you poll.

curl https://platform.nupaas.com/api/v1/deployments/dep_REPLACE \
  -H "Authorization: Bearer plat_REPLACE_WITH_YOUR_KEY"

An identifier outside your organization returns 404.

Roll back#

POST /deployments/{id}/rollback. Requires the write scope. The identifier in the path is the deployment you are rolling back from.

curl -X POST https://platform.nupaas.com/api/v1/deployments/dep_REPLACE/rollback \
  -H "Authorization: Bearer plat_REPLACE_WITH_YOUR_KEY"

There is no request body. The response is a deployment resource, and it is a new deployment with a new identifier — a rollback is deployed like any other change rather than mutating history. Poll the returned identifier to know when the rollback has landed.

Build logs#

GET /deployments/{id}/logs. Requires a valid credential; no additional scope.

curl https://platform.nupaas.com/api/v1/deployments/dep_REPLACE/logs \
  -H "Authorization: Bearer plat_REPLACE_WITH_YOUR_KEY"

{
  "data": [
    { "timestamp": "2026-02-03T11:07:46Z", "line": "Resolving build strategy" },
    { "timestamp": "2026-02-03T11:07:52Z", "line": "Building image" }
  ]
}

Polling to completion#

Creating a deployment is asynchronous. To find out whether it worked, poll GET /deployments/{id} until status reaches a terminal value.

Treat any status not on this list as still in progress and keep polling. Three seconds between polls, with an overall timeout, matches what the CLI does and stays well inside the rate limit. Only active is success: treat the other four as failures in a deployment pipeline, or a rollback will look like a green build.