[Experimental]

Update a build

⚠️ 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.

patch/v1/builds/{buildId}

Request

  • Base URL: https://api.prisma.io
  • URL: https://api.prisma.io/v1/builds/{buildId}
  • Auth: one of:
    • OAuth 2 (authorization code, authorization URL https://auth.prisma.io/authorize, token URL https://auth.prisma.io/token, scopes: workspace:admin, offline_access)
    • HTTP bearer

Path parameters

buildIdstring required

Request body

phase'queued' | 'build' | 'deploy'

How far the run has got.

state'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled'
failingStepstring

Name of the step that failed, free text — step names come from build tooling the platform cannot validate.

errorMessagestring
externalLogUrlstring uri
projectIdstring

Project the build targets. Can be set once and never changed: a reporter that learns the project partway through a deploy may set it, but a value already recorded cannot be changed.

branchIdstring

Branch the build targets. Can be set once and never changed, like projectId.

deployedUrlstring uri

Where the deployed app can be reached. Can be set once and never changed, like projectId.

applicationTopologyContentHashstring

Content hash of the application topology this run deploys, as submitted to the application-topology endpoint. A value match, never a reference: equal hashes identify the same graph. Can be set once and never changed, like projectId.

Response

The updated build.

Changes

No recorded changes to this operation across all 1 revision of this API.