# Update a build

**PATCH** `/v1/builds/{buildId}`

⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️

Records progress on a build. Any holder of the workspace token may patch any field — the webhook, the CI run and Composer each report the part of a deploy they can see, and the token is the boundary. Reaching `running` stamps `startedAt` and reaching a terminal state stamps `finishedAt`, both only if unset, so re-reporting the same state does not move the clock. Once a build has finished, its state no longer changes: a later report updates the other fields and leaves the state as the finishing report set it.

`projectId`, `branchId`, `deployedUrl` and `applicationTopologyContentHash` can each be set once and never changed: a reporter that resolves them partway through a deploy sets them here, but a value already recorded cannot be changed and the attempt is a conflict. Sending the value already recorded is accepted and changes nothing. `projectId` and `branchId` must belong to the caller's workspace, and a branch must belong to the build's project, so a branch from another project is refused.

Base URL: `https://api.prisma.io`

Tags: `[Experimental]`

## Authorization

Any ONE of the following options authorizes this operation; every scheme listed within an option is required together.

| Option | Scheme | Type | Sent as | Scopes |
| --- | --- | --- | --- | --- |
| Option 1 | `OAuth2` | `oauth2` | `Authorization: Bearer <access token>` | `offline_access`, `workspace:admin` |
| Option 2 | `Bearer` | `http` | `Authorization: Bearer <token>` (JWT) | — |

### OAuth 2.0 flows

- **OAuth2 · authorizationCode**
  - Authorization URL: `https://auth.prisma.io/authorize`
  - Token URL: `https://auth.prisma.io/token`
  - Refresh URL: `https://auth.prisma.io/token`
  - Scope `offline_access` — Offline access
  - Scope `workspace:admin` — Full access to workspace resources

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `buildId` | `string` | Yes | — |

## Request body

Optional. Media type: `application/json`

### Example request body

```json
{
  "applicationTopologyContentHash": "string",
  "branchId": "string",
  "deployedUrl": "https://example.com",
  "errorMessage": "string",
  "externalLogUrl": "https://example.com",
  "failingStep": "string",
  "phase": "build",
  "projectId": "string",
  "state": "cancelled"
}
```

## Responses

| Status | Description | Media type |
| --- | --- | --- |
| `200` | The updated build. | `application/json` |
| `401` | Missing or invalid authorization token. | `application/json` |
| `404` | Build not found, or the caller's workspace does not own it (indistinguishable). | `application/json` |
| `409` | A field that can only be set once already holds a different value. | `application/json` |
| `413` | Request body exceeds this endpoint's size cap. | `application/json` |
| `429` | Rate limit exceeded. | `application/json` |

### Example response: 200 — The updated build.

```json
{
  "data": {
    "applicationTopologyContentHash": "string",
    "branchId": "string",
    "branchName": "string",
    "commitSha": "string",
    "createdAt": "string",
    "deployedUrl": "string",
    "errorMessage": "string",
    "externalLogUrl": "string",
    "failingStep": "string",
    "finishedAt": "string",
    "gitRepoId": "string",
    "id": "string",
    "phase": "build",
    "projectId": "string",
    "source": "ci",
    "startedAt": "string",
    "state": "cancelled"
  }
}
```

### Example response: 401 — Missing or invalid authorization token.

```json
{
  "error": {
    "code": "string",
    "hint": "string",
    "message": "string"
  }
}
```

### Example response: 404 — Build not found, or the caller's workspace does not own it (indistinguishable).

```json
{
  "error": {
    "code": "string",
    "hint": "string",
    "message": "string"
  }
}
```

### Example response: 409 — A field that can only be set once already holds a different value.

```json
{
  "error": {
    "code": "string",
    "hint": "string",
    "message": "string"
  }
}
```

### Example response: 413 — Request body exceeds this endpoint's size cap.

```json
{
  "error": {
    "code": "string",
    "hint": "string",
    "message": "string"
  }
}
```

### Example response: 429 — Rate limit exceeded.

```json
{
  "error": {
    "code": "string",
    "hint": "string",
    "message": "string"
  }
}
```

## Related pages

- [[Experimental]](./tags/experimental.md)
- [Acquire Alchemy deploy lease](./postv1projectsbyprojectidbranchesbybranchidalchemy-statelease.md)
- [Agents](./tags/agents.md)
- [Alchemy state store version](./getv1projectsbyprojectidbranchesbybranchidalchemy-stateversion.md)
- [Buckets](./tags/buckets.md)
- [Connections](./tags/connections.md)
- [Create a branch](./postv1projectsbyprojectidbranches.md)
- [Create a custom domain](./postv1appsbyappiddomains.md)
- [Create a custom domain](./postv1servicesbyserviceiddomains.md)
- [Create a workspace](./postv1workspaces.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.