Cancel Artifact

Cancel a queued or processing artifact.

Cancellation is atomic โ€” once the API returns 200, the artifact will not transition to any other state. See the Artifacts overview for lifecycle rules.

Cancelling a non-terminal artifact:

  • Flips status to cancelled and sets completed_at.
  • Frees the artifact's idempotencyKey for reuse on a future create.
  • Generation work in progress stops; no further bytes are written and any partial output is discarded.

Cancelling an already-terminal artifact (succeeded, failed, cancelled, purged) returns 409 cancel_invalid_state. Only a queued or processing artifact can be cancelled.

Use cases

  • Abort an artifact you no longer need (e.g. a user closed the UI before the bundle completed).
  • Free an idempotencyKey after a misconfigured request so a retry can use the same key.

Path parameters

ParamTypeDescription
iduuidArtifact ID. Must be visible to your organization.

Response schema (data)

Identical to GET /artifacts/:id. On a successful cancellation status is cancelled and completed_at is the cancellation timestamp.

Status codes

  • 200 โ€” Artifact cancelled. The response carries the full artifact resource in its new cancelled state.
  • 400 โ€” Invalid id (not a UUID).
  • 401 โ€” Missing or invalid API key.
  • 403 โ€” Caller lacks the artifacts:write scope.
  • 404 โ€” Artifact does not exist or is not visible to your organization.
  • 409 โ€” cancel_invalid_state: the artifact is already in a terminal state.

Required scope: artifacts:write