API documentation

Everything lives under a single versioned base URL:

https://roundhouseworks.com/api/v1

Requests and responses are JSON. Every resource is scoped to your organization — an API key can only ever see its own org's jobs, workers, and events. The surface is additive-only: fields may be added to responses, but nothing documented here will be renamed or removed within v1.

The native model is asynchronous — submit a job, let the router place it, fetch the result — because that is what makes deadline-aware placement possible. If you need a synchronous call today, start at the Bedrock-compatible endpoint.

Authenticate every request with an org-scoped API key (keys look like dsk_…) in the Authorization header. Each key carries one or more scopes:

Rate limits are generous — 600 requests per minute per key — and enforced with a 429 plus a Retry-After header when exceeded (see Errors).

# the only header Roundhouse needs
curl "https://api.roundhouseworks.com/api/v1/jobs" \
  -H "Authorization: Bearer dsk_your_api_key"

A submission is a payload plus three routing facts — how good the model must be, how urgent the job is, and when it must be done:

Also accepted: earliest_start_at, max_retries (0–10, default 3), and allow_overspend to let a job escalate past the org's daily cloud budget cap when it truly must run.

curl -X POST "https://api.roundhouseworks.com/api/v1/jobs" \
  -H "Authorization: Bearer dsk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
        "payload": {"prompt": "Summarize this incident report."},
        "required_capability": "tier-standard",
        "priority": 7,
        "deadline_at": "2026-08-20T18:00:00Z",
        "idempotency_key": "incident-8412",
        "tags": ["incident"]
      }'

# 201 Created (200 on idempotent replay)
{
  "id": "0198f6a2-6b1e-7c3d-9a10-3f2e8c11d204",
  "status": "pending",
  "priority": 7,
  "required_capability": "tier-standard",
  "deadline_at": "2026-08-20T18:00:00Z",
  "earliest_start_at": null,
  "idempotency_key": "incident-8412",
  "max_retries": 3,
  "attempt_count": 0,
  "retries_remaining": 3,
  "tags": ["incident"],
  "allow_overspend": false,
  "cost_estimate": "0.000000",
  "estimated_input_tokens": 0,
  "estimated_output_tokens": 0,
  "routing_decision": {},
  "error": null,
  "is_overdue": false,
  "payload_bytes": 45,
  "started_at": null,
  "finished_at": null,
  "created_at": "2026-08-20T17:12:03.412809+00:00",
  "updated_at": "2026-08-20T17:12:03.412809+00:00"
}

A job moves through a small, fully audited state machine. The router places it in one of two lanes; the escalation sweep re-checks queued local work every 30 seconds and moves at-risk jobs to the cloud lane before their deadlines slip.

• Failures retry with backoff up to max_retries, then land in dead_letter for inspection.
• held means the daily cloud budget cap was reached — the job waits for local capacity or the next budget window rather than silently overspending.
• Every transition is an event you can read on the feed or the per-job audit trail.

          ┌─▶ queued_local ─▶ leased ─▶ running ─┐
pending ──┤        │ escalation sweep (30s)     ├─▶ succeeded
          └─▶ queued_cloud ─────────▶ running ─┘

failed ──▶ retried with backoff, up to max_retries
       ──▶ dead_letter when retries are exhausted
held      — budget cap reached; waits, never overspends
cancelled — POST /api/v1/jobs/{job_id}/cancel

{"id", "type", "ts", "data"} — id is a time-ordered UUIDv7 that doubles as the cursor and the dedupe key; data carries ids and status fields only, never payload bodies. Three type families:

• job.* — every lifecycle transition, from job.created through job.succeeded, job.escalated, job.dead_lettered and friends.
• worker.status — worker lifecycle (registered, online, draining, offline), with current load for fleet gauges.
• metering.recorded — one per finished attempt, local and cloud alike. Savings ride inside this event: each carries the computed cost, the all-cloud baseline, and the difference, as decimal strings.

REST cursor feeds

• GET /api/v1/events?cursor=&types= Merged feed, poll-style
• GET /api/v1/metering/events Pre-filtered to metering, for billing exports

Pass the response's next_cursor back as cursor; the cursor is exclusive, so a polling loop yields each event exactly once. types takes a comma-separated list; limit defaults to 100, max 500.

# the envelope, flattened onto the data: line;
# the id rides the SSE id: line — that is what
# makes Last-Event-ID resume work
id: 0198f6a1-355e-7f02-8b61-77e4d90312af
event: metering.recorded
data: {"type": "metering.recorded",
  "ts": "2026-08-23T17:41:35.512276+00:00",
  "job_id": "0198f69f-b7e4-7c55-a1d0-42e9f1c88b21",
  "provider": "local", "model_id": "local-llm",
  "tokens_in": 100, "tokens_out": 200,
  "computed_cost": "0.000000",
  "cloud_baseline_cost": "0.014400",
  "savings": "0.014400"}

The same envelopes, pushed. Connect with ?cursor=<id> or a Last-Event-ID header and every newer event is replayed before the stream tails live. Mechanics you can rely on:

• Heartbeats — an SSE comment every 15 seconds of silence keeps idle connections alive through load balancers; EventSource never sees them.
• Named events — the server sets the SSE event: field, so use addEventListener('job.succeeded', …); the default onmessage never fires.
• Streams end on purpose after 1 hour — EventSource reconnects and resumes via Last-Event-ID automatically; raw clients reconnect themselves.
• 5 concurrent streams per org. The sixth connection gets a 429 (too_many_streams). Don't retry-loop it — fall back to polling /api/v1/events, which serves the identical envelopes. The dashboard itself does exactly this.
• Dedupe by id — reconnects can re-deliver events at the resume boundary; keep the last id you processed and drop anything at or below it.

const es = new EventSource('/api/v1/feed');
let lastId = null;
function handle(e) {
  // dedupe by id: UUIDv7 strings sort in time order
  if (lastId !== null && e.lastEventId <= lastId) return;
  lastId = e.lastEventId;
  const data = JSON.parse(e.data);  // flattened envelope
  console.log(data.type, data.ts, data);
}
['job.succeeded', 'job.failed', 'worker.status',
 'metering.recorded'].forEach(function (t) {
  es.addEventListener(t, handle);
});
es.onerror = function () {
  // after repeated errors: close, poll /api/v1/events
};

Every error, from every endpoint, is the same shape — a code you can switch on, a human-readable message, and an optional structured detail:

{
  "error": {
    "code": "timeout",
    "message": "The job did not finish within the
      timeout. It is still running; fetch the
      result from the jobs API.",
    "detail": {
      "job_id": "0198f6a2-6b1e-7c3d-9a10-3f2e8c11d204"
    }
  }
}