Skip to content
builders.ac

Provisioning API · Internal testing only

cancelOperation

POST
/operations/{op}/cancel
curl --request POST \
  --url https://api.builders.ac/api/provisioning/v1alpha1/operations/op_01k5nd7v2qe9ma4bt3rz8hy6xw/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: example'

Requests best-effort cancellation. Provider work already submitted may finish before cancellation takes effect.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
op
required
string
>= 29 characters <= 29 characters /^[oO][pP]_[0-7][0-9a-hjkmnp-tv-zA-HJKMNP-TV-Z]{25}$/

Operation TypeIDs are accepted case-insensitively. Responses use canonical lowercase.

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
required
string
>= 1 characters <= 255 characters /^[\x20-\x7E]+$/

A client-generated key containing 1–255 printable ASCII characters (0x20 through 0x7E). Reuse it only for exact retries of one logical request.

Responses

Section titled “Responses”

200

Section titled “200”

Cancellation requested, or the unchanged Operation when it was already terminal.

Media typeapplication/json
One of: discriminator: type
One of: discriminator: type
object
id
required

Canonical lowercase TypeID.

string
>= 29 characters <= 29 characters /^op_[0-7][0-9a-hjkmnp-tv-z]{25}$/
object
required
Allowed value: operation
workspace_id
required

Canonical lowercase TypeID.

string
>= 30 characters <= 30 characters /^wsp_[0-7][0-9a-hjkmnp-tv-z]{25}$/
parent_operation_id

Nearest ancestor public Operation which caused this child Operation. Omitted on root Operations.

string
>= 29 characters <= 29 characters /^op_[0-7][0-9a-hjkmnp-tv-z]{25}$/
type
required
Allowed value: inbox.create
state
required
string
Allowed values: pending running
done
required
target
required
object
object
required
Allowed value: inbox_collection
ids
required
Array<string>
>= 1 items <= 150 items unique items
metadata
required
object
domain_id
required

Canonical lowercase TypeID.

string
>= 30 characters <= 30 characters /^dom_[0-7][0-9a-hjkmnp-tv-z]{25}$/
requested
required
integer
>= 1 <= 150
active
required
integer
<= 150
failed
required
integer
<= 150
retrying
required
integer
<= 150
created_at
required
string format: date-time
started_at
string format: date-time
finished_at
string format: date-time
cancel_requested_at

Cancellation was requested. It is honoured only at a safe boundary, so keep polling state and done to learn whether it took effect.

string format: date-time
update_by_date
required

Next date by which meaningful progress should be visible.

string format: date-time
completion_by_date
required

Public completion SLA for this Operation.

string format: date-time
Example
{
  "id": "op_01k5nd7v2qe9ma4bt3rz8hy6xw",
  "object": "operation",
  "workspace_id": "wsp_01k5n2rf8bd3xa9e7m4jt6vq5h",
  "parent_operation_id": "op_01k5nf4b8yt3qd7vm2ae9rz6hx",
  "type": "inbox.create",
  "state": "pending",
  "done": false,
  "target": {
    "object": "inbox_collection",
    "ids": [
      "inb_01k5nc9te4vr7bd2hq8ym3xz6a"
    ]
  },
  "metadata": {
    "domain_id": "dom_01k5nb3wz7q2hj8vd4rt6ye9ma",
    "requested": 3,
    "active": 3,
    "failed": 0,
    "retrying": 0
  },
  "created_at": "2026-04-15T09:15:04Z",
  "started_at": "2026-04-15T09:15:05Z",
  "update_by_date": "2026-04-15T09:45:04Z",
  "completion_by_date": "2026-04-15T10:15:04Z"
}

Headers

Section titled “Headers”
Idempotency-Replayed
string
Allowed value: true

Present with value true only for a stored exact replay.

x-correlation-id
string

The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.

400

Section titled “400”

Idempotency key required. The example shows idempotency_key_required.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
code
required

Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.

string
retryable
required
boolean
retry_after
string format: date-time
correlation_id
required
string
errors
object
key
additional properties
Array<string>
Example
{
  "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/idempotency_key_required",
  "title": "Idempotency key required",
  "status": 400,
  "detail": "This request requires a valid Idempotency-Key header.",
  "code": "idempotency_key_required",
  "retryable": false,
  "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"
}

Headers

Section titled “Headers”
x-correlation-id
string

The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.

401

Section titled “401”

Authentication required. The example shows authentication_required; this status is also answered with invalid_api_key. Branch on code, not on the status.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
code
required

Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.

string
retryable
required
boolean
retry_after
string format: date-time
correlation_id
required
string
errors
object
key
additional properties
Array<string>
Example
{
  "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/authentication_required",
  "title": "Authentication required",
  "status": 401,
  "detail": "Provide an active Provisioning API Key as a Bearer token.",
  "code": "authentication_required",
  "retryable": false,
  "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"
}

