CALIBER Python SDK API reference

Every documented class and module-level function, with the module that defines it. Members hang off their class, so start here and follow the link.

A

B

C

E

F

G

I

J

K

L

M

N

O

P

Q

R

S

T

U

V

W

Module caliber_sdk#

caliber-sdk — a typed Python client for the CALIBER management API.

Tested example

def quickstart(caliber: CaliberClient) -> dict[str, Any]:
    """Report who you are and which API surfaces are GA on this deployment."""
    identity = caliber.me.get()
    if identity.is_anonymous:
        # /me answers "who am I" rather than requiring a credential, so an
        # invalid token shows up here as anonymous instead of an exception.
        raise SystemExit("no usable credential — check CALIBER_TOKEN")

    capabilities = caliber.capabilities_info.get()
    return {
        "user_id": identity.user_id,
        "scopes": identity.scopes,
        "ga_surfaces": sorted(capabilities.sdk_stability.get("ga", [])),
        "queue_enabled": capabilities.workflow_runs.queue_enabled,
    }

Public exports

API_PREFIX, ENV_BASE_URL, ENV_PROJECT, ENV_TOKEN, ENV_USER, FAILURE_STATES, TERMINAL_STATES, UNSET_PROJECT, AuthProvider, CaliberAPIError, CaliberAuthenticationError, CaliberClient, CaliberConfigError, CaliberConflictError, CaliberDecodeError, CaliberError, CaliberNotFoundError, CaliberPermissionError, CaliberPreconditionError, CaliberRateLimitError, CaliberServerError, CaliberTransportError, CaliberValidationError, ErrorBody, FieldError, NoAuth, Page, RawAPI, Response, Stability, TokenAuth, Transport, TrustedHeaderAuth, UnsetProjectType, WaitFailed, WaitTimeout, WorkflowRunFailed, __version__, wait_for, wait_for_terminal_state

Module constants

Module caliber_sdk.client#

The root client — what a developer constructs first.

Tested example

def quickstart(caliber: CaliberClient) -> dict[str, Any]:
    """Report who you are and which API surfaces are GA on this deployment."""
    identity = caliber.me.get()
    if identity.is_anonymous:
        # /me answers "who am I" rather than requiring a credential, so an
        # invalid token shows up here as anonymous instead of an exception.
        raise SystemExit("no usable credential — check CALIBER_TOKEN")

    capabilities = caliber.capabilities_info.get()
    return {
        "user_id": identity.user_id,
        "scopes": identity.scopes,
        "ga_surfaces": sorted(capabilities.sdk_stability.get("ga", [])),
        "queue_enabled": capabilities.workflow_runs.queue_enabled,
    }

Public exports

ENV_BASE_URL, ENV_PROJECT, ENV_TOKEN, ENV_USER, CaliberClient

Module constants

Classes#

CaliberClient#

class CaliberClient(base_url: str | None = None, *, token: str | None = None, user: str | None = None, proxy_secret: str | None = None, auth: AuthProvider | None = None, project: str | None = None, timeout: float = 30.0, max_retries: int = 2, verify: bool | str = True, http_client: httpx.Client | None = None)

A connection to one CALIBER deployment.

Usage example

def quickstart(caliber: CaliberClient) -> dict[str, Any]:
    """Report who you are and which API surfaces are GA on this deployment."""
    identity = caliber.me.get()
    if identity.is_anonymous:
        # /me answers "who am I" rather than requiring a credential, so an
        # invalid token shows up here as anonymous instead of an exception.
        raise SystemExit("no usable credential — check CALIBER_TOKEN")

    capabilities = caliber.capabilities_info.get()
    return {
        "user_id": identity.user_id,
        "scopes": identity.scopes,
        "ga_surfaces": sorted(capabilities.sdk_stability.get("ga", [])),
        "queue_enabled": capabilities.workflow_runs.queue_enabled,
    }

Constructor

__init__(base_url: str | None = None, *, token: str | None = None, user: str | None = None, proxy_secret: str | None = None, auth: AuthProvider | None = None, project: str | None = None, timeout: float = 30.0, max_retries: int = 2, verify: bool | str = True, http_client: httpx.Client | None = None) -> None#

Operate on the caliber client surface with the supplied arguments and return the server response.

Returns: None

Raises:

• CaliberConfigError

Attributes

Properties

stability() -> dict[str, list[str]]#

Tags grouped by `ga / beta / internal`.

This callable takes no public parameters.

Returns: dict[str, list[str]]

capabilities_api() -> CapabilitiesAPI#

Deprecated alias for :attr:capabilities_info.

`capabilities_api reads as "the capabilities API resource", which is accurate but indistinguishable from CaliberClient.capabilities() at a glance. capabilities_info` names what it actually returns.

This callable takes no public parameters.

Returns: CapabilitiesAPI

datasets() -> EvalDatasetsAPI#

Deprecated alias for :attr:eval_datasets.

`datasets reads as every kind of stored data CALIBER has (prompt datasets, knowledge bases, ...); eval_datasets` names the one this resource actually is.

This callable takes no public parameters.

Returns: EvalDatasetsAPI

Methods

close() -> None#

Close the underlying HTTP client or transport owned by this object.

This callable takes no public parameters.

Returns: None

__enter__() -> CaliberClient#

Return this instance so it can be used inside a context manager.

This callable takes no public parameters.

Returns: CaliberClient

__exit__(*_: object) -> None#

Close any owned resources when leaving the context manager.

Returns: None

workspace_scope(project_id: str) -> Iterator[CaliberClient]#

Temporarily select the workspace sent on subsequent requests.

This is useful when a script creates its own workspace and needs the following prompt, dataset, workflow, or assistant records to belong to that project. The previous selection is restored even when an operation raises, so a reusable client does not silently leak project context into the caller's next task.

Project selection is stored in the current thread/task context, so a concurrent caller gets its own selection. Per-request project pins are still preferred for resource methods whose path names the project.

Returns: Iterator[CaliberClient]

Raises:

• CaliberConfigError

library_scope() -> Iterator[CaliberClient]#

Temporarily omit the project header for a library-scoped call.

`None` is intentionally distinct from an unset scope: it prevents a constructor or outer workspace scope from leaking into a platform or personal-library request. The prior scope is restored on exit.

This callable takes no public parameters.

Returns: Iterator[CaliberClient]

project_scope(project_id: str) -> Iterator[CaliberClient]#

Compatibility alias for :meth:workspace_scope.

Returns: Iterator[CaliberClient]

Raises:

• CaliberConfigError

capabilities() -> Any#

