{"openapi":"3.1.0","info":{"title":"vlt benchmarks API","version":"1.0.0","description":"Install and run performance for JavaScript package managers, registries and task runners, measured nightly on identical GitHub-hosted runners and published in full. Read-only, no authentication. Errors are `{ error: { code, message, hint } }`. An MCP server with the same data is at /mcp; every page is indexed as Markdown at /llms.txt."},"servers":[{"url":"https://benchmarks.vlt.io"}],"security":[],"paths":{"/api/v1/runs":{"get":{"operationId":"listRuns","summary":"Every published run, by date","responses":{"200":{"description":"The latest run and every published date, oldest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Runs"}}}}}}},"/api/v1/catalog":{"get":{"operationId":"getCatalog","summary":"Benchmarks, their scenarios, tools and fixtures in the latest run","responses":{"200":{"description":"The catalog of the latest run.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}}}}},"/api/v1/{section}/{scenario}":{"get":{"operationId":"getReport","summary":"One scenario's full report, as its page shows it","parameters":[{"name":"section","in":"path","required":true,"schema":{"type":"string","enum":["registries","package-managers","task-runners"]},"description":"The benchmark."},{"name":"scenario","in":"path","required":true,"schema":{"type":"string"},"description":"A scenario published by the run, e.g. `clean` or `cache+lockfile`. /api/v1/catalog lists them."},{"name":"date","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"A published run; absent means the latest. An unpublished date is a 400."},{"name":"fixture","in":"query","required":false,"schema":{"type":"string"},"description":"One fixture; absent means all of them. One the scenario did not publish is a 400."},{"name":"range","in":"query","required":false,"schema":{"type":"integer","enum":[30,60,90,120],"default":30},"description":"Trend window: this many calendar days ending at the run."},{"name":"from","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"Exact trend window start; with `to`. Both must be published dates, less than 120 days apart."},{"name":"to","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"Exact trend window end; no later than the run."},{"name":"metric","in":"query","required":false,"schema":{"type":"string","enum":["total","change","baseline","per-package"],"default":"total"},"description":"What the trend holds. Total time is the measurement; the others are derived."},{"name":"exclude","in":"query","required":false,"schema":{"type":"string"},"description":"Runs taken out of every trend, comma-separated: `YYYY-MM-DD` or `tool@YYYY-MM-DD`."},{"name":"hide","in":"query","required":false,"schema":{"type":"string"},"description":"Tools left out of the rows, comma-separated. Rankings and ratios still count them."}],"responses":{"200":{"description":"The report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}}},"400":{"description":"A date, fixture or window that cannot be used.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"An unknown benchmark or scenario, or a run that published no results for it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/{section}/{scenario}/history":{"get":{"operationId":"getHistory","summary":"One scenario's trend, failures and coverage","parameters":[{"name":"section","in":"path","required":true,"schema":{"type":"string","enum":["registries","package-managers","task-runners"]},"description":"The benchmark."},{"name":"scenario","in":"path","required":true,"schema":{"type":"string"},"description":"A scenario published by the run, e.g. `clean` or `cache+lockfile`. /api/v1/catalog lists them."},{"name":"date","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"A published run; absent means the latest. An unpublished date is a 400."},{"name":"fixture","in":"query","required":false,"schema":{"type":"string"},"description":"One fixture; absent means all of them. One the scenario did not publish is a 400."},{"name":"range","in":"query","required":false,"schema":{"type":"integer","enum":[30,60,90,120],"default":30},"description":"Trend window: this many calendar days ending at the run."},{"name":"from","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"Exact trend window start; with `to`. Both must be published dates, less than 120 days apart."},{"name":"to","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"Exact trend window end; no later than the run."},{"name":"metric","in":"query","required":false,"schema":{"type":"string","enum":["total","change","baseline","per-package"],"default":"total"},"description":"What the trend holds. Total time is the measurement; the others are derived."},{"name":"exclude","in":"query","required":false,"schema":{"type":"string"},"description":"Runs taken out of every trend, comma-separated: `YYYY-MM-DD` or `tool@YYYY-MM-DD`."},{"name":"tools","in":"query","required":false,"schema":{"type":"string"},"description":"Tools to include, comma-separated; absent means all."}],"responses":{"200":{"description":"The trend.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/History"}}}},"400":{"description":"A date, fixture, window or tool that cannot be used.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"An unknown benchmark or scenario.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/{section}/{scenario}.md":{"get":{"operationId":"getReportMarkdown","summary":"One scenario's report as Markdown","description":"The same page also answers `Accept: text/markdown` at its own URL. Takes the page's query parameters.","parameters":[{"name":"section","in":"path","required":true,"schema":{"type":"string","enum":["registries","package-managers","task-runners"]},"description":"The benchmark."},{"name":"scenario","in":"path","required":true,"schema":{"type":"string"},"description":"A scenario published by the run, e.g. `clean` or `cache+lockfile`. /api/v1/catalog lists them."},{"name":"date","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"A published run; absent means the latest. An unpublished date is a 400."},{"name":"fixture","in":"query","required":false,"schema":{"type":"string"},"description":"One fixture; absent means all of them. One the scenario did not publish is a 400."},{"name":"range","in":"query","required":false,"schema":{"type":"integer","enum":[30,60,90,120],"default":30},"description":"Trend window: this many calendar days ending at the run."},{"name":"from","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"Exact trend window start; with `to`. Both must be published dates, less than 120 days apart."},{"name":"to","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"Exact trend window end; no later than the run."},{"name":"metric","in":"query","required":false,"schema":{"type":"string","enum":["total","change","baseline","per-package"],"default":"total"},"description":"What the trend holds. Total time is the measurement; the others are derived."},{"name":"exclude","in":"query","required":false,"schema":{"type":"string"},"description":"Runs taken out of every trend, comma-separated: `YYYY-MM-DD` or `tool@YYYY-MM-DD`."}],"responses":{"200":{"description":"The report.","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"No such page.","content":{"text/markdown":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"}}}}},"Runs":{"type":"object","required":["latest","dates"],"properties":{"latest":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"dates":{"type":"array","items":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}}},"Catalog":{"type":"object","required":["latest","sections"],"properties":{"latest":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"sections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["registries","package-managers","task-runners"]},"label":{"type":"string"},"about":{"type":"string"},"tools":{"type":"array","items":{"$ref":"#/components/schemas/Named"}},"fixtures":{"type":"array","items":{"$ref":"#/components/schemas/Named"}},"scenarios":{"type":"array","items":{"type":"object","properties":{"variation":{"type":"string"},"path":{"type":"string"},"description":{"type":["string","null"]},"kind":{"type":"string","enum":["cold","partial","warm","ci","other"]},"state":{"type":["object","null"],"properties":{"cache":{"type":"boolean"},"lockfile":{"type":"boolean"},"nodeModules":{"type":"boolean"}}},"uncurated":{"type":"boolean"},"fixtures":{"type":"array","items":{"type":"string"}}}}}}}}}},"Named":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}}},"Report":{"type":"object","description":"The report model the page is drawn from. Times are seconds (per-package figures milliseconds per installed package). `finding.sentence` is the headline; `leaderboard` the ranking (mean, rsd, ratio to the baseline, sinceLastRun, fixtures, failed, version); `timeRows`/`perPackageRows` the per-fixture values with DNFs in `failed`; `trend.rows` one row per calendar day with `null` for gaps; `caveats` every note the page prints; `raw` the result files.","required":["section","scenario","run","filters","finding","leaderboard","trend","caveats","raw"],"properties":{"section":{"type":"object"},"scenario":{"type":"object"},"run":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"latest":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"isLatest":{"type":"boolean"},"dates":{"type":"array","items":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}}},"filters":{"type":"object"},"finding":{"type":"object","properties":{"sentence":{"type":"string"},"qualifier":{"type":["string","null"]}}},"stats":{"type":["array","null"]},"leaderboard":{"type":"array","items":{"type":"object"}},"timeRows":{"type":"array"},"perPackageRows":{"type":"array"},"packageCounts":{"type":"array"},"processCounts":{"type":"array"},"trend":{"type":"object"},"caveats":{"type":"object"},"raw":{"type":"array","items":{"type":"object","properties":{"fixture":{"type":"string"},"label":{"type":"string"},"href":{"type":"string"}}}},"citation":{"type":"object"}}},"History":{"type":"object","required":["section","scenario","run","metric","unit","tools","rows","runs"],"properties":{"section":{"type":"string"},"scenario":{"type":"string"},"run":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"fixture":{"type":["string","null"]},"fixtures":{"type":"array","items":{"type":"string"}},"metric":{"type":"string","enum":["total","change","baseline","per-package"]},"derived":{"type":"boolean"},"unit":{"type":"string"},"baseline":{"type":["string","null"]},"window":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"custom":{"type":"boolean"}}},"excluded":{"type":"array","items":{"type":"string"}},"tools":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","description":"One per calendar day. A tool's value is `null` when nothing comparable was published that day.","items":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"additionalProperties":{"type":["number","null"]}}},"runs":{"type":"array","description":"Each published run: its fixtures, partial means, failures, spread and per-fixture seconds.","items":{"type":"object"}},"markers":{"type":"array","items":{"type":"object"}},"outliers":{"type":"array","items":{"type":"object"}}}}}}}