Decisions

Ask a decision model typed questions about a state and get typed answers.

Operation	Request
Typed decisions in OpenAI's Decisions shape	`POST /v1/decisions`
Answer typed questions about one state	`POST /v1/systemone`

Typed decisions in OpenAI's Decisions shape

POST /v1/decisions · post-v1-decisions

OpenAI's Decisions API request and response over one NIP-DEC decision (docs/api/decisions.md). openagents/decide asks our hosted Clef first, then Jev, then Vertex; clef-flash and clef ask only our hosted Clef. Keyless and free.

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
`Idempotency-Key`	header	string	No	The same key and body within 24 hours returns the first answer; another body is `409` `idempotency_conflict`.
`X-Decision-Order`	header	one of "pylon", "hosted"	No

Request body

Content type: application/json

Type: object

Response

200 — One answer per question, in request order.

Errors

Status	Meaning	Body
400	`invalid_request`, `too_many_questions`, or `too_many_options`.
404	`model_not_found`.
409	`idempotency_conflict`.
413	`limit_exceeded`.
503	No decision door could answer right now (`unavailable`).

Example

curl -X POST 'https://api.openagents.com/v1/decisions' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'

Answer typed questions about one state

POST /v1/systemone · answerSystemOne

One state, one set of typed questions, one typed answer per question. The model field names a door the credential is bound to; the gateway verifies the backend's published identity against the binding before a byte of the request is forwarded. A credential must resolve through the gateway's configured key or account store; a recognizable prefix is not authorization. With accounts enabled, user sessions require their current workspace membership. A request without a credential is allowed only by the deployment's shared-door and funding policy. Admission reserves quota before forwarding and settles one attempt with an execution receipt.

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

SystemOneBearer: An issued oak_<id>.<secret> key, or an account session supported by this gateway's account configuration. Scope, workspace membership, door binding, and funding checks remain operation-specific. Anonymous access is available only when the operation and shared-door policy allow it.

Parameters

Name	In	Type	Required	Description
`X-Workspace-Id`	header	string	No	Required for a user session when workspace membership is enforced. The gateway checks current membership and the selected door's policy.
`Idempotency-Key`	header	string	No	The request's stable identity. Retries repeat it with an incrementing `X-Attempt`; a settled pair refuses reuse, and a pair reused against different content is `409 idempotency_conflict`.
`X-Attempt`	header	integer	No	The attempt number of this request; `1` when absent.

Request body

Content type: application/json

Type: SystemOneCall

Field	Type	Required	Description
`model`	string	Yes	The door to answer through.
`questions`	object	Yes	Question id to question. Ids are for the caller and are not sent to the model.
`state`	any	Yes	The JSON or text the questions read.

Response

200 — Every question answered.

Type: SystemOneResult

Field	Type	Required	Description
`answers`	object	Yes
`model`	string	Yes	The served identity that answered.
`usage`	SystemOneUsage	No	Either field is absent when the backend does not count it.
`usage.input_tokens`	integer	No
`usage.output_tokens`	integer	No

Errors

Status	Meaning	Body
400, 401, 403, 409, 422, 503	A typed refusal — see the `error.code` table in `gateway.md`.	SystemOneTypedError
429	Rate, concurrency, or daily-quota bound. `Retry-After` accompanies `rate_limited`, `busy`, `overloaded`, and `quota_exhausted`.	SystemOneTypedError

Example

curl -X POST 'https://api.openagents.com/v1/systemone' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "string",
  "questions": {},
  "state": {}
}'