Runtime feature flags and the SDK stability tiers.

The cheap half of feature detection: it answers "may I call this?" without downloading the full OpenAPI document.

This callable takes no public parameters.

Returns: Any

Raises:

• CaliberAPIError
• CaliberTransportError

openapi() -> Any#

The management OpenAPI document, generated from the live routes.

This callable takes no public parameters.

Returns: Any

Raises:

• CaliberAPIError
• CaliberTransportError

whoami() -> Any#

The identity and scopes CALIBER resolved for this client's credential.

The first call worth making when a script gets an unexpected 403: it distinguishes "wrong credential" from "right credential, wrong scope".

It reports identity rather than requiring it, so an invalid or revoked credential does not raise here -- it returns `user_id: "anonymous"` with no scopes. Check the value; do not rely on an exception to detect a bad token.

This callable takes no public parameters.

Returns: Any

Raises:

• CaliberAPIError
• CaliberTransportError

health() -> Any#

Fetch the lightweight health/readiness view exposed by the deployment.

This callable takes no public parameters.

Returns: Any

Raises:

• CaliberAPIError
• CaliberTransportError

readiness() -> Any#

Whether CALIBER's configured dependencies (database, object storage, MLflow, ...) are actually reachable -- stronger than :meth:health, which only reports the process is up.

This callable takes no public parameters.

Returns: Any

Raises:

• CaliberAPIError
• CaliberTransportError

dashboard_summary() -> Any#

Aggregate counts and status tiles for the Overview page.

This callable takes no public parameters.

Returns: Any

Raises:

• CaliberAPIError
• CaliberTransportError

bootstrap_csrf() -> str | None#

Fetch a CSRF token up front.

Rarely needed: the transport fetches one automatically when a write is refused for want of it. Exposed for callers who would rather pay that round trip at startup than on their first write.

This callable takes no public parameters.

Returns: str | None

__repr__() -> str#

Operate on the caliber client surface with the supplied arguments and return the server response.

This callable takes no public parameters.

Returns: str

Module caliber_sdk.auth#

Authentication strategies for the CALIBER management API.

Tested example

def issue_scoped_token(caliber: CaliberClient, *, name: str = "ci") -> dict[str, Any]:
    """Create a token limited to operator scope.

    The scope list is a *ceiling*: the effective authority is the intersection
    with what the owner holds when the request is made. Requesting more than
    you hold is refused outright rather than silently narrowed, so a token
    never claims authority it cannot exercise.
    """
    issued = caliber.auth.tokens.create(name, scopes=["caliber.operator"])
    # The plaintext exists exactly once. There is no endpoint that returns it
    # again — store it now or rotate to get a new one.
    secret = issued.token

    live = [token.token_id for token in caliber.auth.tokens.list() if token.active]
    caliber.auth.tokens.revoke(issued.token_id)
    return {"token_id": issued.token_id, "secret_len": len(secret), "live_before_revoke": live}

Public exports

AuthProvider, NoAuth, TokenAuth, TrustedHeaderAuth

Classes#

AuthProvider#

class AuthProvider()

Bases: Protocol

Supplies per-request auth headers.

A protocol rather than a base class so a caller can plug in their own -- fetching a short-lived token from a secret manager, for instance -- without subclassing anything in this package.

Properties

uses_cookie_auth() -> bool#

Whether this credential is cookie-based.

Drives CSRF: CALIBER's protection exists for browser credentials, and a Bearer client should not be forced to bootstrap a token it does not need. See :mod:caliber_sdk.csrf.

This callable takes no public parameters.

Returns: bool

Methods

headers() -> dict[str, str]#

Headers to attach to every request.

This callable takes no public parameters.

Returns: dict[str, str]

TokenAuth#

class TokenAuth(token: str)

`Authorization: Bearer <token>` — personal access or session token.

Constructor

__init__(token: str) -> None#

Operate on the token auth surface with the supplied arguments and return the server response.

Returns: None

Raises:

• CaliberConfigError

Properties

uses_cookie_auth() -> bool#

Report whether this auth strategy relies on cookie-backed authentication.

This callable takes no public parameters.

Returns: bool

Methods

headers() -> dict[str, str]#

Build the authentication headers added to outgoing HTTP requests.

This callable takes no public parameters.

Returns: dict[str, str]

__repr__() -> str#

Operate on the token auth surface with the supplied arguments and return the server response.

This callable takes no public parameters.

Returns: str

TrustedHeaderAuth#

class TrustedHeaderAuth(user: str, *, proxy_secret: str | None = None)

`X-CALIBER-User — only for deployments in trusted_header` mode.

Carries no proof of identity by itself, which is why CALIBER ignores the header entirely in the default `session` mode. Offered because local development and proxy-terminated deployments genuinely use it.

Constructor

__init__(user: str, *, proxy_secret: str | None = None) -> None#

Operate on the trusted header auth surface with the supplied arguments and return the server response.

Returns: None

Raises:

• CaliberConfigError

Properties

uses_cookie_auth() -> bool#

Report whether this auth strategy relies on cookie-backed authentication.

This callable takes no public parameters.

Returns: bool

Methods

headers() -> dict[str, str]#

Build the authentication headers added to outgoing HTTP requests.

This callable takes no public parameters.

Returns: dict[str, str]

__repr__() -> str#

Operate on the trusted header auth surface with the supplied arguments and return the server response.

This callable takes no public parameters.

Returns: str

NoAuth#

class NoAuth()

Send no credential. Useful for probing an unauthenticated endpoint.

Properties

uses_cookie_auth() -> bool#

Report whether this auth strategy relies on cookie-backed authentication.

This callable takes no public parameters.

Returns: bool

Methods

headers() -> dict[str, str]#

Build the authentication headers added to outgoing HTTP requests.

This callable takes no public parameters.

Returns: dict[str, str]

Module caliber_sdk.transport#

HTTP transport: envelopes, errors, retries, CSRF, and correlation.

Tested example

def quickstart(caliber: CaliberClient) -> dict[str, Any]:
    """Report who you are and which API surfaces are GA on this deployment."""
    identity = caliber.me.get()
    if identity.is_anonymous:
        # /me answers "who am I" rather than requiring a credential, so an
        # invalid token shows up here as anonymous instead of an exception.
        raise SystemExit("no usable credential — check CALIBER_TOKEN")

    capabilities = caliber.capabilities_info.get()
    return {
        "user_id": identity.user_id,
        "scopes": identity.scopes,
        "ga_surfaces": sorted(capabilities.sdk_stability.get("ga", [])),
        "queue_enabled": capabilities.workflow_runs.queue_enabled,
    }

