Skip to content
builders.ac

Provisioning API · Internal testing only

getOperation

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

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.

Responses

Section titled “Responses”

200

Section titled “200”

Operation.

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”
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.

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.