Sessions & operations

Budget sessions, API keys, orders, credits, and resumable streams.

Owner

Developer Experience

Version

api-2026.07

Verified

2026-07-13

Operations are the controls around inference: give an agent a bounded budget, issue a revocable key, submit work for later, and recover a stream after a network interruption.

Choose an operating model

Budget sessions

A session turns a series of requests into one explicit spending envelope. There is no create endpoint: the first completions call that carries routing.session_id opens the session, and its x402 authorization funds the budget. The router returns a session token in the x-session-token header; send it on subsequent calls and the remaining balance is exposed in response headers. Close the session when the workflow ends so the final settlement is explicit.

const session = omnious.session({
  model: "auto",
  budgetUsd: 1,
});

const answer = await session.ask("Summarize the latest market move.");
console.log(answer.content);
console.log(session.remainingUsd());

Durable tasks

A durable task moves execution truth out of a special UI and into the router. The normal chat and SDK share one ordered event log, renewable worker lease, latest checkpoint, verification gate, and write-ahead effect receipts. If a worker disappears after starting an external write, the next worker sees an unresolved effect and blocks for reconciliation instead of guessing and submitting it twice.

const { task, result } = await omnious.runTask({
  goal: "Implement the change, run the tests, and verify the result",
  maxSteps: 100,
  maxBudgetUsdc: 2_000_000,
  retentionHours: 24 * 7,
}, { model: "auto", tools: true, maxToolRounds: 100 });

// Store this capability in your secret store. A replacement worker can
// reconstruct the handle and continue from the latest checkpoint.
console.log(task.id, task.token, result.content);

World-class harness behavior comes from separating execution from acceptance. Criteria are immutable once installed. Completion requires a router-produced verification record derived from durable events, exactly-once effects, resolved approvals, budget counters, and the latest content-addressed workspace. A client-authoredverification.passed event cannot satisfy a task that has an acceptance contract.

# Freeze success criteria before execution
omnious task acceptance task_... --token tsk_... --file acceptance.json

# Persist/fork the runnable artifact, then grade durable outcomes
omnious task snapshot task_... --token tsk_... --file workspace.json
omnious task verify task_... --token tsk_... --result-file result.json
omnious task trace task_... --token tsk_... --otlp

Subjective criteria use a separately authenticated evaluator identity; the task owner cannot submit its own review. Evaluation runs grade capability, crash recovery, prompt-injection resistance, financial approvals, source grounding, context resolution, semantic retry control, answer shape, bounded cost, and termination. The offline optimizer sweeps explicit policy candidates over redacted trace metrics; it never changes a live customer turn. Trial records retain assertions and metrics rather than private prompts.

Task capabilities are returned once and stored only as hashes by the router. The default retention window is seven days (configurable from one hour to 30 days); DELETE /v1/tasks/:id removes the run, events, checkpoints, effects, and approvals immediately.

API keys for services

Create a spend-capable key for controlled, unattended workloads. Fund the wallet's credits once, give each service its own label and budget, and send that key as x-credit-key. Each request is then one call; the router reserves the worst case and captures metered actuals. Never put a credit key in browser code, a mobile bundle, or a public repository. A normal x-api-key is attribution-only.

# Create a key after signing the request with the keys wallet
curl -X POST "$ROUTER_URL/v1/keys" \
  -H "x-keys-wallet: $WALLET" \
  -H "x-keys-sig: $SIGNATURE" \
  -H "content-type: application/json" \
  -d '{"label":"production-agent","budget_usdc":"50"}'

# Use the returned key on a request
curl "$ROUTER_URL/v1/keys/usage" \
  -H "x-api-key: $OMNIOUS_API_KEY"

Patient orders

Patient orders let the market work over a wider latency window when the request can wait.

Retries and resumable streams

• Send an Idempotency-Key when a client may retry a paid completion.
• Persist x-request-id and the payment response for support and reconciliation.
• For a dropped stream, reconnect with GET /v1/streams/:id and its x-stream-token.
• Use POST /v1/streams/:id/stop when the caller cancels; do not abandon open work.