Public exports

API_PREFIX, UNSET_PROJECT, USER_AGENT, Response, Transport, UnsetProjectType

Module constants

Classes#

UnsetProjectType#

class UnsetProjectType()

Sentinel distinguishing "use the ambient project" from an explicit `project=None (deliberately unscoped). A bare default of None` could not tell those apart.

Methods

__repr__() -> str#

Operate on the unset project type surface with the supplied arguments and return the server response.

This callable takes no public parameters.

Returns: str

Response#

class Response(*, data, status_code: int, headers: Mapping[str, str], request_id: str | None)

A decoded response plus the context needed to debug it.

Constructor

__init__(*, data, status_code: int, headers: Mapping[str, str], request_id: str | None) -> None#

Operate on the response surface with the supplied arguments and return the server response.

Returns: None

Attributes

Transport#

class Transport(base_url: str, *, auth: AuthProvider | None = None, project: str | None = None, timeout: float = 30.0, max_retries: int = 2, backoff_factor: float = 0.5, verify: bool | str = True, client: httpx.Client | None = None, user_agent: str | None = None)

Synchronous HTTP transport against one CALIBER deployment.

The ambient project is context-local. Per-request `project=` pins remain the preferred choice for resource methods whose path names the project.

Constructor

__init__(base_url: str, *, auth: AuthProvider | None = None, project: str | None = None, timeout: float = 30.0, max_retries: int = 2, backoff_factor: float = 0.5, verify: bool | str = True, client: httpx.Client | None = None, user_agent: str | None = None) -> None#

Send a prepared request through the shared transport and decode the typed response wrapper.

Returns: None

Raises:

• CaliberConfigError

Attributes

Properties

project() -> str | None#

The ambient project in the current thread/task context.

This callable takes no public parameters.

Returns: str | None

Methods

project(value: str | None) -> None#

Send a prepared request through the shared transport and decode the typed response wrapper.

Returns: None

close() -> None#

Close the underlying HTTP client or transport owned by this object.

This callable takes no public parameters.

Returns: None

__enter__() -> Transport#

Return this instance so it can be used inside a context manager.

This callable takes no public parameters.

Returns: Transport

__exit__(*_: object) -> None#

Close any owned resources when leaving the context manager.

Returns: None

url_for(path: str) -> str#

Absolute URL for an API path, with or without the prefix.

Returns: str

bootstrap_csrf() -> str | None#

Fetch and cache a CSRF token, returning it.

Idempotent and cheap to call. Returns `None` when the deployment does not issue one, which is not an error: CSRF enforcement is configurable and a Bearer client may not need it.

This callable takes no public parameters.

Returns: str | None

request(method: str, path: str, *, params: Mapping[str, Any] | None = None, json = None, headers: Mapping[str, str] | None = None, files = None, data: Mapping[str, Any] | None = None, timeout: float | None = None, project: str | UnsetProjectType | None = UNSET_PROJECT, _csrf_retry: bool = True) -> Response#

Perform one API call, returning the unwrapped payload.

`project, when passed, pins the request's X-CALIBER-Project header regardless of the ambient (constructor/project_scope) scope -- resource modules that build a /projects/{project_id}/... path use this to send that same id, never whatever the client happens to be scoped to. Left at its default (UNSET_PROJECT), the ambient scope applies unchanged; None` deliberately omits the header even if an ambient scope is set.

Returns: Response

Raises:

• CaliberAPIError
• CaliberConfigError
• CaliberTransportError

get(path: str, **kwargs) -> Response#

Fetch one record from the transport surface identified by path.

Returns: Response

Raises:

• CaliberAPIError
• CaliberTransportError

post(path: str, **kwargs) -> Response#

Send a prepared request through the shared transport and decode the typed response wrapper.

Returns: Response

Raises:

• CaliberAPIError
• CaliberTransportError

put(path: str, **kwargs) -> Response#

Send a prepared request through the shared transport and decode the typed response wrapper.

Returns: Response

Raises:

• CaliberAPIError
• CaliberTransportError

patch(path: str, **kwargs) -> Response#

Send a prepared request through the shared transport and decode the typed response wrapper.

Returns: Response

Raises:

• CaliberAPIError
• CaliberTransportError

delete(path: str, **kwargs) -> Response#

Delete a record on the transport surface and return the server acknowledgement.

Returns: Response

Raises:

• CaliberAPIError
• CaliberTransportError

download(path: str, *, project: str | UnsetProjectType | None = UNSET_PROJECT, **kwargs) -> bytes#

Fetch raw bytes.

Separate from :meth:request because file content is not JSON: it has no envelope to unwrap and decoding it would corrupt binary data.

`project pins the request the same way it does for :meth:request`.

Returns: bytes

Raises:

• CaliberAPIError
• CaliberTransportError

stream_lines(path: str, *, params: Mapping[str, Any] | None = None, timeout: float | None = None) -> Iterator[str]#

Yield lines from a server-sent-events endpoint.

Streaming needs its own path: the ordinary request reads the whole body before returning, which for an endpoint that never ends means blocking forever. No default timeout is applied either — a stream staying open is the success case, not a hang.

Returns: Iterator[str]

Raises:

• CaliberAPIError
• CaliberTransportError

paginate(path: str, *, params: Mapping[str, Any] | None = None, limit: int = 100) -> Iterator[Any]#

Yield items across `limit/offset` pages.

CALIBER's list endpoints are offset-based today. Exposing an iterator rather than the raw pages means the eventual move to cursors does not change this signature.

Returns: Iterator[Any]

Raises:

• CaliberAPIError
• CaliberTransportError

Module caliber_sdk.errors#

Exception hierarchy for the CALIBER SDK.

Tested example

def quickstart(caliber: CaliberClient) -> dict[str, Any]:
    """Report who you are and which API surfaces are GA on this deployment."""
    identity = caliber.me.get()
    if identity.is_anonymous:
        # /me answers "who am I" rather than requiring a credential, so an
        # invalid token shows up here as anonymous instead of an exception.
        raise SystemExit("no usable credential — check CALIBER_TOKEN")

    capabilities = caliber.capabilities_info.get()
    return {
        "user_id": identity.user_id,
        "scopes": identity.scopes,
        "ga_surfaces": sorted(capabilities.sdk_stability.get("ga", [])),
        "queue_enabled": capabilities.workflow_runs.queue_enabled,
    }

Public exports

