Deploys

REST endpoints for deploys. Bearer-auth required.

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

{
  "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

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

Response

{
  "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

{
  "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

{
  "reason?": "string"
}

Response

{
  "success": "boolean"
}