# Deployments API

> Create, list and inspect deployments with the REST API.

Source: https://helpdox.fekbd.com/docs/acme-cloud/api-cli/deployments-api/

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',
});
```

Response

201 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)
```

Response

200 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. |