API reference

Authentication

Two credentials, one rule each. A session cookie is a person — sign in through the UI or POST /api/login. An API key (Authorization: Bearer gw_…) is a script or another machine, minted in the cockpit and scoped:

Failed logins are throttled (delays, never lockouts), and every sign-in, refusal and key change lands in an append-only audit trail.

The project rule

Almost every route is project-scoped and the project is never implicit: pass ?project=<slug>. A missing project is a 422, not a fallback — no request can silently operate on the wrong dataset. Machine-level routes (/api/machines…, /api/overview, /healthz) take no project.

Worked examples

BASE=http://localhost:8000
AUTH="Authorization: Bearer gw_…"        # minted in the cockpit

# What is serving, and how good is it?
curl -s "$BASE/api/state?project=widgets" -H "$AUTH" | jq .served

# Add photos to the fix queue
curl -s -X POST "$BASE/api/upload?project=widgets" -H "$AUTH" \
     -F "files=@bench1.jpg" -F "files=@bench2.jpg"

# Count one image with the serving model (count + overlay URL back)
curl -s -X POST "$BASE/api/count?project=widgets" -H "$AUTH" \
     -F "image=@bench1.jpg"

# Start a training run (model × machine × card)
curl -s -X POST "$BASE/api/train?project=widgets" -H "$AUTH" \
     -H 'Content-Type: application/json' \
     -d '{"model":"yolov8n","machine":"here","epochs":250}'

The catalog — every route

Generated from the live application (app.openapi()), not written by hand — in the repo, CI fails if this table goes stale. As of v0.3.0 · 100 routes.