HTTP API (Augur server)

When the SDK streams (because AUGUR_DSN is set), it talks to the Augur server over these endpoints. You can also call them directly — they're versioned under /api/v1.

Live interactive reference is auto-generated by every running server:

• OpenAPI JSON: GET /api/v1/openapi.json
• Swagger UI: GET /api/v1/docs
• ReDoc: GET /api/v1/redoc

Authentication

Ingest endpoints — DSN bearer

Authorization: Bearer <api_key>

The api_key is the secret inside your DSN URL. One key per tenant per client; mint with augur admin dsn-issue upstream.

Read endpoints — signed session cookie

POST /api/v1/auth/login { email, password } → sets augur_session cookie. All GET /api/v1/runs[...] and GET /api/v1/connections calls require it.

Admin users can additionally set an augur_tenant_override cookie via POST /api/v1/admin/impersonate to scope reads to a different tenant.

Endpoints

Ingest (the SDK calls these)

Method	Path	Body
POST	/api/v1/runs	full manifest JSON (idempotent on run_id)
PUT	/api/v1/runs/{run_id}/trace	full trace.json document
PUT	/api/v1/runs/{run_id}/steps/{step_index}	one StepTrace record
POST	/api/v1/runs/{run_id}/events	{ events: DecisionEvent[], step_index?: number }
POST	/api/v1/runs/{run_id}/screenshots/{step_index}/{kind}	multipart form: image=@shot.png;type=image/png
POST	/api/v1/runs/{run_id}/modelio/{relpath}	full modelio record JSON; relpath is the SDK-allocated <step:04d>-<layer>-<seq>.json (or run-<layer>-<seq>.json). 403 ⇒ tenant hasn't enabled modelio capture (SDK latches off for the session)
POST	/api/v1/runs/{run_id}/logs	JSON: {text, name?, step_index?} — appends to logs/<name>.log (or logs/step-<idx>.log when step_index is set), bounded at 1 MB per file
POST	/api/v1/heartbeat	JSON: {client_id, client_name?, client_version?, capture_mode?, run_id?, last_event?}

kind ∈ {pre, post, target, diff}.

Every ingest call ALSO stamps a heartbeat under the hood — so a CUA that's actively streaming steps doesn't need a separate heartbeat tick.

Read (the viewer / a coding agent calls these)

Method	Path	Effect
POST	/api/v1/auth/login	sign in; sets cookie
POST	/api/v1/auth/logout	clear cookie
GET	/api/v1/auth/me	{ user, tenant, home_tenant, impersonating }
GET	/api/v1/runs	list runs in the active workspace
GET	/api/v1/runs/{id}/manifest.json	bundle envelope
GET	/api/v1/runs/{id}/trace.json	full session + steps
GET	/api/v1/runs/{id}/steps/{NNNN}.json	one step
GET	/api/v1/runs/{id}/events/{NNNN-or-run}.jsonl	decision events JSONL
GET	/api/v1/runs/{id}/screenshots/{NNNN}_{pre,post,target,diff}.png	image bytes
GET	/api/v1/runs/{id}/diagnostics/findings.json	diagnostic findings
GET	/api/v1/connections	live SDK clients (last 60s)
GET	/api/v1/tenant/dsns	DSN records (no plaintext)
POST	/api/v1/tenant/dsns	mint a new DSN (plaintext returned ONCE)
GET	/api/v1/healthz	liveness; no auth

Admin (is_admin=True users only)

Method	Path	Effect
GET	/api/v1/admin/tenants	list every tenant
POST	/api/v1/admin/impersonate	set/clear the augur_tenant_override cookie

Curl reference

DSN_KEY="…your api_key…"

# Manifest (open run)
curl -X POST https://augur.example/api/v1/runs \
  -H "Authorization: Bearer $DSN_KEY" \
  -H "Content-Type: application/json" \
  -d @manifest.json

# Step
curl -X PUT https://augur.example/api/v1/runs/run_abc/steps/0 \
  -H "Authorization: Bearer $DSN_KEY" \
  -H "Content-Type: application/json" \
  -d @step.json

# Screenshot
curl -X POST https://augur.example/api/v1/runs/run_abc/screenshots/0/post \
  -H "Authorization: Bearer $DSN_KEY" \
  -F "image=@post.png;type=image/png"

# Modelio record (one model call's full input + output, live)
curl -X POST https://augur.example/api/v1/runs/run_abc/modelio/0003-planner-0.json \
  -H "Authorization: Bearer $DSN_KEY" \
  -H "Content-Type: application/json" \
  -d @modelio-0003-planner-0.json

# Log chunk (appended; routes to logs/step-3.log because step_index is set)
curl -X POST https://augur.example/api/v1/runs/run_abc/logs \
  -H "Authorization: Bearer $DSN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "retrying after verifier failure\n", "step_index": 3}'

# Bare heartbeat (keep the connection badge green between events)
curl -X POST https://augur.example/api/v1/heartbeat \
  -H "Authorization: Bearer $DSN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"client_id": "my_client", "client_name": "myagent"}'

Errors

Standard FastAPI shape: { "detail": "<message>" }.

Status	Meaning
401	Missing or invalid credential
403	DSN api_key not recognised; OR non-admin hit admin route
404	Path / file not present
415	Wrong content-type (e.g. non-PNG to /screenshots/*)
422	Payload failed schema validation
5xx	Server bug — file an issue with debug_session_id

Versioning

/v1 is the current path. Breaking changes will bump to /v2; additive changes will not. The JSON Schemas at <bundle>/schema/*.schema.json have their own schema_version field — see ../concepts/bundle-layout.md.