---
title: "Deploys"
description: "REST endpoints for deploys. Bearer-auth required."
section: "API"
group: "REST"
order: 24
---

## GET /api/deploys

List deploys.

**Query parameters**

- `limit` (optional): Page size (1–100, default 100).
- `after` (optional): Keyset cursor — return the page after this row (next page).
- `before` (optional): Keyset cursor — return the page before this row (prev page).
- `ids` (optional): Comma-separated list of IDs. Narrows results to these IDs within the caller's accessible scope (does not bypass access checks).
- `filter` (optional): Nested filter expression (`<Entity>Filter`): AND/OR/NOT + per-field comparison operators + relation traversal. JSON-encoded on the query string.
- `orderBy` (optional): Multi-key sort (`<Entity>OrderBy[]`): array of `{ field: direction }` applied in order. Directions: asc/desc plus the four explicit nulls variants. JSON-encoded on the query string.
- `workspace_id` (optional): Filter deploys to this workspace.
- `entity_id` (optional): Filter to deploys for a specific entity (app, function, …).
- `build_id` (optional): Filter to deploys produced from a specific build.
- `status` (optional): Filter by deploy status.
- `trigger` (optional): Shorthand: filter where `trigger` equals this value.
- `created_by` (optional): Shorthand: filter where `createdBy` equals this value.

**Response**

```json
{
  "data": [
    {
      "id": "<...>",
      "workspaceId": "<...>",
      "entityId": "<...>",
      "sequenceNumber": "<...>",
      "buildId": "<...>",
      "status": "<...>",
      "trigger": "<...>",
      "sourceEventId": "<...>",
      "productionUrl": "<...>",
      "previewUrl": "<...>",
      "error": "<...>",
      "metadata": "<...>",
      "createdBy": "<...>",
      "startedAt": "<...>",
      "completedAt": "<...>",
      "createdAt": "<...>"
    }
  ],
  "pageInfo": {
    "total": "number",
    "hasNextPage": "boolean",
    "hasPreviousPage": "boolean",
    "startCursor": "string",
    "endCursor": "string"
  }
}
```

## POST /api/deploys

Create deploy

Deploy a build (when `buildId` is set) or the latest successful build of an app's default version (when `appId` is set). Returns the freshly-created deploy row so the caller can poll status via GET /api/deploys/{id}.

**Request body**

```json
{
  "buildId?": "string",
  "appId?": "string"
}
```

**Response**

```json
{
  "id": "string",
  "workspaceId": "string",
  "entityId": "string",
  "sequenceNumber": "integer",
  "buildId": "string",
  "status": "pending | running | completed | failed",
  "trigger": "auto | manual | rollback",
  "sourceEventId": "string",
  "productionUrl": "string",
  "previewUrl": "string",
  "error": "string",
  "metadata": {},
  "createdBy": "string",
  "startedAt": "string",
  "completedAt": "string",
  "createdAt": "string"
}
```

## GET /api/deploys/{id}

Get a deploy by ID, including its step list.

**Path parameters**

- `id` (required): Deploy to retrieve.

**Response**

```json
{
  "id": "string",
  "workspaceId": "string",
  "entityId": "string",
  "sequenceNumber": "integer",
  "buildId": "string",
  "status": "pending | running | completed | failed",
  "trigger": "auto | manual | rollback",
  "sourceEventId": "string",
  "productionUrl": "string",
  "previewUrl": "string",
  "error": "string",
  "metadata": {},
  "createdBy": "string",
  "startedAt": "string",
  "completedAt": "string",
  "createdAt": "string",
  "steps": ["<...>"]
}
```

## POST /api/deploys/{id}/cancel

Cancel deploy

Cancel a pending or running deploy. In-flight CF Pages uploads cannot be aborted but results will be discarded.

**Path parameters**

- `id` (required): The deploy's prefixed ID (e.g. `dep_...`).

**Request body**

```json
{
  "reason?": "string"
}
```

**Response**

```json
{
  "success": "boolean"
}
```