CaliberAPIError, CaliberAuthenticationError, CaliberConfigError, CaliberConflictError, CaliberDecodeError, CaliberError, CaliberNotFoundError, CaliberPermissionError, CaliberPreconditionError, CaliberRateLimitError, CaliberServerError, CaliberTransportError, CaliberValidationError, error_for_response

Functions#

error_for_response(*, status_code: int, payload, method: str, url: str, request_id: str | None = None) -> CaliberAPIError#

Build the right exception for a non-2xx response.

Tolerates a body that is not the documented shape -- an HTML error page from a proxy in front of CALIBER is a realistic response, and it must produce a usable exception rather than a KeyError inside the SDK.

Returns: CaliberAPIError

Classes#

CaliberError#

class CaliberError()

Bases: Exception

Base class for everything this SDK raises.

A caller who wants "any SDK failure" catches this and nothing else.

CaliberConfigError#

class CaliberConfigError()

Bases: CaliberError

The client was constructed with an unusable configuration.

CaliberTransportError#

class CaliberTransportError()

Bases: CaliberError

The request never produced an HTTP response.

Connection refused, DNS failure, timeout. Distinct from :class:CaliberAPIError because there is no server verdict to inspect -- and because retrying is often correct here and often wrong there.

CaliberDecodeError#

class CaliberDecodeError(payload)

Bases: CaliberError

A 2xx payload had the wrong shape to decode.

Distinct from :class:CaliberAPIError: the request succeeded and the server is not complaining about anything, but the payload was not the list (or object) this call expected -- an error page from a misconfigured proxy, an envelope from the wrong endpoint, `None where a body was required. Raised only by callers that opt into strict decoding (decode_list(..., strict=True)`); by default a shape mismatch degrades to an empty result instead, per this module's tolerant-decoding principle (S4) -- strict mode exists for the contract tests that must tell "empty" apart from "wrong shape entirely".

Constructor

__init__(payload) -> None#

Operate on the caliber decode error surface with the supplied arguments and return the server response.

Returns: None

Attributes

CaliberAPIError#

class CaliberAPIError(message: str, *, status_code: int, detail: str | None = None, method: str | None = None, url: str | None = None, request_id: str | None = None, payload = None, reason_code: str | None = None)

Bases: CaliberError

The server returned a non-2xx response.

Constructor

__init__(message: str, *, status_code: int, detail: str | None = None, method: str | None = None, url: str | None = None, request_id: str | None = None, payload = None, reason_code: str | None = None) -> None#

Operate on the caliber a p i error surface with the supplied arguments and return the server response.

Returns: None

Attributes

CaliberAuthenticationError#

class CaliberAuthenticationError()

Bases: CaliberAPIError

401 — no usable identity. The credential is missing, wrong, or revoked.

CaliberPermissionError#

class CaliberPermissionError()

Bases: CaliberAPIError

403 — authenticated, but the identity lacks the required scope.

CaliberNotFoundError#

class CaliberNotFoundError()

Bases: CaliberAPIError

404 — no such resource.

CALIBER also returns this for a resource that exists but belongs to another user, deliberately: distinguishing the two would let a caller enumerate ids.

CaliberConflictError#

class CaliberConflictError()

Bases: CaliberAPIError

409 — the request conflicts with current state (duplicate name, etc.).

CaliberPreconditionError#

class CaliberPreconditionError()

Bases: CaliberAPIError

412 — a stale precondition (e.g. `If-Match`/ETag) failed.

