{"openapi":"3.1.0","info":{"title":"Open Edge Speech Benchmark API","description":"Objective, reproducible benchmarks for local (edge) speech AI. Every read endpoint here is open and meant to be called directly by third parties (FR-12.2) -- this is the same API the web frontend and the `goesb` runner CLI both use, nothing held back for internal use only.","version":"0.0.1"},"paths":{"/leaderboards":{"get":{"tags":["leaderboards"],"summary":"List every verified result, filterable and sortable","description":"Filterable leaderboard (FR-7.1). Curated views (docs/03-roadmap.md M4)\nare just presets of these same params (e.g. \"Lowest energy\" =\n`?sort=energy_wh&order=asc`) — no separate mechanism, so the criteria\nbehind any view is always visible in the URL (governance.md's\nmechanical-not-discretionary curation principle).\n\nADR-0009 adds two more mechanical-filter families, same principle:\n`?param.beam_size=8` (an exact-value facet on a profile-declared\noverridable parameter — `document.parameters.<key>.value`) and\n`?min_<metric>=N` / `?max_<metric>=N` (inclusive threshold filters on\nany metric id a loaded profile actually declares, e.g.\n`?max_wer=10&sort=real_time_factor` = \"fastest with WER <= 10%\").\nNeither hides or de-ranks non-default-parameter rows — ADR-0009 §4\nexplicitly rejected that; the platform's job is to make the true values\nvisible and filterable, never to pick a \"fair\" default view.","operationId":"list_leaderboards_leaderboards_get","parameters":[{"name":"benchmark_type","in":"query","required":false,"schema":{"anyOf":[{"enum":["batch","streaming","concurrency"],"type":"string"},{"type":"null"}],"description":"Restrict to one benchmark type. Omit to mix all types in one list.","title":"Benchmark Type"},"description":"Restrict to one benchmark type. Omit to mix all types in one list."},{"name":"profile","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Exact profile id, e.g. 'whisper-medium-nl-batch'.","title":"Profile"},"description":"Exact profile id, e.g. 'whisper-medium-nl-batch'."},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"BCP-47-ish language code the profile declares, e.g. 'nl-NL'.","title":"Language"},"description":"BCP-47-ish language code the profile declares, e.g. 'nl-NL'."},{"name":"pack","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pack id, e.g. 'common-voice-nl' (ADR-0011: a language can have several eligible packs).","title":"Pack"},"description":"Pack id, e.g. 'common-voice-nl' (ADR-0011: a language can have several eligible packs)."},{"name":"runtime","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Runtime/engine name, e.g. 'faster-whisper', 'whisper-cpp', 'vosk'.","title":"Runtime"},"description":"Runtime/engine name, e.g. 'faster-whisper', 'whisper-cpp', 'vosk'."},{"name":"model","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Model name as declared by the profile, e.g. 'whisper-medium'.","title":"Model"},"description":"Model name as declared by the profile, e.g. 'whisper-medium'."},{"name":"hardware","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Hardware catalog id, e.g. 'apple-m1-pro' (see GET /hardware/catalog).","title":"Hardware"},"description":"Hardware catalog id, e.g. 'apple-m1-pro' (see GET /hardware/catalog)."},{"name":"backend","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Compute backend the run actually used (ADR-0008), e.g. 'cpu', 'cuda', 'metal'.","title":"Backend"},"description":"Compute backend the run actually used (ADR-0008), e.g. 'cpu', 'cuda', 'metal'."},{"name":"max_price_eur","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Not supported — no hardware pricing data exists yet (docs/03-roadmap.md M4). Passing this returns 400 rather than silently ignoring it.","title":"Max Price Eur"},"description":"Not supported — no hardware pricing data exists yet (docs/03-roadmap.md M4). Passing this returns 400 rather than silently ignoring it."},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A metric id to sort by (e.g. energy_wh, real_time_factor, wer). Defaults to most-recently-ingested first.","title":"Sort"},"description":"A metric id to sort by (e.g. energy_wh, real_time_factor, wer). Defaults to most-recently-ingested first."},{"name":"order","in":"query","required":false,"schema":{"enum":["asc","desc"],"type":"string","description":"Sort direction when `sort` is set.","default":"asc","title":"Order"},"description":"Sort direction when `sort` is set."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Page size, 1-500.","default":100,"title":"Limit"},"description":"Page size, 1-500."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Rows to skip, for pagination alongside `limit` — see `total` in the response.","default":0,"title":"Offset"},"description":"Rows to skip, for pagination alongside `limit` — see `total` in the response."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeaderboardResponse"}}}},"400":{"description":"An unsupported or malformed filter — `max_price_eur` (never supported), an `?min_<metric>=`/`?max_<metric>=` filter for a metric id no loaded profile declares, or a non-numeric threshold value."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/answers":{"get":{"tags":["answers"],"summary":"Best verified match for a set of constraints — the decision tool","description":"The decision-tool answer (M4b, docs/04-product-direction.md).\n\nA deterministic, transparent query result — \"best match for your\nconstraints\" — never an editorial recommendation (guardrail G1): same\nstored rows always produce the same answer for the same query. Groups\nmatching results by (profile, pack, hardware), reduces each group to\nmedian metrics, and returns the group ranked best by `rank_by`. When no\nresult matches the exact constraints, relaxes one axis at a time and\nsurfaces the closest verified data plus a runner command and request\nkey for the gap (guardrail G2), rather than a dead end.","operationId":"get_answer_answers_get","parameters":[{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"BCP-47-ish language code, e.g. 'nl-NL'.","title":"Language"},"description":"BCP-47-ish language code, e.g. 'nl-NL'."},{"name":"pack","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pin one specific pack id instead of seeing every eligible pack for the language as a separate alternative (ADR-0011).","title":"Pack"},"description":"Pin one specific pack id instead of seeing every eligible pack for the language as a separate alternative (ADR-0011)."},{"name":"hardware","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A GET /hardware/catalog id, e.g. 'apple-m1-pro'.","title":"Hardware"},"description":"A GET /hardware/catalog id, e.g. 'apple-m1-pro'."},{"name":"model","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Model name as declared by the profile, e.g. 'whisper-medium'.","title":"Model"},"description":"Model name as declared by the profile, e.g. 'whisper-medium'."},{"name":"runtime","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Runtime/engine name, e.g. 'faster-whisper', 'whisper-cpp', 'vosk'.","title":"Runtime"},"description":"Runtime/engine name, e.g. 'faster-whisper', 'whisper-cpp', 'vosk'."},{"name":"benchmark_type","in":"query","required":false,"schema":{"anyOf":[{"enum":["batch","streaming","concurrency"],"type":"string"},{"type":"null"}],"description":"Restrict to one benchmark type.","title":"Benchmark Type"},"description":"Restrict to one benchmark type."},{"name":"rank_by","in":"query","required":false,"schema":{"enum":["wer","real_time_factor","energy_wh","first_final_latency"],"type":"string","description":"Which metric decides the ranking (ties broken by a fixed second metric per rank_by, see TIE_BREAKERS).","default":"wer","title":"Rank By"},"description":"Which metric decides the ranking (ties broken by a fixed second metric per rank_by, see TIE_BREAKERS)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnswerResponse"}}}},"400":{"description":"No constraints at all — at least one of language/pack/hardware/model/runtime/benchmark_type is required."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/profiles":{"get":{"tags":["profiles"],"summary":"List official benchmark profiles (what gets run)","description":"List official benchmark profiles, optionally filtered — assets are\nan in-memory dict (loaded from the committed profiles/ directory), so\nplain Python filtering, no query builder needed.","operationId":"list_profiles_profiles_get","parameters":[{"name":"benchmark_type","in":"query","required":false,"schema":{"anyOf":[{"enum":["batch","streaming","concurrency"],"type":"string"},{"type":"null"}],"description":"Restrict to one benchmark type.","title":"Benchmark Type"},"description":"Restrict to one benchmark type."},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"BCP-47-ish language code, e.g. 'nl-NL'.","title":"Language"},"description":"BCP-47-ish language code, e.g. 'nl-NL'."},{"name":"runtime","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Runtime/engine name, e.g. 'faster-whisper', 'whisper-cpp', 'vosk'.","title":"Runtime"},"description":"Runtime/engine name, e.g. 'faster-whisper', 'whisper-cpp', 'vosk'."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/profiles/{profile_id}":{"get":{"tags":["profiles"],"summary":"Get one profile's full document","description":"Get a profile by id, including version and changelog — the full\ndocument as validated against `benchmark-profile.schema.json`\n(https://github.com/taktx-io/GOESB/blob/main/runner/src/oesb_runner/schemas/benchmark-profile.schema.json)\n— returned as-is rather than a typed Pydantic model, since that schema\nis the single source of truth for a profile's shape (see schemas.py's\nown module docstring).","operationId":"get_profile_profiles__profile_id__get","parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","title":"Profile Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Profile Profiles  Profile Id  Get"}}}},"404":{"description":"No profile with this id."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/packs":{"get":{"tags":["packs"],"summary":"List official benchmark packs (the datasets)","description":"List benchmark packs, optionally filtered — assets are an in-memory\ndict (loaded from the committed packs/ directory), so plain Python\nfiltering, no query builder needed.","operationId":"list_packs_packs_get","parameters":[{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"BCP-47-ish language code, e.g. 'nl-NL'.","title":"Language"},"description":"BCP-47-ish language code, e.g. 'nl-NL'."},{"name":"visibility","in":"query","required":false,"schema":{"anyOf":[{"enum":["open","community","private"],"type":"string"},{"type":"null"}],"description":"'open' packs are the only ones eligible to back a public leaderboard result (FR-7.3).","title":"Visibility"},"description":"'open' packs are the only ones eligible to back a public leaderboard result (FR-7.3)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/packs/{pack_id}":{"get":{"tags":["packs"],"summary":"Get one pack's full document","description":"Full pack document, as validated against `benchmark-pack.schema.json`\n(https://github.com/taktx-io/GOESB/blob/main/runner/src/oesb_runner/schemas/benchmark-pack.schema.json)\n— returned as-is rather than a typed Pydantic model, since that schema\nis the single source of truth for a pack's shape (see schemas.py's own\nmodule docstring).","operationId":"get_pack_packs__pack_id__get","parameters":[{"name":"pack_id","in":"path","required":true,"schema":{"type":"string","title":"Pack Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Pack Packs  Pack Id  Get"}}}},"404":{"description":"No pack with this id."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/benchmark":{"post":{"tags":["benchmarks"],"summary":"Submit one signed benchmark result","description":"Submit a signed benchmark result for verification & ranking.\n\n`body` is a full signed result document as produced by `goesb run` +\n`goesb submit` — shaped like `benchmark-result.schema.json`\n(https://github.com/taktx-io/GOESB/blob/main/runner/src/oesb_runner/schemas/benchmark-result.schema.json),\naccepted here as a raw object rather than a typed Pydantic model since\nthat schema is the single source of truth (see schemas.py's own module\ndocstring). Its `signature.key_id` must reference a not-yet-consumed,\nnot-yet-expired token from `POST /runner-tokens` — this is not an open\nsubmission endpoint. A retry of an already-accepted `payload_sha256`\nreturns the existing row rather than re-checking (and rejecting on) an\nalready-used token.\n\nRe-verifies schema, hash, and signature (ADR-0004) and checks\nofficial-profile/open-pack membership (FR-7.3) before storing anything —\nsee ingest.py. Rejections raise HTTPException with a machine-readable\n`reason` (see the per-status-code breakdown below), never a silent\npartial acceptance.","operationId":"submit_benchmark_benchmark_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitBenchmarkResponse"}}}},"400":{"description":"Bad or already-used signing token, or a hash/signature mismatch — `detail.reason` is one of: unknown_signing_token, signing_token_already_used, signing_token_expired, hash_or_signature_invalid."},"403":{"description":"The result is well-formed and signed, but doesn't reference an official profile/open pack (FR-7.3) — `detail.reason` is one of: not_an_official_profile, profile_hash_mismatch, not_a_known_pack, pack_not_open, unknown_hardware_id."},"422":{"description":"Doesn't match `benchmark-result.schema.json`, or the submitting runner is below MIN_RUNNER_VERSION — `detail.reason` is 'schema_invalid' or 'runner_outdated'."}}}},"/benchmark/batch":{"post":{"tags":["benchmarks"],"summary":"Submit many signed results under one token","description":"Submit many signed results under ONE already-issued token (ADR-0005\nbatch variant). These batch-level failures (bad token, empty/oversized\nbatch) reject the whole call via HTTPException; once past them, a 200 is\nreturned and per-item outcomes (accepted/rejected) live in the response\nbody instead — one bad item must not fail its siblings.\n\ntokens.py's per-IP rate limit counts token *issuance*, not results\ningested — without this, a legitimate multi-result batch (the wizard's\nmulti-select submit, or any sweep across many profile/pack combos)\ncosts the same quota as submitting one result at a time. Bounded at\n`ingest.MAX_BATCH_RESULTS` results per call; a bad item never blocks its\nsiblings — each gets its own `accepted`/`detail` outcome instead of the\nwhole request failing (see `ingest.verify_and_ingest_batch`).","operationId":"submit_benchmark_batch_benchmark_batch_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchSubmitRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchSubmitResponse"}}}},"400":{"description":"Bad or already-used token — `detail.reason` is one of: unknown_signing_token, signing_token_already_used, signing_token_expired."},"422":{"description":"`results` is empty, or exceeds ingest.MAX_BATCH_RESULTS — `detail.reason` is 'empty_batch' or 'batch_too_large'."}}}},"/benchmark/{benchmark_id}":{"get":{"tags":["benchmarks"],"summary":"Get one submitted result's full signed document","description":"The full signed result document as originally submitted, keyed by\nits own id (`payload_sha256`) — shaped like `benchmark-result.schema.json`,\nreturned as-is for the same reason `GET /profiles/{id}`/`GET /packs/{id}`\ndo (see schemas.py's own module docstring).","operationId":"get_benchmark_benchmark__benchmark_id__get","parameters":[{"name":"benchmark_id","in":"path","required":true,"schema":{"type":"string","title":"Benchmark Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Benchmark Benchmark  Benchmark Id  Get"}}}},"404":{"description":"No result with this id."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/hardware":{"get":{"tags":["hardware"],"summary":"Hardware actually used by verified results, grouped by how well-identified it is","description":"Hardware records, aggregated three ways depending on what a result's\nhardware_id tells us:\n- catalog-backed: a real curated id (not \"custom\") — group by that id,\n  resolved against the catalog for display.\n- custom: explicitly asserted \"custom\" — group by the same\n  (cpu_model, os_system, os_machine) raw-string triple the legacy\n  branch uses, since \"custom\" itself carries no identifying\n  information on its own but the raw diagnostic string does. This is\n  the \"what to add to the catalog next\" backlog: every custom result\n  already captures this string (see hardware/README.md), it just used\n  to get thrown away by folding straight into one opaque \"custom: N\"\n  catalog row.\n- legacy: pre-catalog result, hardware_id IS NULL — same raw-string\n  triple grouping, kept as its own bucket rather than merged with\n  \"custom\" so the two \"why isn't this catalogued\" reasons (never had\n  the field at all vs. explicitly opted into \"custom\") stay visible\n  as distinct, not silently combined.","operationId":"list_hardware_hardware_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HardwareListResponse"}}}}}}},"/hardware/catalog":{"get":{"tags":["hardware"],"summary":"The curated hardware catalog","description":"The curated hardware catalog itself (hardware/*/hardware.yaml) — what\n`goesb run --hardware` and the wizard's picker fetch to resolve ids, and\nwhat the web hardware page's filters narrow down.","operationId":"list_hardware_catalog_hardware_catalog_get","parameters":[{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"e.g. 'laptop', 'sbc', 'desktop-gpu' — see the returned entries' own `category` values for the full set.","title":"Category"},"description":"e.g. 'laptop', 'sbc', 'desktop-gpu' — see the returned entries' own `category` values for the full set."},{"name":"vendor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"e.g. 'apple', 'nvidia', 'intel'.","title":"Vendor"},"description":"e.g. 'apple', 'nvidia', 'intel'."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HardwareCatalogResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/requests":{"post":{"tags":["requests"],"summary":"Log a request for a missing benchmark","description":"Log a \"request this benchmark\" click from the empty-cell contribute\nflow (guardrail G2) — upserts on the same pipe-joined constraint tuple\n`GET /answers` derives for its `missing` block, so repeat requests for\nthe same gap increment a shared counter rather than piling up rows.","operationId":"create_request_requests_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BenchmarkRequestCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BenchmarkRequestRecord"}}}},"400":{"description":"No constraints at all — at least one of language/hardware/model/runtime/benchmark_type is required."},"429":{"description":"Rate limit exceeded for this IP — see requests_board.check_rate_limit."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["requests"],"summary":"List the most-wanted missing benchmarks","description":"The public \"most-wanted benchmarks\" list, ordered by request count.","operationId":"list_requests_requests_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Max rows to return, 1-100.","default":20,"title":"Limit"},"description":"Max rows to return, 1-100."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BenchmarkRequestListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/runner-tokens":{"post":{"tags":["tokens"],"summary":"Request a signing token before submitting a result","description":"Issue a short-lived, single-use signing token bound to a\ncaller-supplied public key (ADR-0005). The caller's private key never\nleaves their machine — only the public half is sent here. Required\nbefore `POST /benchmark` or `POST /benchmark/batch` — those endpoints\nreject a result whose signature doesn't verify against a token issued\nhere.","operationId":"request_token_runner_tokens_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"422":{"description":"`public_key` isn't a valid base64-encoded 32-byte Ed25519 public key — `detail.reason` is 'invalid_public_key'."},"429":{"description":"Rate limit exceeded for this IP — see tokens.py's issuance limit."}}}},"/health":{"get":{"tags":["meta"],"summary":"Service status and version","description":"Liveness/version check. `min_runner_version` is what `goesb run`\ncompares itself against to warn a caller their runner is outdated\n(see MIN_RUNNER_VERSION) -- not just a health probe, also how the CLI\nself-checks staleness.","operationId":"health_health_get","responses":{"200":{"description":"Always 200 with status 'ok' when the process is up -- this endpoint is exempt from maintenance mode.","content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object","title":"Response Health Health Get"}}}}}}}},"components":{"schemas":{"AlternativeResult":{"properties":{"verdict":{"$ref":"#/components/schemas/AnswerVerdict"},"metrics":{"additionalProperties":{"type":"number"},"type":"object","title":"Metrics","description":"Median value per metric id across the group's runs. Latency metrics also get flattened '<metric>_p50'/'<metric>_p95' keys."},"est_concurrent_streams":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Est Concurrent Streams","description":"floor(1 / real_time_factor) — a rough capacity estimate, not a measured value. Null for batch (no concurrency concept) or when RTF is missing. See the real concurrency benchmark_type for measured throughput under actual simultaneous load instead of this estimate."},"provenance":{"$ref":"#/components/schemas/AnswerProvenance"},"aggregation":{"type":"string","title":"Aggregation","description":"Always 'median across runs' today — stated explicitly so the number's meaning never has to be assumed."},"runtime":{"type":"string","title":"Runtime"},"model":{"type":"string","title":"Model"},"hardware":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hardware"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"benchmark_type":{"type":"string","title":"Benchmark Type"},"runtime_divergence_warning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Runtime Divergence Warning","description":"Non-null when another runtime running the exact same model weights on the same pack+hardware reports a materially different WER — same weights should score the same regardless of engine, so a real gap usually means a decode-config or adapter bug in one of them, not a genuine capability difference."},"differs":{"items":{"type":"string"},"type":"array","title":"Differs","description":"Which axes (pack/runtime/model/hardware/language) this group differs on from best_match. Usually empty — these matched the same query."}},"type":"object","required":["verdict","metrics","provenance","aggregation","runtime","model","hardware","language","benchmark_type","differs"],"title":"AlternativeResult","description":"A same-constraints group ranked below `best_match` (top 5)."},"AnswerProvenance":{"properties":{"runs":{"type":"integer","title":"Runs","description":"How many individual verified results were median-aggregated into this group."},"newest":{"type":"string","title":"Newest","description":"ISO 8601 timestamp of the most recent contributing run."},"verified":{"type":"boolean","title":"Verified","description":"Always true today — every stored result already passed the trust gate (ADR-0004) before ingestion."},"profile":{"type":"string","title":"Profile","description":"'<profile_id>@<version>' of the newest contributing run."},"pack":{"type":"string","title":"Pack","description":"'<pack_id>@<version>' of the newest contributing run."},"benchmark_ids":{"items":{"type":"string"},"type":"array","title":"Benchmark Ids","description":"Ids of every individual result folded into this group's median — for GET /benchmark/{id} lookups."},"distinct_submitters":{"type":"integer","title":"Distinct Submitters","description":"Count of distinct callsign#discriminator identities among this group's runs. Anonymous runs (no submitted_by) never count — an unattributed run can't corroborate anyone. 0 or 1 means unreproduced-by-others; 2+ means independent submitters got the same result."}},"type":"object","required":["runs","newest","verified","profile","pack","benchmark_ids","distinct_submitters"],"title":"AnswerProvenance"},"AnswerQuery":{"properties":{"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"pack":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pack"},"hardware":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hardware"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model"},"runtime":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Runtime"},"benchmark_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Benchmark Type"},"rank_by":{"type":"string","title":"Rank By","description":"Which metric decided the ranking, e.g. 'wer', 'real_time_factor', 'energy_wh', 'first_final_latency'."}},"type":"object","required":["rank_by"],"title":"AnswerQuery","description":"The resolved query this response was computed for — echoed back so\nthe answer is self-describing without re-sending the original request."},"AnswerResponse":{"properties":{"query":{"$ref":"#/components/schemas/AnswerQuery"},"ranking_rule":{"type":"string","title":"Ranking Rule","description":"Stated plainly, e.g. 'lowest wer, ties broken by real_time_factor' — the ranking is always a fixed rule, never an editorial pick (guardrail G1)."},"best_match":{"anyOf":[{"$ref":"#/components/schemas/AnswerResult"},{"type":"null"}],"description":"Null only when nothing verified matches the exact query — see `missing` and `closest_matches` instead."},"alternatives":{"items":{"$ref":"#/components/schemas/AlternativeResult"},"type":"array","title":"Alternatives","description":"Up to 5 more groups that also matched the exact query, ranked below best_match."},"closest_matches":{"items":{"$ref":"#/components/schemas/ClosestMatch"},"type":"array","title":"Closest Matches","description":"Up to 3 groups after relaxing one constraint at a time — populated only when best_match is null."},"missing":{"anyOf":[{"$ref":"#/components/schemas/MissingInfo"},{"type":"null"}],"description":"Populated only when best_match is null."}},"type":"object","required":["query","ranking_rule"],"title":"AnswerResponse"},"AnswerResult":{"properties":{"verdict":{"$ref":"#/components/schemas/AnswerVerdict"},"metrics":{"additionalProperties":{"type":"number"},"type":"object","title":"Metrics","description":"Median value per metric id across the group's runs. Latency metrics also get flattened '<metric>_p50'/'<metric>_p95' keys."},"est_concurrent_streams":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Est Concurrent Streams","description":"floor(1 / real_time_factor) — a rough capacity estimate, not a measured value. Null for batch (no concurrency concept) or when RTF is missing. See the real concurrency benchmark_type for measured throughput under actual simultaneous load instead of this estimate."},"provenance":{"$ref":"#/components/schemas/AnswerProvenance"},"aggregation":{"type":"string","title":"Aggregation","description":"Always 'median across runs' today — stated explicitly so the number's meaning never has to be assumed."},"runtime":{"type":"string","title":"Runtime"},"model":{"type":"string","title":"Model"},"hardware":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hardware"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"benchmark_type":{"type":"string","title":"Benchmark Type"},"runtime_divergence_warning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Runtime Divergence Warning","description":"Non-null when another runtime running the exact same model weights on the same pack+hardware reports a materially different WER — same weights should score the same regardless of engine, so a real gap usually means a decode-config or adapter bug in one of them, not a genuine capability difference."}},"type":"object","required":["verdict","metrics","provenance","aggregation","runtime","model","hardware","language","benchmark_type"],"title":"AnswerResult","description":"One (profile, pack, hardware) group, reduced to its median metrics —\nthe shape shared by `best_match`, `alternatives`, and `closest_matches`."},"AnswerVerdict":{"properties":{"realtime_capable":{"type":"boolean","title":"Realtime Capable","description":"True when real_time_factor < 1.0. Null-safe: false (with an 'unknown' label) if this group has no RTF metric at all."},"label":{"type":"string","title":"Label","description":"Human-readable verdict, e.g. 'Realtime capable', 'Not realtime (RTF 1.4)', or 'Realtime capability unknown (no RTF data)'."}},"type":"object","required":["realtime_capable","label"],"title":"AnswerVerdict"},"BatchSubmitRequest":{"properties":{"token_id":{"type":"string","title":"Token Id","description":"A signing token id from POST /runner-tokens, not yet consumed by a prior submission."},"results":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Results","description":"Up to a fixed per-call cap (see ingest.MAX_BATCH_RESULTS) signed result documents, each shaped like a single POST /benchmark body. A bad item never blocks its siblings — see BatchSubmitResultItem."}},"type":"object","required":["token_id","results"],"title":"BatchSubmitRequest"},"BatchSubmitResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/BatchSubmitResultItem"},"type":"array","title":"Results"}},"type":"object","required":["results"],"title":"BatchSubmitResponse"},"BatchSubmitResultItem":{"properties":{"accepted":{"type":"boolean","title":"Accepted"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Set only when accepted=true — the stored result's id, usable with GET /benchmark/{id}."},"detail":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Detail","description":"Set only when accepted=false — {reason, ...} where reason is one of schema_invalid / hash_or_signature_invalid / not_an_official_profile / profile_hash_mismatch / not_a_known_pack / pack_not_open, the same machine-readable reasons a single POST /benchmark rejection raises."}},"type":"object","required":["accepted"],"title":"BatchSubmitResultItem"},"BenchmarkRequestCreate":{"properties":{"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"hardware":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hardware"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model"},"runtime":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Runtime"},"benchmark_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Benchmark Type"}},"type":"object","title":"BenchmarkRequestCreate","description":"At least one field is required — see POST /requests."},"BenchmarkRequestListResponse":{"properties":{"requests":{"items":{"$ref":"#/components/schemas/BenchmarkRequestRecord"},"type":"array","title":"Requests","description":"Ordered by request count descending — the public 'most-wanted benchmarks' board."}},"type":"object","required":["requests"],"title":"BenchmarkRequestListResponse"},"BenchmarkRequestRecord":{"properties":{"request_key":{"type":"string","title":"Request Key","description":"Pipe-joined constraint tuple — the same key GET /answers' `missing.request_key` computes for a gap, so a click-through always upserts the right row."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"hardware":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hardware"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model"},"runtime":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Runtime"},"benchmark_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Benchmark Type"},"count":{"type":"integer","title":"Count","description":"How many times this exact constraint tuple has been requested — repeat requests increment this rather than creating duplicate rows."},"first_requested":{"type":"string","title":"First Requested","description":"ISO 8601 timestamp of the first request for this tuple."},"last_requested":{"type":"string","title":"Last Requested","description":"ISO 8601 timestamp of the most recent request for this tuple."}},"type":"object","required":["request_key","language","hardware","model","runtime","benchmark_type","count","first_requested","last_requested"],"title":"BenchmarkRequestRecord"},"ClosestMatch":{"properties":{"verdict":{"$ref":"#/components/schemas/AnswerVerdict"},"metrics":{"additionalProperties":{"type":"number"},"type":"object","title":"Metrics","description":"Median value per metric id across the group's runs. Latency metrics also get flattened '<metric>_p50'/'<metric>_p95' keys."},"est_concurrent_streams":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Est Concurrent Streams","description":"floor(1 / real_time_factor) — a rough capacity estimate, not a measured value. Null for batch (no concurrency concept) or when RTF is missing. See the real concurrency benchmark_type for measured throughput under actual simultaneous load instead of this estimate."},"provenance":{"$ref":"#/components/schemas/AnswerProvenance"},"aggregation":{"type":"string","title":"Aggregation","description":"Always 'median across runs' today — stated explicitly so the number's meaning never has to be assumed."},"runtime":{"type":"string","title":"Runtime"},"model":{"type":"string","title":"Model"},"hardware":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hardware"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"benchmark_type":{"type":"string","title":"Benchmark Type"},"runtime_divergence_warning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Runtime Divergence Warning","description":"Non-null when another runtime running the exact same model weights on the same pack+hardware reports a materially different WER — same weights should score the same regardless of engine, so a real gap usually means a decode-config or adapter bug in one of them, not a genuine capability difference."},"differs":{"items":{"type":"string"},"type":"array","title":"Differs","description":"Which of the originally-requested axes this group actually differs on — not just which axis the relaxation search dropped."}},"type":"object","required":["verdict","metrics","provenance","aggregation","runtime","model","hardware","language","benchmark_type","differs"],"title":"ClosestMatch","description":"Present only when nothing matched the exact query — the closest verified data after relaxing one constraint at a time (guardrail G2)."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HardwareCatalogEntry":{"properties":{"id":{"type":"string","title":"Id","description":"Stable id — pass to `?hardware=` on GET /leaderboards or GET /answers."},"display_name":{"type":"string","title":"Display Name"},"vendor":{"type":"string","title":"Vendor"},"category":{"type":"string","title":"Category"},"cores":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cores"},"threads":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Threads"},"base_clock_ghz":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Base Clock Ghz"},"max_clock_ghz":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Clock Ghz"},"vram_gb":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Vram Gb","description":"Present only for discrete/dedicated GPU entries."},"ram_gb":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ram Gb"},"tops":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Tops","description":"Peak claimed TOPS (trillion operations/sec) at whatever precision the vendor quotes — not independently verified."},"release_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Release Year"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"}},"type":"object","required":["id","display_name","vendor","category"],"title":"HardwareCatalogEntry"},"HardwareCatalogResponse":{"properties":{"hardware":{"items":{"$ref":"#/components/schemas/HardwareCatalogEntry"},"type":"array","title":"Hardware"}},"type":"object","required":["hardware"],"title":"HardwareCatalogResponse"},"HardwareListResponse":{"properties":{"hardware":{"items":{"$ref":"#/components/schemas/HardwareRecord"},"type":"array","title":"Hardware"}},"type":"object","required":["hardware"],"title":"HardwareListResponse"},"HardwareRecord":{"properties":{"source":{"type":"string","enum":["catalog","custom","legacy"],"title":"Source","description":"'catalog': a curated GET /hardware/catalog id. 'custom': the runner explicitly asserted hardware not in the catalog (cpu_model/os_system/os_machine/gpu_model identify it instead). 'legacy': a pre-catalog result with no hardware_id at all."},"hardware_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hardware Id","description":"Set only when source='catalog' — an id from GET /hardware/catalog."},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"vendor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"cpu_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cpu Model","description":"Set only when source is 'custom' or 'legacy'."},"os_system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Os System","description":"Set only when source is 'custom' or 'legacy'."},"os_machine":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Os Machine","description":"Set only when source is 'custom' or 'legacy'."},"gpu_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gpu Model","description":"Set only when source is 'custom' or 'legacy', and a GPU backend was used."},"result_count":{"type":"integer","title":"Result Count","description":"Number of verified results grouped into this row."}},"type":"object","required":["source","result_count"],"title":"HardwareRecord"},"LeaderboardEntry":{"properties":{"id":{"type":"string","title":"Id","description":"The result's own hash-derived id (payload_sha256 in the signed result document)."},"profile_id":{"type":"string","title":"Profile Id"},"profile_version":{"type":"string","title":"Profile Version"},"pack_id":{"type":"string","title":"Pack Id"},"pack_version":{"type":"string","title":"Pack Version"},"runtime_name":{"type":"string","title":"Runtime Name"},"model_name":{"type":"string","title":"Model Name"},"hardware":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hardware","description":"A GET /hardware/catalog id, or null for custom/legacy hardware (see GET /hardware for the raw strings)."},"backend":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Backend","description":"Compute backend actually used, e.g. 'cpu', 'cuda', 'metal' (ADR-0008)."},"timestamp":{"type":"string","title":"Timestamp","description":"ISO 8601 UTC, when the run completed."},"repeats":{"type":"integer","title":"Repeats"},"metrics":{"additionalProperties":true,"type":"object","title":"Metrics","description":"Keyed by metric id (e.g. 'wer', 'real_time_factor', 'energy_wh'). Each value is {value, unit, spread?} — spread (std/min/max/p50/p95) is present when repeats > 1 or the metric is pooled per-utterance (e.g. concurrency's real_time_factor)."},"parameters":{"additionalProperties":true,"type":"object","title":"Parameters","description":"Keyed by parameter name (e.g. 'concurrency', 'beam_size'). Each value is {value, default} — every profile-declared overridable parameter this run resolved, whether or not it was actually overridden (ADR-0009). Empty for results from before this field existed."},"comment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comment","description":"Freeform note the submitter attached at `goesb submit` time, if any."},"submitted_by":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Submitted By","description":"{callsign, discriminator} if the submitter opted in to attribution; null if submitted anonymously or on an older runner."}},"type":"object","required":["id","profile_id","profile_version","pack_id","pack_version","runtime_name","model_name","hardware","backend","timestamp","repeats","metrics"],"title":"LeaderboardEntry"},"LeaderboardResponse":{"properties":{"total":{"type":"integer","title":"Total","description":"Total rows matching the filters, independent of limit/offset — for pagination, not just len(results)."},"filters":{"additionalProperties":true,"type":"object","title":"Filters","description":"Every filter this response was computed with — the resolved query, echoed back, including defaults."},"results":{"items":{"$ref":"#/components/schemas/LeaderboardEntry"},"type":"array","title":"Results"}},"type":"object","required":["total","filters","results"],"title":"LeaderboardResponse"},"MissingInfo":{"properties":{"runner_command":{"type":"string","title":"Runner Command","description":"The exact `goesb run <profile> <pack>` invocation that would produce this missing benchmark, or an explanatory string if no matching profile/pack exists yet."},"request_key":{"type":"string","title":"Request Key","description":"Pipe-joined constraint tuple identifying this exact gap — POST this as-is to /requests to register interest in it."}},"type":"object","required":["runner_command","request_key"],"title":"MissingInfo","description":"Present only when `best_match` is null — what to run to fill the gap, and how to request it instead."},"PackListResponse":{"properties":{"packs":{"items":{"$ref":"#/components/schemas/PackSummary"},"type":"array","title":"Packs"}},"type":"object","required":["packs"],"title":"PackListResponse"},"PackSummary":{"properties":{"id":{"type":"string","title":"Id"},"version":{"type":"string","title":"Version"},"sha256":{"type":"string","title":"Sha256"},"visibility":{"type":"string","enum":["open","community","private"],"title":"Visibility","description":"Only 'open' packs can back a public leaderboard result (FR-7.3) — identical data for everyone. 'community'/'private' packs exist for local use but never surface there."},"profile_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Profile Id","description":"Informational only (ADR-0011) — a profile's real eligibility is decided by matching `language`, not this field."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"gated":{"type":"boolean","title":"Gated","description":"True if `goesb run` needs a personal API key/credential (ADR-0010) before it can fetch this pack's audio.","default":false}},"type":"object","required":["id","version","sha256","visibility"],"title":"PackSummary"},"ProfileListResponse":{"properties":{"profiles":{"items":{"$ref":"#/components/schemas/ProfileSummary"},"type":"array","title":"Profiles"}},"type":"object","required":["profiles"],"title":"ProfileListResponse"},"ProfileSummary":{"properties":{"id":{"type":"string","title":"Id"},"version":{"type":"string","title":"Version"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"benchmark_type":{"type":"string","title":"Benchmark Type"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"runtime":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Runtime"}},"type":"object","required":["id","version","benchmark_type"],"title":"ProfileSummary"},"SubmitBenchmarkResponse":{"properties":{"id":{"type":"string","title":"Id","description":"The newly-stored result's id (its payload_sha256) — usable with GET /benchmark/{id}."},"accepted":{"type":"boolean","title":"Accepted","description":"Always true on a 201 response — a rejected submission raises an HTTPException instead of returning accepted=false."}},"type":"object","required":["id","accepted"],"title":"SubmitBenchmarkResponse"},"TokenRequest":{"properties":{"public_key":{"type":"string","title":"Public Key","description":"Base64-encoded raw Ed25519 public key (32 bytes). The matching private key never leaves the caller's machine (ADR-0005) — only this public half is sent."}},"type":"object","required":["public_key"],"title":"TokenRequest"},"TokenResponse":{"properties":{"token_id":{"type":"string","title":"Token Id","description":"Pass as `token_id` when submitting the signed result(s) this token authorizes."},"expires_at":{"type":"string","title":"Expires At","description":"ISO 8601 timestamp — short-lived and single-use; submit before this or request a fresh token."}},"type":"object","required":["token_id","expires_at"],"title":"TokenResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"leaderboards","description":"Filterable, sortable results (FR-7.1) -- the data behind every leaderboard view on the site."},{"name":"answers","description":"The decision-tool endpoint (M4b) -- \"best match for your constraints,\" deterministic and never editorial (guardrail G1)."},{"name":"profiles","description":"Official, versioned benchmark profiles (what gets run) -- read-only."},{"name":"packs","description":"Benchmark datasets (what gets transcribed) -- read-only."},{"name":"benchmarks","description":"Submit signed results (ADR-0004). Requires a runner-tokens signing token issued first -- this is not an open POST."},{"name":"hardware","description":"The curated hardware catalog, plus which hardware real results were actually run on."},{"name":"requests","description":"The public \"most-wanted benchmarks\" board (guardrail G2) -- log and read requests for a benchmark gap."},{"name":"tokens","description":"Short-lived, single-use signing tokens (ADR-0005) required before POST /benchmark. Rate-limited per IP."},{"name":"meta","description":"Service status, unrelated to benchmark data."}],"servers":[{"url":"/api"}]}