Skip to content
builders.ac

Provisioning API · Internal testing only

listOperations

GET
/operations
curl --request GET \
  --url 'https://api.builders.ac/api/provisioning/v1alpha1/operations?limit=20&order=created_at.asc&state=pending&type=inbox.create' \
  --header 'Authorization: Bearer <token>'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
limit
integer
default: 20 >= 1 <= 100
starting_after
string
>= 1 characters <= 2048 characters

Opaque cursor returned by an Operation page for the same Account, order, and filters.

order
string
default: created_at.desc
Allowed values: created_at.asc created_at.desc

Creation-time order with Operation ID as the tie-breaker.

workspace_id
Array<string>
>= 1 items <= 100 items

One to 100 comma-separated, case-insensitive Workspace TypeIDs. Omit to span every accessible Workspace.

external_customer_id
string
>= 1 characters <= 255 characters /^[^\u0000]+$/

Exact end-customer reference carried by the owning Workspace.

state
string
Allowed values: pending running succeeded failed cancelled
type
string
Allowed values: inbox.create inbox.deprovision inbox.upload domain.connect domain.provision domain.deprovision domain.redirect domain.clone
created[gte]
string format: date-time
/^(?!0000)\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?(?:Z|\+00:00)(?![\s\S])/

Inclusive ISO-8601 UTC lower bound.

created[lte]
string format: date-time
/^(?!0000)\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?(?:Z|\+00:00)(?![\s\S])/

Inclusive ISO-8601 UTC upper bound; must not precede created[gte].

Responses

Section titled “Responses”

200

Section titled “200”

Operation page.

Media typeapplication/json
object
data
required
Array
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
has_more
required
boolean
next_cursor
required
string | null
Example
{
  "data": [
    {
      "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"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNC0xNVQwOToxNTowNFoiLCJpZCI6ImluYl8wMWs1bmM5dGU0dnI3YmQyaHE4eW0zeHo2YSJ9"
}

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.

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.