API & SDK specification
The original contract chapter, generated from the Arbiro engineering handbook.
| Route | Wire contract |
|---|---|
| POST /v1/decisions | OpenAI SDK base URL ends in /v1. Forward input, model and questions. Preserve ordered answers, probabilities, usage, refusals and the OpenAI error envelope. |
| POST /v1/systemone GET /v1/models | TypeSafe SDK base URL is the origin. Preserve state, question IDs, choice/score/noul fields, model discovery and TypeSafe errors. Pass through supported vendor-specific inputs in direct mode. |
| POST /v1/decide | Accept state, named questions, a policy or direct model and optional correlation/retry keys. Return an answers map keyed by question ID or 202 with a status URL. |
| GET /v1/decisions/{id} | Tenant-scoped audit lookup and current review status. List and filter separately with GET /v1/decisions?external_id=… and an opaque pagination cursor. |
A native request and its result
POST /v1/decide
{"policy":"default-cascade@v1","external_id":"case_42",
"state":["copper","aluminum"],"questions":{"both_metals":{
"type":"noul","instructions":"Are both materials metals?"}}}
200 {"decision_id":"dec_81","status":"completed","branch":"answer_j",
"answers":{"both_metals":{"type":"noul","noul":0.96}},
"cost_usd":0.000042,"arbiro_charge_usd":0.045,"payer":"customer"}On vendor routes, accept the arbiro extension object or X-Arbiro-Policy, X-Arbiro-External-Id and Idempotency-Key headers. On the native route accept these fields at the top level. Resolve each field from body, then header. Apply an account policy default only if no explicit native model was supplied. Strip extensions before forwarding vendor calls.
Policy mode on a vendor route
Validate question types and required response fields against every reachable adapter before spending. Direct mode preserves vendor capabilities. A policy forwards the full question set at each model node, validates the complete result and returns one terminal answer map. Bill once per provider call.
Day one supports synchronous decision requests. Streaming, batch inference, chat routing and general workflow actions are outside the release scope.
OpenAI Decisions reference · TypeSafe primitives
Caller-defined questions
The caller owns the task. A policy version can be reused with different subjects, state shapes and question names. Validate this boundary before reserving spend.
TypeSafe-compatible direct call
POST /v1/systemone
{"model":"jev-latest","state":{"message":"Moved to Friday."},
"questions":{
"topic":{"type":"choice","instructions":"Classify the message.",
"criteria":{"schedule":"Timing or dates","other":"Other"}},
"mentions_date":{"type":"noul",
"instructions":"Does the text mention a day or date?"}}}
200 {"model":"jev-latest","answers":{
"topic":{"type":"choice","choice":"schedule","confidence":0.84,
"probabilities":{"schedule":0.94,"other":0.06}},
"mentions_date":{"type":"noul","noul":0.98}},
"usage":{"input_tokens":74,"output_tokens":0}}Accept a string, JSON object or array as state. Reject a missing state, other root scalar, empty question map or malformed definition with a field path. Each question has a name and instructions. Choice criteria map stable option IDs to descriptions. Score criteria preserve the ordered scale. Noul reports a probability. Direct Jev supports box and assets under its documented image flag.
Policy admission
Resolve the selected policy, compile a reversible mapping for every reachable model and pin the request definitions by digest. If any adapter cannot represent a question, its scale or its required outputs, return 400 unsupported_question_type or unsupported_mapping before inference. Return all named answers from the selected observation. A human handoff has its own status and task ID.
TypeSafe System One request and response reference
Native response and retry contract
POST /v1/decide requires state and a nonempty questions object. Supply a direct model or resolve a policy from the request or account default. Reject conflicting explicit model and policy selectors. The request defines the question IDs, instructions and criteria. The policy selects the providers and route.
| HTTP result | Client behavior and server guarantee |
|---|---|
| 200 completed | Return decision_id, status, answers, branch, cost_usd (model cost), arbiro_charge_usd (wallet debit) and payer (model funding source). Show the service fee separately. The audit identifies the actor and each settled model step. |
| 202 running / review_pending | Return decision_id, status and a Location header pointing to the audit record. A running duplicate receives Retry-After: 1. A pending human review has review_task_id and no final answer. Poll the audit resource. |
| 400 / 401 / 403 / 404 | Reject malformed JSON or an invalid contract before dispatch. Missing/invalid credentials yield 401, insufficient scope yields 403. Unknown or cross-tenant resource IDs yield the same 404. |
| 409 / 412 | On a reused key with different normalized input, return idempotency_conflict. A stale If-Match on an edit or resolution returns 412 with the current revision. An already-resolved task cannot accept a second resolution. |
| 402 / 429 / 503 | Return 402 insufficient_credits when posted prepaid funds are zero or negative, or available funds cannot cover a new hold. Enterprise limit exhaustion returns 402 credit_limit_exceeded. Rate limits return 429. An ambiguous dispatch returns 503 with its decision ID. Preserve vendor error envelopes. |
Idempotency and polling
Scope the key by tenant and route. HMAC canonical JSON covering state, named question definitions, ordered criteria, assets, explicit model or policy, vendor flags and external_id. Reject duplicate keys. Preserve array order. Omit transport headers and the retry key. Resolve defaults after claim and retain the HMAC key version.
Persist the first committed terminal submission response, including a 202 review handoff. Repeating that POST returns that snapshot, even after a reviewer resolves it. GET /v1/decisions/{id} returns the latest status and event cursor. A provisional “running” response to a concurrent caller is never cached as the terminal snapshot.
202 Location: /v1/decisions/dec_81
{"decision_id":"dec_81","status":"review_pending",
"review_task_id":"rev_9","branch":"review"}The table defines the native route. A vendor route preserves its own status and error envelope for upstream errors. Use its documented review_pending extension on review handoff, and retain the decision-ID header on post-admission failures.
Canonical JSON serialization · RFC 8785
Control plane contracts
Return opaque IDs and UTC timestamps. Require a tenant-scoped principal. Read-only access covers audit and replay reports, reviewer scope covers review actions, editor scope covers policy changes, and admin scope covers credentials and spend settings.
| Endpoint | Success, concurrency and failure contract |
|---|---|
| PUT /v1/policies/{name}/draft | Accept schema_version, entry, nodes and layout. If-Match carries the last draft revision. For a new draft use If-None-Match: *. Return 200/201 with revision, executable_hash and validation diagnostics by node ID and field path. |
| POST /v1/policies/{name}/versions | Accept draft_revision, executable_hash and optional replay_id. Lock the policy row and verify the draft still matches. If replay_id is supplied, verify tenant, draft hash and cohort. Insert version and update the alias atomically. Return 201 with version_id. |
| POST /v1/replays | Accept baseline_version_id, candidate_hash, cohort_id and backfill mode (off by default). Return 202 with run_id and status URL. An enabled backfill also needs a payer, a bounded budget and retained or resupplied state. |
| GET /v1/replays/{id} | Return status, frozen manifest, processed/total counts and comparable/unresolved counts. A cancelled run returns partial counts with complete=false. GET /v1/replays/{id}/rows pages through changed and unresolved cases. |
| POST /v1/reviews/{id}/resolve | Submit a complete answers map and reason with If-Match. Lock the task, validate keys, types and values against the original definitions, append the human event and advance the projection. Return the new revision. |
| POST /v1/decisions/{id}/labels | Append question key, definition fingerprint, source, outcome type, value, actor and effective_at. A correction references its predecessor in the same tenant, decision and question. A frozen replay retains the original revision. |
Lists, exports and long-running operations
For the decision log, order by (created_at, decision_id) descending and seek after the last tuple. Bind the opaque cursor to tenant, filters and order. For an audit export, freeze an upper watermark at job creation, stream rows in bounded pages and return an expiring, tenant-authorized download. Deduplicate async creation with the request key and normalized payload hash.
Changing an active alias, starting a paid backfill and buying credits require separate permissions. Return field-level validation failures before starting a job. Surface a job failure with a stable reason code and the last successful checkpoint.