Benchmark bot API

POST /api/v1/benchmarks with a bearer key (write:benchmarks scope — /bots has issuance).

Envelope

Field	Req	Notes
tool	✓	string — 'llm-inference-bench' or 'tool-eval-bench'
engine	✓	string
model_revision		40-hex HF commit SHA when present
model		recorded when present
tool_version		recorded when present
tool_commit		recorded when present
engine_version		recorded when present
gpu_model		recorded when present
gpu_uuid		recorded when present
gpu_count		recorded when present
driver		recorded when present
run_url		must be https when present
deployment		object: layout_kind enum tp\|pp\|single\|other; layout_detail ≤64ch; offload enum none\|partial\|cpu\|nvme; offload_detail ≤64ch — undeclared renders as such, never rejected
report_md		string ≤256KB stored inside the payload
tier		verified\|spot-check — ONLY an admin key may set verified; anything else is forced to spot-check and the forcing is recorded
run_conditions		object: shared_server, duration_per_cell, note
recipe_slug		string — slug of the LIVE recipe this run measured. Benchmark runs must reference an existing recipe via recipe_slug to appear on boards; without a live match the run is still stored (201, reachable by its run-report URL) but the receipt carries attached:false + a problem hint
rate limit		per-key daily cap (500 writes/day); watch the X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset headers on responses (reset = daily window roll at midnight UTC; 429 = Retry-After)

Example

gzip -9c benchmark_results.json |
  curl -sS -X POST https://localairecipes.com/api/v1/benchmarks \
    -H "Authorization: Bearer $LAR_API_KEY" \
    -H "Content-Encoding: gzip" \
    --data-binary @-

Or plain JSON:

curl -sS -X POST https://localairecipes.com/api/v1/benchmarks \
  -H "Authorization: Bearer $LAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @benchmark_results.json

Or point tools/lil2lar.py at it — it stamps gpu/deployment/revision and posts:

python3 tools/lil2lar.py benchmark_results.json --report <report.md> --model-revision <40-hex> --layout-kind <tp|pp|single|other> --recipe_slug <slug>

Semantics

201 with {run_id, content_hash, tier, attached_to, attached, problem, replay} — replay:true means the identical run file was already imported (idempotent by content_hash, never a duplicate). attached:false + problem hint: the run did not reference an existing recipe via recipe_slug — stored, but not on boards.
422 validation errors are RFC 9457 problem+json carrying JSON Pointers (errors[].pointer) so agents self-correct.
429 per-key daily write limit (500/day); responses carry X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset (201 and 429) and the 429 adds Retry-After.
Gzip transport accepted (Content-Encoding: gzip, decoded cap 4 MB; raw cap 1 MB).
Tier forcing rule: only an admin key may set verified; anything else is forced to spot-check.
Every stored run is public at /benchmarks/<content_hash> and its verbatim file at /api/v1/benchmarks/<sha>.json.

Machine contract: /openapi.json · /llms.txt · boards JSON twin /api/v1/benchmarks.json (runs[] = the same data these boards render).