/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Cancel Build

Cancel Build

Stop a queued or running build before it publishes.

POST/v1/projects/{projectId}/builds/{buildId}/cancelTry it
API key or session token

Stop a build that is queued or still running. A cancelled build publishes nothing, and the site keeps serving whatever it served before.

Note

Any workspace member (session JWT), or an API key bound to this project with the build scope or higher. Any plan.

A build can be cancelled while its status is queued, uploading, cloning, parsing or compiling. Once it reaches deploying, the upload to the CDN and the switch to the new version may already be under way, so the request returns 409 build_not_cancellable.

What happens next depends on where the build is:

•
Queued — it never runs.
•
Running — the build stops at its next stage, or before updating search and the AI assistant. It is not marked failed.

Either way the status changes to cancelled immediately, the log gets a Cancelled by <name> line, and the log stream ends with a complete event whose data is cancelled. The workspace audit log records build.cancelled.

Path Parameters

NameDescription
projectId:stringpathRequired
The project ID (e.g., 3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c).
buildId:stringpathRequired
The build to cancel (e.g., bld_xyz789). It must belong to projectId.

Request Body

None.

Response

Returns the updated build object, without logs and triggeredBy:

•
status is cancelled.
•
completedAt is the time of the cancel.
•
error is Cancelled by <name>, using your account name (or email), or Cancelled by API key "<key name>" for an API key.
•
durationMs is set if the build had started.

Error Responses

Statuserror.codeWhen
401unauthorizedNo credential, or an invalid, revoked or expired one
403forbiddenYou are not a member of the project's workspace, or the API key's scope is below build
404not_foundThe project or build does not exist, the build belongs to another project, or the API key belongs to another project
409build_not_cancellableThe build is deploying, deployed, failed or already cancelled. details.status is its current status

409 Conflict

Returned when the build is already publishing or has finished. The status check and the update happen in one step, so if the build moves on between your request and the update you also get this error.

json
{
"error": {
"code": "build_not_cancellable",
"message": "This build is already publishing and can no longer be cancelled.",
"details": {
"status": "deploying",
"traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10"
}
}
}

For a finished build the message is This build has already finished (<status>).

Was this page helpful? Yes No
Request
cURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl -X POST https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/builds/bld_xyz789/cancel \
-H "Authorization: Bearer stx_abc12345_..."
Responseapplication/json
200OK
{
"data": {
"id": "bld_xyz789",
"projectId": "3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c",
"priority": 0,
"status": "cancelled",
"trigger": "manual",
"commitSha": null,
"commitMessage": null,
"filesChanged": null,
"branch": "main",
"isPreview": false,
"deployUrl": null,
"error": "Cancelled by API key \"ci\"",
"pageCount": null,
"durationMs": 2140,
"contentHash": null,
"sourcePath": null,
"deployId": null,
"warnings": 0,
"degraded": [],
"triggeredByUserId": null,
"createdAt": "2026-11-08T12:00:00Z",
"startedAt": "2026-11-08T12:00:01Z",
"completedAt": "2026-11-08T12:00:03Z"
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext