{"openapi":"3.1.0","info":{"title":"DVBench API","description":"HTTP and WebSocket endpoints for DVBench experiments, measurements, benchmarks, models, and text ingestion.","license":{"name":""},"version":"0.1.0"},"paths":{"/":{"get":{"tags":["system"],"operationId":"root","responses":{"200":{"description":"HTML API welcome page"}}}},"/api/v1/benchmarks":{"get":{"tags":["benchmarks"],"operationId":"benchmarks","responses":{"200":{"description":"Benchmark definitions"}}},"post":{"tags":["benchmarks"],"operationId":"create_benchmark","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBenchmark"}}},"required":true},"responses":{"200":{"description":"Benchmark created"},"400":{"description":"Invalid benchmark definition"}}}},"/api/v1/benchmarks/{benchmark_id}":{"get":{"tags":["benchmarks"],"description":"Filter with verified, scale_min/scale_max (parameter counts), metrics.<measurement name>_min/_max, and dataset (including Unknown for missing or unmatched tape training data). Dataset proportions use tape rolling-window hash occurrences matched to indexed corpora. ISO FLOPs estimates 6 × committed parameter count × tape training tokens, with no size-based token fallback. Filters and sorting apply before pagination. Available filters are returned in filterables.","operationId":"benchmark","parameters":[{"name":"benchmark_id","in":"path","description":"Benchmark ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"page","in":"query","description":"Leaderboard page, starting at 1","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"limit","in":"query","description":"Rows per page, from 1 through 100","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"sort","in":"query","description":"model, scale, isoflops, comparator, or metrics.<name>; unknown compute sorts last","required":false,"schema":{"type":"string"}},{"name":"direction","in":"query","description":"asc or desc","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Benchmark definition and leaderboard"},"400":{"description":"Invalid pagination, sort, or filter"},"404":{"description":"Benchmark not found"}}},"put":{"tags":["benchmarks"],"operationId":"update_benchmark","parameters":[{"name":"benchmark_id","in":"path","description":"Benchmark ID","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBenchmark"}}},"required":true},"responses":{"200":{"description":"Benchmark updated"},"404":{"description":"Benchmark not found"}}},"delete":{"tags":["benchmarks"],"operationId":"delete_benchmark","parameters":[{"name":"benchmark_id","in":"path","description":"Benchmark ID","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Benchmark deleted"},"404":{"description":"Benchmark not found"}}}},"/api/v1/downloads/{filename}":{"put":{"tags":["downloads"],"operationId":"publish_download","parameters":[{"name":"filename","in":"path","description":"PEP 427 wheel filename","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Wheel bytes, up to 512 MiB","content":{"application/octet-stream":{"schema":{"type":"string"}}},"required":true},"responses":{"200":{"description":"Wheel published atomically"},"400":{"description":"Invalid or empty wheel"},"401":{"description":"Missing or invalid publishing credential"},"413":{"description":"Wheel exceeds 512 MiB"}},"security":[{"wheel_publish_token":[]}]}},"/api/v1/experiments":{"post":{"tags":["experiments"],"operationId":"create_experiment","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateExperiment"}}},"required":true},"responses":{"200":{"description":"Experiment created or returned"},"400":{"description":"Invalid experiment name"}}}},"/api/v1/experiments/{id}/metadata":{"put":{"tags":["experiments"],"operationId":"update_run_metadata","parameters":[{"name":"id","in":"path","description":"Experiment ID from a leaderboard row","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunMetadata"}}},"required":true},"responses":{"200":{"description":"Run descriptions updated; training evidence is read from the tape"},"400":{"description":"Invalid description or unsupported metadata field"},"404":{"description":"Experiment not found"}}}},"/api/v1/measurement-definitions":{"get":{"tags":["measurements"],"operationId":"measurement_definitions","responses":{"200":{"description":"Measurement definitions"}}},"post":{"tags":["measurements"],"operationId":"create_measurement_definition","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDefinition"}}},"required":true},"responses":{"200":{"description":"Measurement definition created or updated"},"400":{"description":"Invalid definition"}}}},"/api/v1/measurement-definitions/{id}":{"get":{"tags":["measurements"],"operationId":"measurement_definition","parameters":[{"name":"id","in":"path","description":"Measurement definition ID","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Measurement definition and public results"},"404":{"description":"Measurement definition not found"}}},"put":{"tags":["measurements"],"operationId":"update_measurement_definition","parameters":[{"name":"id","in":"path","description":"Measurement definition ID","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDefinition"}}},"required":true},"responses":{"200":{"description":"Measurement definition updated"},"404":{"description":"Measurement definition not found"}}},"delete":{"tags":["measurements"],"operationId":"delete_measurement_definition","parameters":[{"name":"id","in":"path","description":"Measurement definition ID","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Measurement definition deleted"},"404":{"description":"Measurement definition not found"}}}},"/api/v1/measurement-results/{id}":{"get":{"tags":["measurements"],"operationId":"measurement_result","parameters":[{"name":"id","in":"path","description":"Measurement result ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"page","in":"query","description":"Observation page, starting at 1","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"limit","in":"query","description":"Observations per page, from 1 through 100","required":false,"schema":{"type":"integer","format":"int32","minimum":0}}],"responses":{"200":{"description":"Measurement result trace"},"400":{"description":"Invalid pagination"},"404":{"description":"Measurement result not found"}}}},"/api/v1/measurements":{"post":{"tags":["measurements"],"operationId":"submit_measurement","requestBody":{"description":"Signed DVBench measurement submission","content":{"application/json":{"schema":{}}},"required":true},"responses":{"200":{"description":"Measurement queued; payload is the request ID"},"400":{"description":"Invalid measurement or signature"}}}},"/api/v1/measurements/{request_id}":{"get":{"tags":["measurements"],"operationId":"measurement_status","parameters":[{"name":"request_id","in":"path","description":"32-byte hexadecimal request ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Measurement processing status"},"400":{"description":"Malformed request ID"},"404":{"description":"Measurement request not found"}}}},"/api/v1/models":{"get":{"tags":["models"],"operationId":"models","parameters":[{"name":"name","in":"query","description":"Normalized model or experiment name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Models matching the name"},"400":{"description":"Invalid model name"}}}},"/api/v1/models/{transcript_id}":{"get":{"tags":["models"],"operationId":"model","parameters":[{"name":"transcript_id","in":"path","description":"32-byte hexadecimal transcript ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Model transcript detail"},"400":{"description":"Malformed transcript ID"},"404":{"description":"Transcript not found"}}}},"/api/v1/models/{transcript_id}/data":{"get":{"tags":["models"],"operationId":"training_data","parameters":[{"name":"transcript_id","in":"path","description":"32-byte hexadecimal transcript ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Training-data commitment summary"},"400":{"description":"Malformed transcript ID"},"404":{"description":"Transcript not found"}}}},"/api/v1/models/{transcript_id}/data/progress":{"get":{"tags":["models"],"operationId":"training_data_progress","parameters":[{"name":"transcript_id","in":"path","description":"32-byte hexadecimal transcript ID","required":true,"schema":{"type":"string"}},{"name":"focus","in":"query","description":"Training step to focus","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"radius","in":"query","description":"Number of surrounding buckets; defaults to 24","required":false,"schema":{"type":"integer","format":"int32","minimum":0}}],"responses":{"200":{"description":"Foveated rolling-hash progress"},"400":{"description":"Malformed transcript ID"}}}},"/api/v1/models/{transcript_id}/measurements/{measurement_id}":{"get":{"tags":["measurements"],"operationId":"measurement_trace","parameters":[{"name":"transcript_id","in":"path","description":"32-byte hexadecimal transcript ID","required":true,"schema":{"type":"string"}},{"name":"measurement_id","in":"path","description":"Measurement result ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"page","in":"query","description":"Observation page, starting at 1","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"limit","in":"query","description":"Observations per page, from 1 through 100","required":false,"schema":{"type":"integer","format":"int32","minimum":0}}],"responses":{"200":{"description":"Measurement trace scoped to a model transcript"},"400":{"description":"Malformed transcript ID or pagination"},"404":{"description":"Measurement result not found"}}}},"/api/v1/records":{"get":{"tags":["ingest"],"operationId":"records","responses":{"101":{"description":"WebSocket upgraded; binary transcript records and acknowledgements use the DVBench protocol"},"400":{"description":"Invalid WebSocket upgrade"}}}},"/api/v1/runs":{"get":{"tags":["models"],"operationId":"runs","responses":{"200":{"description":"Observed transcript runs"}}}},"/api/v1/texts":{"post":{"tags":["ingest"],"operationId":"ingest_text","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TextIngestRequest"}}},"required":true},"responses":{"202":{"description":"Text persisted and indexing job accepted"},"400":{"description":"Invalid text, tokenizer, corpus, or rolling-window range"},"413":{"description":"Request exceeds 512 MiB"}}}},"/api/v1/texts/{hash}":{"get":{"tags":["ingest"],"operationId":"text","parameters":[{"name":"hash","in":"path","description":"32-byte hexadecimal rolling-text hash","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Indexed text window"},"400":{"description":"Malformed text hash"},"404":{"description":"Indexed text not found"}}}},"/api/v1/texts/{hash}/vectors":{"get":{"tags":["vectors"],"operationId":"text_vectors","parameters":[{"name":"hash","in":"path","description":"32-byte hexadecimal probe-vector hash","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CBOR-encoded probe vectors"},"400":{"description":"Malformed vector hash"},"404":{"description":"Probe vectors not found"}}}},"/api/v1/tokenizers":{"get":{"tags":["ingest"],"operationId":"tokenizers","responses":{"200":{"description":"Supported tokenizer names"}}}},"/api/v1/vectors/resolve":{"post":{"tags":["vectors"],"operationId":"resolve_vectors","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveRequest"}}},"required":true},"responses":{"200":{"description":"Resolved vector visualizations"},"400":{"description":"Batch must contain 1 through 500 valid handles"},"404":{"description":"Vector object not found"}}}},"/api/v1/vectors/{handle}":{"get":{"tags":["vectors"],"operationId":"vector","parameters":[{"name":"handle","in":"path","description":"Object, slice, or rolling-text vector handle","required":true,"schema":{"type":"string"}},{"name":"transcript_id","in":"query","description":"Optional transcript context for token decoding","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Resolved vector visualization"},"400":{"description":"Malformed handle or context"},"404":{"description":"Vector object not found"}}},"put":{"tags":["vectors"],"operationId":"upload_vector","parameters":[{"name":"handle","in":"path","description":"BLAKE3 digest expected for the uploaded object","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Encoded DVBench vector object","content":{"application/octet-stream":{"schema":{"type":"string"}}},"required":true},"responses":{"200":{"description":"Vector stored"},"400":{"description":"Malformed digest or content mismatch"},"413":{"description":"Vector object is too large"}}}},"/downloads":{"get":{"tags":["downloads"],"operationId":"downloads","responses":{"200":{"description":"HTML index of published production wheels"}}}},"/downloads/":{"get":{"tags":["downloads"],"operationId":"downloads_with_trailing_slash","responses":{"200":{"description":"HTML index of published production wheels"}}}},"/downloads/{filename}":{"get":{"tags":["downloads"],"operationId":"download","parameters":[{"name":"filename","in":"path","description":"Published wheel filename","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Wheel artifact"},"404":{"description":"Wheel not found"}}},"head":{"tags":["downloads"],"operationId":"download_metadata","parameters":[{"name":"filename","in":"path","description":"Published wheel filename","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Wheel artifact metadata"},"404":{"description":"Wheel not found"}}}},"/healthz":{"get":{"tags":["system"],"operationId":"health","responses":{"200":{"description":"API is healthy"}}}}},"components":{"schemas":{"CreateBenchmark":{"type":"object","required":["name","description","measurement_ids","key_measurement_id","sort_direction"],"properties":{"description":{"type":"string"},"key_measurement_id":{"type":"integer","format":"int64"},"long_description":{"type":"string"},"measurement_ids":{"type":"array","items":{"type":"integer","format":"int64"}},"name":{"type":"string"},"sort_direction":{"$ref":"#/components/schemas/Direction"}}},"CreateDefinition":{"type":"object","required":["name","description"],"properties":{"description":{"type":"string"},"long_description":{"type":["string","null"]},"name":{"type":"string"}}},"CreateExperiment":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}},"Direction":{"type":"string","enum":["asc","desc"]},"ResolveRequest":{"type":"object","required":["vectors"],"properties":{"vectors":{"type":"array","items":{"$ref":"#/components/schemas/VectorHandle"}}}},"RunMetadata":{"type":"object","required":["description","long_description"],"properties":{"description":{"type":"string"},"long_description":{"type":"string"}},"additionalProperties":false},"TextIngestRequest":{"type":"object","required":["text","tokenizer","window_size","corpus"],"properties":{"corpus":{"type":"string"},"text":{"type":"string"},"tokenizer":{"type":"string"},"window_size":{"$ref":"#/components/schemas/TextWindowSize"}}},"TextWindowSize":{"type":"object","required":["max"],"properties":{"max":{"type":"integer","format":"int64","description":"Required inclusive upper bound; 2048 is a typical value.","example":2048,"maximum":65536,"minimum":1},"min":{"type":"integer","format":"int64","description":"Inclusive lower bound; defaults to 128 when omitted.","default":128,"maximum":65536,"minimum":1}}},"UpdateBenchmark":{"type":"object","required":["description"],"properties":{"description":{"type":"string"},"long_description":{"type":"string"}}},"UpdateDefinition":{"type":"object","required":["description"],"properties":{"description":{"type":"string"},"long_description":{"type":"string"}}},"VectorHandle":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"transcript_id":{"type":["string","null"]}}}},"securitySchemes":{"wheel_publish_token":{"type":"http","scheme":"bearer"}}},"tags":[{"name":"system","description":"Service discovery and health"},{"name":"downloads","description":"Production client wheel distribution"},{"name":"ingest","description":"Transcript and text ingestion"},{"name":"experiments","description":"Experiment declarations"},{"name":"measurements","description":"Measurement definitions, submissions, and traces"},{"name":"vectors","description":"Measurement vector storage and visualization"},{"name":"models","description":"Recorded model and training-data views"},{"name":"benchmarks","description":"Benchmark definitions and leaderboards"}]}