The decision API for callers

The service answers questions instead of generating text. One request
carries one state (the JSON or text under judgment) and a map of typed
questions; the response carries one typed answer per question with
probabilities. There is no streaming prose and no chat history — each call
is complete and independent.

The contract

POST /v1/systemone
Authorization: Bearer oak_<id>.<secret>
Content-Type: application/json

{
  "model": "shared-kev",
  "state": "I was charged twice on the March invoice.",
  "questions": {
    "refund": {"type": "noul", "instructions": "Does the customer ask for money back?"}
  }
}

{"model": "shared-kev", "answers": {"refund": {"type": "noul", "noul": 0.91}},
 "usage": {"input_tokens": 412, "output_tokens": 2}}

GET /v1/models lists the doors the credential may name in model. Three
question types:

• noul — probability a condition holds (noul field, 0–1).
• choice — pick one of criteria's named options (choice,
  confidence, probabilities).
• score — probability-weighted position on 2–10 ordered criteria
  levels (score, confidence, probabilities, legend).

Question ids are caller-side only — the model sees instructions and
criteria, never the id. Include a no-match option in a choice when
nothing may fit.

Refusals, retries, and identity

Errors are typed: {"error": {"code", "message"}}. Gateway-owned codes
are stable (unauthenticated, door_not_bound, invalid_request,
too_many_questions, too_many_options, idempotency_conflict,
rate_limited, busy, overloaded, quota_exhausted,
door_unavailable, identity_mismatch, unavailable); a backend may add
its own refusal codes. Treat rate_limited/busy/overloaded and 5xx
as retryable — honor Retry-After — and quota_exhausted as a daily
budget that retrying cannot fix.

Send Idempotency-Key on work you may retry and increment X-Attempt per
attempt: the service settles quota by (request, attempt), a retried
request shares one reservation, and a settled pair reused against changed
content answers 409. The x-request-id response header is the identity
to quote when reporting a call.

The CLI and the SDK

oak (cargo run -p oak) is the reference caller: oak ask --questions FILE [STATE] for one call, --input lines|ndjson for bounded batches,
--request-id for idempotent work, --select/--uncertain-below to shape
output, and stable exit codes (0 answered, 1 failure, 2 usage, 3 refused,
4 unavailable, 5 mixed). Credentials come from OPENAGENTS_API_KEY or a
0600 config file — never a flag. In Rust, crates/jev is the SDK the
CLI is built on.

What an answer does not mean

Probabilities are model judgments, not permission or proof of correctness.
Calibration must be measured on the target workload; the wire contract does
not establish it. A Noul of 0.5 expresses equal model probability for yes and no,
not an independently established frequency.
confidence describes how concentrated a distribution is. Acting on an
answer — a threshold, a routing rule, an escalation — belongs to the
caller's policy and should be measured on the caller's labelled data.

Where to read more

• docs/decision-models/guides/caller.md — the caller's guide end to end.
• docs/decision-models/service/gateway.md — the service's admission, bounds, and
  refusal codes.
• docs/decision-models/api/openapi.yaml — the machine-readable contract.
• docs/decision-models/examples/ — runnable curl and oak examples.
• docs/gym/measured-records.md — how suites, runs, and report
  commitments measure a door.