Deployments API

Create, list and inspect deployments with the REST API.

Updated 5 days ago 2 min read v2

On this page

Create a deployment
List deployments
Errors

Deployments are builds of a project. Every endpoint needs an API key with the right scope; responses are JSON.

POST/v2/deployments

Create a deployment#

Starts a new deployment of a project from its connected repository or an uploaded archive.

Requires deployments:write

Parameters

projectstringrequired: ID of the project, for example prj_123.
refstring: Git branch, tag or commit. Defaults to the production branch.
targetenum: production or preview. Defaults to preview.

POST /v2/deployments

curl https://api.acme.example/v2/deployments \
  -H "Authorization: Bearer $ACME_TOKEN" \
  -d project=prj_123 \
  -d target=production

const deployment = await acme.deployments.create({
  project: 'prj_123',
  target: 'production',
});

Response201 Created

{
  "id": "dpl_8f3k2q",
  "project": "prj_123",
  "status": "queued",
  "target": "production",
  "url": "https://my-app-8f3k2q.acme.app",
  "created_at": "2026-10-12T15:04:05Z"
}

GET/v2/deployments

List deployments#

Returns deployments of a project, newest first, 20 per page.

Requires deployments:read

Parameters

projectstringrequired: Project ID.
limitinteger: Between 1 and 100. Default 20.
cursorstring: Value of next_cursor from the previous page.

GET /v2/deployments

curl "https://api.acme.example/v2/deployments?project=prj_123&limit=2" \
  -H "Authorization: Bearer $ACME_TOKEN"

page = acme.deployments.list(project="prj_123", limit=2)
for d in page.data:
    print(d.id, d.status)

Response200 OK

{
  "data": [
    { "id": "dpl_8f3k2q", "status": "ready" },
    { "id": "dpl_7a1m9x", "status": "error" }
  ],
  "next_cursor": "c_19f2"
}

Errors#

Status	Meaning
`400`	A parameter is missing or invalid.
`401`	The API key is missing or revoked.
`403`	The key lacks the scope this endpoint needs.
`429`	Rate limit hit — see Rate limits.

Was this article helpful?

84% found this helpful