Headers

Section titled “Headers”
x-correlation-id
string

The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.

403

Section titled “403”

Account inactive. The example shows account_inactive; this status is also answered with insufficient_proof. Branch on code, not on the status.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
code
required

Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.

string
retryable
required
boolean
retry_after
string format: date-time
correlation_id
required
string
errors
object
key
additional properties
Array<string>
Example
{
  "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/account_inactive",
  "title": "Account inactive",
  "status": 403,
  "detail": "This account is inactive.",
  "code": "account_inactive",
  "retryable": false,
  "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"
}

Headers

Section titled “Headers”
x-correlation-id
string

The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.

404

Section titled “404”

Not found. The example shows not_found.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
code
required

Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.

string
retryable
required
boolean
retry_after
string format: date-time
correlation_id
required
string
errors
object
key
additional properties
Array<string>
Example
{
  "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/not_found",
  "title": "Not found",
  "status": 404,
  "detail": "The requested resource was not found.",
  "code": "not_found",
  "retryable": false,
  "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"
}

Headers

Section titled “Headers”
x-correlation-id
string

The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.

409

Section titled “409”

Request already in progress. The example shows idempotency_in_progress; this status is also answered with external_id_conflict, persona_in_use, workspace_archived, domain_not_ready, inbox_address_unavailable, operation_cancelled, resource_operation_in_progress, workspace_limit_reached, workspace_not_empty, workspace_is_default, workspace_last_active, nameservers_not_delegated, external_id_immutable, domain_already_exists, domain_unavailable, resource_quota_exceeded, domain_inbox_capacity_exceeded, domain_inbox_count_invalid, domain_not_active, domain_traffic_unavailable, redirect_not_configured, domain_not_reconnectable, account_not_provisioned, provider_account_in_use, no_inboxes_to_upload. Branch on code, not on the status.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
code
required

Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.

string
retryable
required
boolean
retry_after
string format: date-time
correlation_id
required
string
errors
object
key
additional properties
Array<string>
Example
{
  "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/idempotency_in_progress",
  "title": "Request already in progress",
  "status": 409,
  "detail": "A request using this idempotency key is still in progress.",
  "code": "idempotency_in_progress",
  "retryable": true,
  "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"
}

Headers

Section titled “Headers”
x-correlation-id
string

The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.

422

Section titled “422”

Validation failed. The example shows validation_error; this status is also answered with idempotency_mismatch, invalid_sealed_value, mailbox_upload_unavailable, provider_credentials_invalid, domains_not_bound, sequencer_targets_mixed. Branch on code, not on the status.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
code
required

Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.

string
retryable
required
boolean
retry_after
string format: date-time
correlation_id
required
string
errors
object
key
additional properties
Array<string>
Example
{
  "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/validation_error",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more request fields are invalid.",
  "code": "validation_error",
  "retryable": false,
  "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3",
  "errors": {
    "display_name": [
      "The display name must not be blank."
    ]
  }
}

Headers

Section titled “Headers”
x-correlation-id
string

The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.

429

Section titled “429”

Rate limit exceeded. The example shows rate_limit_exceeded.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
code
required

Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.

string
retryable
required
boolean
retry_after
string format: date-time
correlation_id
required
string
errors
object
key
additional properties
Array<string>
Example
{
  "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/rate_limit_exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "Too many requests were made for this policy.",
  "code": "rate_limit_exceeded",
  "retryable": true,
  "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3",
  "retry_after": "2026-04-15T09:16:04Z"
}

Headers

Section titled “Headers”
x-correlation-id
string

The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.

503

Section titled “503”

Service unavailable. The example shows service_unavailable; this status is also answered with encryption_keys_unavailable, provider_unreachable. Branch on code, not on the status.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
required
string
code
required

Extensible enum. Branch on this, never on title. New codes may appear at any time, so treat an unrecognised one as its HTTP status; GET /problems lists every code this version can answer with, and GET /problems/{code} resolves one.

string
retryable
required
boolean
retry_after
string format: date-time
correlation_id
required
string
errors
object
key
additional properties
Array<string>
Example
{
  "type": "https://api.builders.ac/api/provisioning/v1alpha1/problems/service_unavailable",
  "title": "Service unavailable",
  "status": 503,
  "detail": "Retry the request later; the service is temporarily unavailable.",
  "code": "service_unavailable",
  "retryable": true,
  "correlation_id": "9f1c2b7a-3d5e-4c81-9a77-2f6b0e4d51c3"
}

Headers

Section titled “Headers”
x-correlation-id
string

The id of this request, echoed on every response and repeated in the correlation_id member of a problem body. Quote it in support requests.