Section 13.6's target design (`docs/workspace-plan.md) reserves 412 for a stale ETag / compare-and-set precondition, distinct from 409's "valid request, but conflicts with current state" -- the caller must re-read the current resource and retry with a fresh precondition rather than simply resubmitting the same request. Carries reason_code when the server sets one so a caller can distinguish *which* precondition failed without parsing detail`.

CaliberValidationError#

class CaliberValidationError(message: str, *, errors: list[dict[str, Any]], **kwargs)

Bases: CaliberAPIError

400 with a structured `errors` list.

Constructor

__init__(message: str, *, errors: list[dict[str, Any]], **kwargs) -> None#

Operate on the caliber validation error surface with the supplied arguments and return the server response.

Returns: None

Attributes

CaliberRateLimitError#

class CaliberRateLimitError()

Bases: CaliberAPIError

429 — too many requests.

CaliberServerError#

class CaliberServerError()

Bases: CaliberAPIError

5xx — the server failed. Usually worth retrying; never worth assuming.

Module caliber_sdk.waiters#

Polling helpers for CALIBER's long-running operations.

Tested example

def run_and_wait(
    caliber: CaliberClient, *, workflow_id: str, alias: str = "prod"

Public exports

FAILURE_STATES, TERMINAL_STATES, WaitFailed, WaitTimeout, state_of, wait_for, wait_for_terminal_state

Functions#

wait_for(poll: Callable[[], T], *, is_done: Callable[[T], bool], timeout: float = 300.0, interval: float = 2.0, max_interval: float = 15.0, backoff: float = 1.5, sleep: Callable[[float], None] = time.sleep, now: Callable[[], float] = time.monotonic) -> T#

Poll until `is_done` or the timeout expires.

The interval grows geometrically to `max_interval. A fixed short interval is what turns a slow job into thousands of requests; a fixed long one makes a fast job feel slow. sleep and now` are injectable so tests do not have to spend real seconds proving this.

Returns: T

Raises:

• ValueError
• WaitTimeout

state_of(payload, *, keys: Sequence[str] = ('status', 'state')) -> str#

Read a status field from a payload, tolerating either spelling.

Returns: str

wait_for_terminal_state(poll: Callable[[], Any], *, terminal: frozenset[str] = TERMINAL_STATES, failure: frozenset[str] = FAILURE_STATES, raise_on_failure: bool = True, **kwargs) -> Any#

Poll until the payload's status is terminal.

`raise_on_failure` is on by default because the common script wants a failed job to stop it; a caller inspecting the outcome themselves turns it off rather than wrapping every call in a try.

Returns: Any

Raises:

• WaitFailed
• WaitTimeout

Classes#

WaitTimeout#

class WaitTimeout(message: str, *, last = None, elapsed: float = 0.0)

Bases: CaliberError

The operation did not reach a terminal state within the budget.

Constructor

__init__(message: str, *, last = None, elapsed: float = 0.0) -> None#

Operate on the wait timeout surface with the supplied arguments and return the server response.

Returns: None

Attributes

WaitFailed#

class WaitFailed(message: str, *, state: str, last = None)

Bases: CaliberError

The operation reached a terminal state that indicates failure.

Constructor

__init__(message: str, *, state: str, last = None) -> None#

Operate on the wait failed surface with the supplied arguments and return the server response.

Returns: None

Attributes

Module caliber_sdk.resources#

Resource modules — typed façades over route groups.

Public exports

AccountsAPI, AdminAPI, AgentsAPI, AriaAPI, AriaDraftsAPI, AriaSessionsAPI, AuditAPI, AuthAPI, CapabilitiesAPI, CookbooksAPI, EvalDatasetsAPI, EvaluationsAPI, EventsAPI, GateVerdictsAPI, GatewayAPI, JobsAPI, JudgesAPI, KnowledgeBasesAPI, LlmPricingAPI, McpServersAPI, MeAPI, MemoryAPI, ObjectStoreAPI, ObservabilityAPI, OpenApiIntegrationsAPI, PlaygroundRunsAPI, ProjectFilesAPI, ProjectReworkTasksAPI, ProjectsAPI, PromptsAPI, QualityReviewsAPI, RawAPI, ReleasesAPI, Resource, ReviewQueuesAPI, ReworkTasksAPI, SecretsAPI, SettingsAPI, SkillsAPI, SystemAPI, TokensAPI, ToolsAPI, VerificationQueueAPI, WorkflowPromotionsAPI, WorkflowRunFailed, WorkflowRunsAPI, WorkflowServicesAPI, WorkflowVersionsAPI, WorkflowsAPI, WorkspacesAPI

Module caliber_sdk.resources.auth#

Authentication, tokens, and accounts.

Tested example

def issue_scoped_token(caliber: CaliberClient, *, name: str = "ci") -> dict[str, Any]:
    """Create a token limited to operator scope.

    The scope list is a *ceiling*: the effective authority is the intersection
    with what the owner holds when the request is made. Requesting more than
    you hold is refused outright rather than silently narrowed, so a token
    never claims authority it cannot exercise.
    """
    issued = caliber.auth.tokens.create(name, scopes=["caliber.operator"])
    # The plaintext exists exactly once. There is no endpoint that returns it
    # again — store it now or rotate to get a new one.
    secret = issued.token

    live = [token.token_id for token in caliber.auth.tokens.list() if token.active]
    caliber.auth.tokens.revoke(issued.token_id)
    return {"token_id": issued.token_id, "secret_len": len(secret), "live_before_revoke": live}

Public exports

AccountsAPI, AdminAPI, AuthAPI, TokensAPI

Classes#

TokensAPI#

class TokensAPI()

Personal access tokens for automation.

Methods

list() -> list[PersonalAccessToken]#

Every token belonging to the caller. Never includes a secret.

This callable takes no public parameters.

Returns: list[PersonalAccessToken]

Raises:

• CaliberAPIError
• CaliberTransportError

create(name: str, *, scopes: Sequence[str] | None = None, expires_at: str | None = None, project_id: str | None = None) -> IssuedToken#

Issue a token. The plaintext is returned once — store it now.

`scopes` is a ceiling, not a grant: the effective authority is the intersection with what the owner holds at request time. Omit it to inherit the owner's scopes. Requesting a scope the caller does not hold is refused rather than silently narrowed.

`project_id` optionally binds the token to one project you already hold a role in -- the server refuses to issue a token bound to a project you have no relationship with. A bound token is then refused for any request that names a different project.

Returns: IssuedToken

Raises:

• CaliberAPIError
• CaliberTransportError

revoke(token_id: str) -> bool#

Revoke a token. Returns whether a live token was actually revoked.

Returns: bool

Raises:

• CaliberAPIError
• CaliberTransportError

rotate(token_id: str) -> IssuedToken#

Replace a token's secret, preserving its name and scope ceiling.

One transaction on the server: the old token is revoked and the replacement issued together, so a failure cannot leave an account with two live tokens or none.

Returns: IssuedToken

Raises:

• CaliberAPIError
• CaliberTransportError

AccountsAPI#

class AccountsAPI()

User accounts. Admin-only on the server.

Methods

list() -> list[Account]#

Return the current collection of user accounts, applying any supported filters.

This callable takes no public parameters.

Returns: list[Account]

Raises:

• CaliberAPIError
• CaliberTransportError

create(user_id: str, password: str) -> Any#

Create a new record on the user accounts surface and return the server-normalized result. Validation and permission failures are surfaced through the standard CALIBER error hierarchy.

Returns: Any

Raises:

• CaliberAPIError
• CaliberTransportError

update(user_id: str, *, password: str | None = None, disabled: bool | None = None) -> Any#

Reset a password or enable/disable an account.

Both revoke the account's sessions server-side, so they take effect immediately rather than at the next expiry.

Returns: Any

Raises:

• CaliberAPIError
• CaliberTransportError

revoke_sessions(user_id: str) -> int#

Sign an account out everywhere. Returns how many sessions were cut.

Returns: int

Raises:

• CaliberAPIError
• CaliberTransportError

AuthAPI#

class AuthAPI(transport)

Session inspection, plus the token and account sub-resources.

Constructor

__init__(transport) -> None#

Operate on the authentication and session state surface with the supplied arguments and return the server response.

Returns: None

Attributes

Methods

session() -> SessionInfo#

How this client's identity was established.

This callable takes no public parameters.

Returns: SessionInfo

Raises:

• CaliberAPIError
• CaliberTransportError

AdminAPI#

class AdminAPI()

Platform-wide, admin-only operational surfaces.

Methods

platform_admin_inventory() -> PlatformAdminInventory#

Who currently holds each config-driven global scope.

Metadata only -- `caliber.admin-gated, and grants no project or resource access itself. See docs/workspace-plan.md` Phase 1 item 13 for why this exists: a recovery/support aid for "who do I even ask", not a capability.

This callable takes no public parameters.

Returns: PlatformAdminInventory

Raises:

• CaliberAPIError
• CaliberTransportError

Module caliber_sdk.resources.system#

Identity, capabilities, and settings — the deployment-level surfaces.

Tested example

def quickstart(caliber: CaliberClient) -> dict[str, Any]:
    """Report who you are and which API surfaces are GA on this deployment."""
    identity = caliber.me.get()
    if identity.is_anonymous:
        # /me answers "who am I" rather than requiring a credential, so an
        # invalid token shows up here as anonymous instead of an exception.
        raise SystemExit("no usable credential — check CALIBER_TOKEN")

    capabilities = caliber.capabilities_info.get()
    return {
        "user_id": identity.user_id,
        "scopes": identity.scopes,
        "ga_surfaces": sorted(capabilities.sdk_stability.get("ga", [])),
        "queue_enabled": capabilities.workflow_runs.queue_enabled,
    }

Public exports

CapabilitiesAPI, MeAPI, SettingsAPI

Classes#

MeAPI#

class MeAPI()

The caller's own identity.

Methods

get() -> Identity#

Resolve this client's identity and scopes.

Reports rather than requires: an invalid or revoked credential returns an anonymous identity instead of raising. Check :attr:Identity.is_anonymous; do not rely on an exception.

This callable takes no public parameters.

Returns: Identity

Raises:

• CaliberAPIError
• CaliberTransportError

CapabilitiesAPI#

class CapabilitiesAPI()

Runtime feature flags and API stability tiers.

Methods

get() -> Capabilities#

Fetch one record from the runtime capabilities surface identified by id.

This callable takes no public parameters.

Returns: Capabilities

Raises:

• CaliberAPIError
• CaliberTransportError

SettingsAPI#

class SettingsAPI()

Runtime configuration inventory and LLM credential status.

Methods

runtime() -> RuntimeSettings#

Return the current runtime settings snapshot for the deployment.

This callable takes no public parameters.

Returns: RuntimeSettings

Raises:

• CaliberAPIError
• CaliberTransportError

llm() -> LlmSetupStatus#

Which LLM credentials are configured.

Presence flags and masked fingerprints only — the endpoint does not disclose key values, deliberately.

This callable takes no public parameters.

Returns: LlmSetupStatus

Raises:

• CaliberAPIError
• CaliberTransportError

update_llm(**changes) -> Any#

Write LLM provider settings. Secrets are write-only on the server.

Returns: Any

Raises:

• CaliberAPIError
• CaliberTransportError

Module caliber_sdk.resources.projects#

Projects and their files — the workspace-scoping surface.

Tested example

def prompt_lifecycle(
    caliber: CaliberClient, *, agent_id: str = "intake-classifier"

Public exports

ProjectChangeRequestsAPI, ProjectFilesAPI, ProjectImportsAPI, ProjectMembersAPI, ProjectReleaseOperationsAPI, ProjectReleasesAPI, ProjectRevisionsAPI, ProjectReworkTasksAPI, ProjectSourceAPI, ProjectVersionTagsAPI, ProjectsAPI, WorkspacesAPI

Classes#

ProjectFilesAPI#

class ProjectFilesAPI()

Files inside one project.

Methods

list(project_id: str) -> tuple[list[ProjectFile], list[ProjectFolder]]#

Files and the directories containing them.

Returned as a pair rather than one flattened list: a directory is not a file, and collapsing them would make an empty folder indistinguishable from a missing one.

Returns: tuple[list[ProjectFile], list[ProjectFolder]] — see ProjectFile, ProjectFolder

Raises:

• CaliberAPIError
• CaliberTransportError

upload(project_id: str, *, filename: str, content: bytes | BinaryIO, path: str | None = None, kind: str = 'input', media_type: str | None = None) -> ProjectFile#

Upload a file. Multipart, so it does not go through the JSON path.

Returns: ProjectFile

Raises:

• CaliberAPIError
• CaliberTransportError

create_folder(project_id: str, path: str) -> ProjectFolder#

Operate on the project files and folders surface with the supplied arguments and return the server response.

Returns: ProjectFolder

Raises:

• CaliberAPIError
• CaliberTransportError

delete(project_id: str, file_id: str) -> bool#

Delete a record on the project files and folders surface and return the server acknowledgement. Validation and permission failures are surfaced through the standard CALIBER error hierarchy.

Returns: bool

Raises:

• CaliberAPIError
• CaliberTransportError

download(project_id: str, file_id: str) -> bytes#

Raw bytes. Not JSON, so it bypasses the envelope entirely.

Returns: bytes

Raises:

• CaliberAPIError
• CaliberTransportError

ProjectSourceAPI#

class ProjectSourceAPI()

A project's Git-backed source-control binding (P6-B).

Every mutation is optimistic-concurrency-checked with an `If-Match etag, mirroring the server's own contract: a stale write 412s rather than silently overwriting a change another caller just made. Read the current binding with :meth:get, pass its .source.etag back as if_match`.

