Skip to content

API reference

A forge-dashboard API client.

Every operation except :meth:health, :meth:get_version and the two webhook receivers requires an authenticated session. forge-dashboard accepts either a browser's passkey session cookie or a personal API token (Authorization: Bearer <token>, minted via POST /api/tokens) -- see the spec's auth tag. This wrapper only speaks the bearer-token half, the headless-friendly one: pass a token as api_token or set FORGE_DASHBOARD_API_TOKEN in the environment -- the constructor argument wins when both are given.

The underlying generated client is available as :attr:raw for any operation this wrapper doesn't have a dedicated method for; every generated forge_dashboard._generated.api.<tag>.<operation> module's sync_detailed/asyncio_detailed functions take it as their client argument.

raw: _GeneratedClient property

The underlying generated Client.

aget_version() -> Version async

Async counterpart of :meth:get_version.

Returns:

Type Description
Version

The running server's build version.

ahealth() -> Health async

Async counterpart of :meth:health.

Returns:

Type Description
Health

The server's health status.

get_version() -> Version

The running server's build version. Needs no session.

Returns:

Type Description
Version

The running server's build version.

health() -> Health

Liveness. Needs no session -- a good first call to prove the client reaches the server at all.

Returns:

Type Description
Health

The server's health status.

Bases: Exception

Raised for any forge-dashboard response carrying an error body.

Attributes:

Name Type Description
status_code

The HTTP status code.

message

The API's own error message (empty string if the body wasn't the documented {error} shape).

Build an :class:APIError from response, or return None if its status code isn't an error.

Decodes response.content directly rather than trusting the generated per-operation .parsed field, which is only populated for status codes the spec documents on that specific operation -- a 500 or 429 that survived every retry attempt still needs an APIError, and the API returns the same {error} shape for those too.

Usage::

response = sync_detailed(client=client.raw, ...)
if error := decode_error(response):
    raise error

Models

Generated model types returned by ForgeDashboardClient's own methods — documented here so a reference to one elsewhere on this site links to a real page instead of rendering as plain text.

Attributes:

Name Type Description
status Literal['ok']

Attributes:

Name Type Description
api_version str

The API's current major version, such as v1: the path segment the versioned operations live under. It is one value, not a list.

version str

The release tag this binary was built from, with no leading "v" — or "dev" for a build outside the release pipeline.