API Reference
Base URL: https://api.useio.xyz/v1/
All requests require the `Authorization: Bearer *** header unless noted.
Inference
POST /completions
Standard inference. Returns a completion with a signed receipt.
{"model":"auto","messages":[{"role":"user","content":"hello"}],"temperature":0.7}POST /stream
SSE token streaming. Same request body as /completions.
Returns text/event-stream with data: frames. Final frame includes the receipt.
POST /broadcast
Send the same prompt to multiple models simultaneously. Returns an array of completions, each with its own receipt.
{"models":["dolphin","deepseek","qwen"],"messages":[{"role":"user","content":"what do you disagree on?"}]}POST /diffuse
Broadcast + merge. All models respond, then IO synthesizes unique insights into one answer with per-model attribution.
POST /batch
Parallel completions, up to 50 at once. Returns all results + total time.
{"model":"auto","prompts":["question 1","question 2","question 3"]}POST /diff
Compare two models side-by-side. Returns divergence score + key differences.
{"model_a":"dolphin","model_b":"deepseek","messages":[{"role":"user","content":"explain consciousness"}]}Receipts
POST /verify-receipt
Validate a single receipt's Ed25519 signature.
{"receipt":{"receipt_id":"io-rcpt-...","signature":"ed25519:..."}}POST /receipt-chain
Link multiple receipts into a tamper-proof Merkle chain.
{"receipts":["io-rcpt-abc","io-rcpt-def","io-rcpt-ghi"]}POST /chain-verify
Validate the integrity of an entire receipt chain. Finds broken links.
POST /proof
Generate a PDF + QR code proof certificate. Third-party verifiable against the IO public key.
Privacy
POST /redact
Strip PII (wallets, emails, phones, API keys) before the model sees the prompt. Returns redacted text + redaction report.
{"text":"Send 1 SOL to 0x1234... and email me at user@example.com"}POST /timer
Set a self-destruct timer for the current session.
{"duration":"5m"}Durations: 1m, 5m, 1h, 24h, flash (tab close).
POST /wipe
Destroy the current session immediately. No recovery.
Fork & Merge
POST /fork
Split a conversation at a specific message. Creates two independent branches.
POST /merge
Combine two branches with a conflict summary.
System
| Method | Endpoint | Description |
|---|---|---|
| GET | /models | Available models + pricing |
| GET | /canary | Warrant canary status (alive: true = no secret orders) |
| GET | /health | Backend health + uptime |
| GET | /ping | Lightweight latency check |
| GET | /version | Protocol + API version |
| GET | /audit | Paginated audit log (no PII) |
Errors
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | Malformed body or missing model |
| 401 | unauthorized | Missing or invalid API key |
| 429 | rate_limited | Token bucket exhausted. Retry-After header set |
| 500 | internal_error | Inference backend error |
| 502 | model_unavailable | Requested model is down or loading |
All errors return:
{"error":{"code":"rate_limited","message":"Too many requests","retry_after":2}}