Methods

get(project_id: str) -> WorkspaceSourceState#

Fetch one record from the project source surface identified by project_id.

Returns: WorkspaceSourceState

Raises:

• CaliberAPIError
• CaliberTransportError

configure(project_id: str, *, provider: str, provider_host: str, canonical_repository_id: str, display_path: str, default_branch: str = 'main', root_path: str = '', manifest_path: str = '.caliber/workspace.yaml', import_mode: str = 'push', connection_ref: str | None = None, if_match: str | None = None) -> WorkspaceSourceState#

Bind or replace this project's source-of-truth repository.

`if_match must be omitted the first time a project has no source configured yet, and must carry the existing binding's etag to replace one that already exists -- passing one when there is nothing to match, or omitting it when there is, both 412. Replacing an existing binding also requires it to be disabled first (:meth:disable`).

Returns: WorkspaceSourceState

Raises:

• CaliberAPIError
• CaliberTransportError

enable(project_id: str, *, if_match: str) -> WorkspaceSourceState#

Verify the binding against its provider and make it importable.

Each transition method calls its own literal path (rather than sharing one helper parameterized on the action) so `docs-site/sdk_coverage.py's static source-text scan -- which matches a literal f"...". after self._post(`, not a runtime-built path -- can see it as covered.

Returns: WorkspaceSourceState

Raises:

• CaliberAPIError
• CaliberTransportError

disable(project_id: str, *, if_match: str) -> WorkspaceSourceState#

Operate on the project source surface with the supplied arguments and return the server response.

Returns: WorkspaceSourceState

Raises:

• CaliberAPIError
• CaliberTransportError

reconcile(project_id: str, *, if_match: str) -> WorkspaceSourceState#

Re-verify an already-enabled binding against its provider.

Returns: WorkspaceSourceState

Raises:

• CaliberAPIError
• CaliberTransportError

capabilities(project_id: str) -> WorkspaceSourceCapabilities#

What the bound provider supports, without needing credentials.

Returns: WorkspaceSourceCapabilities

Raises:

• CaliberAPIError
• CaliberTransportError

ProjectImportsAPI#

class ProjectImportsAPI()

Durable source-to-revision import jobs for one project (P6-B).

Usage example

