Server-sent events
One connection, typed events, automatic reconnect in every HTTP client.
Runs behind an endpoint.
POST a task, stream its events, collect one receipt. Typed events, resumable streams, usage in every response.
curl
$ curl -N https://api.optamus.cloud/v1/runs \
-H "Authorization: Bearer $OPTAMUS_KEY" \
-d '{"task":"summarise this week's failures","limit":30}'
event: run.started {"id":"run/7c4d"}
event: step.completed {"step":"tests","passed":38}
event: run.settled {"state":"completed","patch":"…"}
usage: {"input":18422,"output":2104}Start, then stream
One POST starts a run. Subscribe to its events over server-sent events; reconnect with Last-Event-ID and nothing is lost.
- POST /v1/runs · GET /v1/runs/:id/events
- Typed events with schema versions in the payload
- Resumable streams — pick up mid-run after a drop
events
POST /v1/runs → 201 { id: "run/7c4d" }
GET /v1/runs/run/7c4d → run state + receipt
GET /v1/runs/run/7c4d/events (SSE)
event: run.started
event: step.started
event: step.completed
event: patch.ready
event: run.settledA receipt when it settles
Every run ends in exactly one of three states — completed, interrupted, failed — with a final event that carries the diff, the log location, and the usage.
- Idempotent: POST with an Idempotency-Key is safe to retry
- Usage reported on the receipt, not a separate report
- Logs retained for 30 days, exportable to your bucket
run.settled
{
"id": "run/7c4d",
"state": "completed",
"patch": "https://files.optamus.cloud/run/7c4d.patch",
"log": "https://files.optamus.cloud/run/7c4d.log",
"usage": { "input": 18422, "output": 2104 },
"settled_at": "2026-10-09T14:22:31Z"
} Details
The parts that make it production-grade.
Keys and scopes
Per-environment keys, scoped to run:create or runs:read. Rotate without downtime.
Usage in every response
Token counts and duration ride along with the receipt — no separate reconciliation.
Plain HTTP, no lock-in
Everything is a documented endpoint — nothing here is reserved for any particular client or language.
GitHub TypeScript Python
Ready when you are.
Install the desktop app or the CLI, run one command, and review the first diff.