Models and balance

The models you can call and the balance your calls draw on.

Operation	Request
Read the caller's workspace account position	`GET /v1/balance`
List the caller's doors	`GET /v1/models`

Read the caller's workspace account position

GET /v1/balance · get-v1-balance

The workspace's exact monetary position — credited, reserved, settled, refunded, available, and remaining authorized spend — plus the price versions the configured doors charge under. A caller can only ever read a workspace it belongs to. There is no top-up, payment, or credit mutation over HTTP.

Sign-in: a bearer credential in the Authorization header.

bearer: An issued key: oak_<id>.<secret>. Omitted entirely for anonymous access to shared doors, which a require_workspace_membership deployment refuses outright.

Parameters

Name	In	Type	Required	Description
`X-Workspace-Id`	header	string	Yes	The workspace account the read is scoped to.

Response

200 — The account position and configured door prices.

Type: Balance

Field	Type	Required
`workspace`	string	Yes
`balance`	object	Yes
`balance.currency`	string	No
`balance.credited`	integer	No
`balance.reserved`	integer	No
`balance.settled`	integer	No
`balance.refunded`	integer	No
`balance.available`	integer	No
`balance.spend_remaining`	integer	No
`prices`	object	Yes

Errors

Status	Meaning	Body
400, 401, 403, 500, 503	A typed refusal — see the `refusal_codes` map in `docs/agents/api-catalog.json` and the code table in `docs/decision-models/service/gateway.md`.	TypedError
404	`account_missing` — the workspace holds no monetary account.	TypedError

Example

curl 'https://api.openagents.com/v1/balance' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \
  -H 'X-Workspace-Id: ...'

List the caller's doors

GET /v1/models · get-v1-models

The doors this credential may name in a request's model field, with the identity each is bound to. Anonymous callers see only shared doors; a tenant sees its bound doors plus the shared lane. This is the registry's claim — not a statement about backend health, and never remote attestation. A listed door can still refuse at identity check.

Sign-in: a bearer credential in the Authorization header.

bearer: An issued key: oak_<id>.<secret>. Omitted entirely for anonymous access to shared doors, which a require_workspace_membership deployment refuses outright.

Response

200 — The visible door cards.

Type: object

Field	Type	Required	Description
`models`	array of ModelCard	Yes
`models[].id`	string	Yes	The door name a request uses in `model`.
`models[].model`	string	Yes	The artifact id the binding expects the backend to publish.
`models[].artifact_signature`	string	Yes	The content digest the binding pins; empty when the binding pins a name only.
`models[].lane`	one of "shared", "dedicated", "trained", "on-device"	Yes
`models[].admission`	object	Yes
`models[].admission.scope`	array of string	No	The question families an admission record covered — trained lane only.
`models[].admission.record`	string	No	The admission record's digest — trained lane only.
`models[].admission.registry_digest`	string	No
`models[].admission.registry_sequence`	integer	No
`models[].classification`	object	Yes	The `openagents.classify-discovery.v1` card: `status` is `configured`, `unsupported`, `unavailable`, or `invalid-limits`; a configured card carries the door's declared limits, supported modes, admission ceilings, and execution shape.
`models[].decision_offer`	object	No	Optional `openagents.decision-offer-terms.v1` for the configured native offer: exact Price, usage ceiling, counter units and basis, capacity, current purchase context, payer, and settlement rules. Balance fields require balance scope. Production qualification and provider and hosting expenses remain unknown; a failed current purchase admission yields unavailable terms. See monetary-accounting.md.

Errors

Status	Meaning	Body
400, 401, 403, 500, 503	A typed refusal — see the `refusal_codes` map in `docs/agents/api-catalog.json` and the code table in `docs/decision-models/service/gateway.md`.	TypedError

Example

curl 'https://api.openagents.com/v1/models' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"