def connect_github_source_and_import_on_push(
    caliber: CaliberClient,
    *,
    project_id: str = "PRJ-1",
    repository: str = "octo-org/mortgage-underwriting",
    commit_sha: str = "a" * 40,
    bundle: bytes = b"PK\x05\x06" + b"\x00" * 18,  # minimal empty-ZIP end-of-central-directory

Methods

list(project_id: str, *, status: str | None = None, limit: int | None = None, cursor: str | None = None) -> CursorPage[WorkspaceImportJob]#

Return the current collection of project imports, applying any supported filters.

Returns: CursorPage[WorkspaceImportJob]

Raises:

• CaliberAPIError
• CaliberTransportError

get(project_id: str, job_id: str) -> WorkspaceImportJob#

Fetch one record from the project imports surface identified by project_id.

Returns: WorkspaceImportJob

Raises:

• CaliberAPIError
• CaliberTransportError

create(project_id: str, *, repository: str, commit_sha: str, bundle: bytes | BinaryIO, idempotency_key: str, filename: str = 'bundle') -> WorkspaceImportJob#

Start an import. Multipart, so it does not go through the JSON path.

`idempotency_key` has no default on purpose: the server replays a prior job for a reused key rather than starting a second one, so generating a fresh key on every call here would silently defeat that retry-safety guarantee. Reuse the same key across a retry of the same logical import; the server compares content digests and rejects a key reused for genuinely different content.

Returns: WorkspaceImportJob

Raises:

• CaliberAPIError
• CaliberTransportError

reconcile(project_id: str, job_id: str) -> WorkspaceImportReconciliation#

Explicitly observe an import stuck in `reconcile_required`.

Returns: WorkspaceImportReconciliation

Raises:

• CaliberAPIError
• CaliberTransportError

wait(project_id: str, job_id: str, *, timeout: float = 900.0, **options) -> WorkspaceImportJob#

Poll until the import reaches a terminal state.

`reconcile_required counts as terminal here -- it will never advance on its own, so a waiter that only accepted succeeded/ failed would block until timeout on the one outcome that needs a caller to act (:meth:reconcile`), not wait longer.

Returns: WorkspaceImportJob

Raises:

• CaliberAPIError
• CaliberTransportError
• WaitFailed
• WaitTimeout

ProjectRevisionsAPI#

class ProjectRevisionsAPI()

Immutable, reviewable Workspace revisions for one project (P6-B).

Methods

list(project_id: str, *, status: str | None = None, limit: int | None = None, cursor: str | None = None) -> CursorPage[WorkspaceRevision]#

Return the current collection of project revisions, applying any supported filters.

Returns: CursorPage[WorkspaceRevision]

Raises:

• CaliberAPIError
• CaliberTransportError

get(project_id: str, revision_id: str) -> WorkspaceRevision#

Fetch one record from the project revisions surface identified by project_id.

Returns: WorkspaceRevision

Raises:

• CaliberAPIError
• CaliberTransportError

diff(project_id: str, revision_id: str, *, base: str) -> WorkspaceRevisionDiff#

The deterministic pin-level difference from `base to revision_id`.

Returns: WorkspaceRevisionDiff

Raises:

• CaliberAPIError
• CaliberTransportError

snapshot(project_id: str, *, resources: Sequence[dict[str, Any]]) -> WorkspaceRevision#

Pin an explicit list of live CALIBER resource versions into a new, immutable, source-less ("managed") revision (P4-B/P4-C).

Unlike a Git-backed import, this never resolves "current" for you -- each entry in `resources names an exact {"resource_type": ..., "resource_id": ..., "version_ref": ...} pin (logical_name/purpose are optional), so the same request always produces the same content. A resource type with no registered adapter, or whose adapter does not yet support managed snapshotting, is refused (409) rather than silently skipped -- today that's only "prompt"`.

Idempotent by content: retrying with the same `resources list returns the already-created revision instead of a duplicate (the resource list's own digest becomes the revision's revision_sha256`, deduplicated server-side), so no separate idempotency key is needed.

Returns: WorkspaceRevision

Raises:

• CaliberAPIError
• CaliberTransportError

ProjectChangeRequestsAPI#

class ProjectChangeRequestsAPI()

The Change Request review lifecycle for one project (P6-B).

