Skip to content
BuildWorkPro Docs

Cancel job

POST
/jobs/{id}/cancel
 
curl --request POST \
  --url https://app.buildworkpro.com/api/v1/jobs/example/cancel \
  --header 'Authorization: Bearer <token>'

Cancels a queued or running job. Already-terminal jobs return 409.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
id
required
string

Header Parameters

Section titled “ Header Parameters ”
Idempotency-Key
string format: uuid
<= 255 characters

Idempotent retry key for mutating operations. The first request with a given key executes normally and BuildWorkPro caches the response. Replaying the same key with the same request body (method + path + JSON body, SHA-256 hashed) returns the cached response without re-executing the mutation. Replaying with a DIFFERENT body returns 409 idempotency_key_reused. The cache TTL is 24 hours; after expiry the key is treated as a new operation. Keys are tenant-scoped. Recommended: a fresh UUID v4 per logical operation.

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Cancelled

Media type application/json
object
data
required
object
id
required
string
type
required
string
resourceType
required
string
status
required
string
progress
object
processed
required
integer
total
required
integer
errorsCount
required
integer
params
result
errorMessage
string | null
createdAt
required
Any of:
string format: date-time
startedAt
Any of:
string format: date-time
completedAt
Any of:
string format: date-time
expiresAt
required
Any of:
string format: date-time
meta
required
object
request_id

Server-generated request identifier

string
pagination
object
cursor
required

Opaque cursor for the next page; null when no more results

string | null
has_more
required

Whether more pages are available after this one

boolean
count
required

Items in this page

integer
Example generated 
{
  "data": {
    "id": "example",
    "type": "example",
    "resourceType": "example",
    "status": "example",
    "progress": {
      "processed": 1,
      "total": 1,
      "errorsCount": 1
    },
    "params": "example",
    "result": "example",
    "errorMessage": "example",
    "createdAt": "2026-04-15T12:00:00Z",
    "startedAt": "2026-04-15T12:00:00Z",
    "completedAt": "2026-04-15T12:00:00Z",
    "expiresAt": "2026-04-15T12:00:00Z"
  },
  "meta": {
    "request_id": "example",
    "pagination": {
      "cursor": "example",
      "has_more": true,
      "count": 1
    }
  }
}

404

Section titled “ 404 ”

Not found

Media type application/problem+json
object
type
required

URL identifying the problem type

string format: uri
title
required

Short human-readable summary

string
status
required

HTTP status code

integer
detail

Human-readable explanation

string
request_id

Server-generated request identifier

string
errors

Validation error array (422 only)

Array<object>
object
field
required

Field path that failed validation

string
code
required

Validation error code

string
message
required

Human-readable validation message

string
Example generated 
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "request_id": "example",
  "errors": [
    {
      "field": "example",
      "code": "example",
      "message": "example"
    }
  ]
}

409

Section titled “ 409 ”

Job already terminal

Media type application/problem+json
object
type
required

URL identifying the problem type

string format: uri
title
required

Short human-readable summary

string
status
required

HTTP status code

integer
detail

Human-readable explanation

string
request_id

Server-generated request identifier

string
errors

Validation error array (422 only)

Array<object>
object
field
required

Field path that failed validation

string
code
required

Validation error code

string
message
required

Human-readable validation message

string
Example generated 
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "request_id": "example",
  "errors": [
    {
      "field": "example",
      "code": "example",
      "message": "example"
    }
  ]
}