A Change Request proposes a ready revision for review and promotes it through a fixed status machine (`draft -> open -> ... -> accepted/closed). Mutations that touch a specific version of the request (update_head/rebase/close/assign_reviewer/ remove_reviewer) take expected_lock_version rather than an If-Match header -- that is the server's own optimistic-concurrency field here (from a prior get()/list() call's .lock_version), unlike :class:ProjectSourceAPI`'s etag.

Usage example

def promote_a_reviewed_revision(
    caliber: CaliberClient,
    *,
    project_id: str = "PRJ-1",
    revision_id: str = "WSR-1",
    environment_id: str = "development",

Methods

list(project_id: str, *, status: str | None = None, created_by: str | None = None, reviewer_user_id: str | None = None, semantic_version: str | None = None, limit: int | None = None, cursor: str | None = None) -> CursorPage[WorkspaceChangeRequest]#

Return the current collection of project change requests, applying any supported filters.

Returns: CursorPage[WorkspaceChangeRequest]

Raises:

• CaliberAPIError
• CaliberTransportError

get(project_id: str, change_request_id: str) -> WorkspaceChangeRequest#

Fetch one record from the project change requests surface identified by project_id.

Returns: WorkspaceChangeRequest

Raises:

• CaliberAPIError
• CaliberTransportError

create(project_id: str, *, title: str, head_revision_id: str, semantic_version: str, description: str = '', base_revision_id: str | None = None, review_backend: str = 'caliber', reviewer_user_ids: Sequence[str] | None = None) -> WorkspaceChangeRequest#

Open a draft Change Request over a ready revision.

Stays `draft until :meth:submit -- creating one does not by itself start review or claim semantic_version`.

Returns: WorkspaceChangeRequest

Raises:

• CaliberAPIError
• CaliberTransportError

submit(project_id: str, change_request_id: str, *, idempotency_key: str | None = None) -> WorkspaceChangeRequest#

Move a draft to `open, reserving its semantic_version` claim.

Returns: WorkspaceChangeRequest

Raises:

• CaliberAPIError
• CaliberTransportError

update_head(project_id: str, change_request_id: str, *, revision_id: str, expected_lock_version: int, change_summary: str = '') -> WorkspaceChangeRequest#

Append a new ready revision as the request's next head generation.

Returns: WorkspaceChangeRequest

Raises:

• CaliberAPIError
• CaliberTransportError

rebase(project_id: str, change_request_id: str, *, revision_id: str, expected_lock_version: int, change_summary: str = '', semantic_version: str | None = None) -> WorkspaceChangeRequest#

Bring an `out_of_date` request back onto the current accepted head.

Returns: WorkspaceChangeRequest

Raises:

• CaliberAPIError
• CaliberTransportError

close(project_id: str, change_request_id: str, *, reason: str, expected_lock_version: int) -> WorkspaceChangeRequest#

Close the underlying HTTP client or transport owned by this object.

Returns: WorkspaceChangeRequest

Raises:

• CaliberAPIError
• CaliberTransportError

accept(project_id: str, change_request_id: str) -> WorkspaceChangeRequest#

Accept a Change Request, advancing the project's accepted revision.

Takes no QA-evidence argument by design: the server derives it itself from a durably recorded QA go decision bound to the request's current head (see `caliber.routes.workspace_change_requests's own docstring on the server side) rather than trusting anything this client could send. A 409` means either no qualifying QA decision exists yet for the current head, or a concurrent acceptance already advanced the project's accepted revision out from under this request.

Returns: WorkspaceChangeRequest

Raises:

• CaliberAPIError
• CaliberTransportError

list_comments(project_id: str, change_request_id: str, *, limit: int | None = None, cursor: str | None = None) -> CursorPage[WorkspaceChangeRequestComment]#

Operate on the project change requests surface with the supplied arguments and return the server response.

Returns: CursorPage[WorkspaceChangeRequestComment]

Raises:

• CaliberAPIError
• CaliberTransportError

add_comment(project_id: str, change_request_id: str, *, body: str, head_id: str | None = None, resource_type: str | None = None, resource_name: str | None = None, source_path: str | None = None) -> WorkspaceChangeRequestComment#

Add a comment, optionally anchored to a specific head/resource/path.

Returns: WorkspaceChangeRequestComment

Raises:

• CaliberAPIError
• CaliberTransportError

list_reviewers(project_id: str, change_request_id: str, *, limit: int | None = None, cursor: str | None = None) -> CursorPage[WorkspaceChangeRequestReviewer]#

Operate on the project change requests surface with the supplied arguments and return the server response.

Returns: CursorPage[WorkspaceChangeRequestReviewer]

Raises:

• CaliberAPIError
• CaliberTransportError

assign_reviewer(project_id: str, change_request_id: str, user_id: str, *, expected_lock_version: int) -> WorkspaceChangeRequestReviewer#

Operate on the project change requests surface with the supplied arguments and return the server response.

Returns: WorkspaceChangeRequestReviewer

Raises:

• CaliberAPIError
• CaliberTransportError

remove_reviewer(project_id: str, change_request_id: str, user_id: str, *, expected_lock_version: int) -> WorkspaceChangeRequest#

Deactivate a reviewer. Returns the Change Request, not the reviewer row -- `active_reviewer_count` is the reason a caller would check.

Returns: WorkspaceChangeRequest

Raises:

• CaliberAPIError
• CaliberTransportError

list_reviews(project_id: str, change_request_id: str, *, limit: int | None = None, cursor: str | None = None) -> CursorPage[WorkspaceChangeRequestReview]#

Operate on the project change requests surface with the supplied arguments and return the server response.

Returns: CursorPage[WorkspaceChangeRequestReview]

Raises:

• CaliberAPIError
• CaliberTransportError

submit_review(project_id: str, change_request_id: str, *, head_id: str, decision: str, rationale: str = '') -> WorkspaceChangeRequestReview#

Record one reviewer's decision against a specific head.

`decision is "approve" or "request_changes"`; passed through rather than a stricter type so a server that adds a third decision is still reachable without an SDK release.

Returns: WorkspaceChangeRequestReview

Raises:

• CaliberAPIError
• CaliberTransportError

list_attestations(project_id: str, change_request_id: str, *, limit: int | None = None, cursor: str | None = None) -> CursorPage[WorkspaceExternalReviewAttestation]#

Operate on the project change requests surface with the supplied arguments and return the server response.

Returns: CursorPage[WorkspaceExternalReviewAttestation]

Raises:

• CaliberAPIError
• CaliberTransportError

refresh_external_review(project_id: str, change_request_id: str) -> None#

Queue a re-check of this request's external (e.g. GitHub PR) review state.

Fire-and-forget: the server responds `202` with no resource to decode, so there is nothing meaningful to return.

Returns: None

Raises:

• CaliberAPIError
• CaliberTransportError

list_checks(project_id: str, change_request_id: str, *, limit: int | None = None, cursor: str | None = None) -> CursorPage[WorkspaceChangeRequestCheck]#

Operate on the project change requests surface with the supplied arguments and return the server response.

Returns: CursorPage[WorkspaceChangeRequestCheck]

Raises:

• CaliberAPIError
• CaliberTransportError

ProjectVersionTagsAPI#

class ProjectVersionTagsAPI()

Immutable semantic-version claims recorded against revisions (P6-B).

Methods

list(project_id: str, *, limit: int | None = None, cursor: str | None = None) -> CursorPage[WorkspaceVersionTag]#

Return the current collection of project version tags, applying any supported filters.

Returns: CursorPage[WorkspaceVersionTag]

Raises:

• CaliberAPIError
• CaliberTransportError

get(project_id: str, tag: str) -> WorkspaceVersionTag#

Fetch one record from the project version tags surface identified by project_id.

Returns: WorkspaceVersionTag

Raises:

• CaliberAPIError
• CaliberTransportError

ProjectReleaseOperationsAPI#

class ProjectReleaseOperationsAPI()

Durable apply/rollback intents against one release (P5-C).

Unlike the cursor-paginated Change-Request/import/revision families, :meth:list uses plain `limit/offset -- this resource's own immediate server-side sibling (release list/evidence/evaluations, see :class:ProjectReleasesAPI`) already established that convention for this release family, and there was no reason to introduce a third pagination style where two already coexist in shipped code.

Usage example

def promote_a_reviewed_revision(
    caliber: CaliberClient,
    *,
    project_id: str = "PRJ-1",
    revision_id: str = "WSR-1",
    environment_id: str = "development",

Methods

list(project_id: str, release_id: str, *, limit: int | None = None, offset: int | None = None) -> list[WorkspaceReleaseOperation]#

Return the current collection of project release operations, applying any supported filters.

Returns: list[WorkspaceReleaseOperation]

Raises:

• CaliberAPIError
• CaliberTransportError

get(project_id: str, release_id: str, operation_id: str) -> WorkspaceReleaseOperationResult#

Fetch one record from the project release operations surface identified by project_id.

Returns: WorkspaceReleaseOperationResult

Raises:

• CaliberAPIError
• CaliberTransportError