Ingest API

• Base path /api/v1. All requests and responses are JSON.
• Two resources, projects and their benchmarks. Both writes are upserts keyed on slug: POST the same slug again to update in place.
• There is intentionally no delete endpoint. Deletion is a human, UI-only action; the API can only create, update, and read.
• Every benchmark spec is validated against the component whitelist before storage. Nothing partial is ever persisted.

Authenticate with a Hub-issued API key sent as a Bearer token on every request:

Authorization: Bearer <your-api-key>

The key is an opaque random token; the Hub stores only its SHA-256 hash, so a database read can never reconstruct a live credential. A missing or unrecognized token returns 401. Keys belong to one of two account types, library (automated publishers) or human, which the authorization rules below distinguish.

Authorization is enforced server-side per request. The rules:

This is a small, trusted set of key-holders by design: every human is an admin, and there is no per-owner isolation between library keys beyond the ownership check on update. A write you aren't allowed to make returns 403.

{project}in a path is the parent project's slug.

Request bodies are strict; any unexpected key is rejected with a 422. A ? marks an optional field.

Errors use conventional HTTP status codes and a JSON body with a message. Validation failures (422) additionally carry an errors array of issues, each pointing at the offending path.

A 422 from a spec that fails whitelist validation looks like:

{
  "message": "invalid render spec",
  "errors": [
    { "code": "custom", "path": ["3", "rows", 2],
      "message": "row 2 has 4 cells but there are 3 headers" }
  ]
}

• Request body: up to 8 MB. A larger declared Content-Length is rejected with 422 before parsing.
• Spec size: up to 2000 top-level nodes.
• Nesting depth: layout containers (row, columns, tabs) may nest up to 32 levels deep.
• Images: src must be an http(s):// URL or a data:image/URI, up to 5 MB of characters.
• Per-field caps (string lengths, array sizes) are listed with each node in the whitelist below.

A spec is a JSON array of nodes. Each node is an object discriminated on a literal type. Only the types below are accepted; any other type, or any extra key on a node, is rejected. There is no raw-HTML or script node; this whitelist is the injection boundary.

Fields marked ?are optional; every default shown is what the Hub applies when the field is omitted. Charts enforce cross-field consistency (e.g. a line series' x and y must be the same length) and report a 422 pointing at the mismatch.

The same publish flow: create a project, then publish a benchmark into it.

cURL

# 1. Register (or update) the pair-project. You own any slug you create.
#    One project per hardware × model pair.
curl -X POST https://benchmark.infinity.inc/api/v1/projects \
  -H "Authorization: Bearer $HUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug":"apple-m2-whisper","name":"Apple M2 · Whisper",
       "hardware":"Apple M2","model":"Whisper"}'

# 2. Publish a run as a new benchmark. Its spec is validated before storage.
curl -X POST https://benchmark.infinity.inc/api/v1/projects/apple-m2-whisper/benchmarks \
  -H "Authorization: Bearer $HUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "20260709-181500-fp16",
    "name": "2026-07-09 18:15 · fp16",
    "hardware": "Apple M2 · 16 GB · macOS 15",
    "spec": [
      {"type": "header", "text": "MLX Whisper vs baselines", "level": 1},
      {"type": "kpi_row", "metrics": [
        {"label": "tok/s", "value": "142", "delta": "+18%", "delta_direction": "up"}]},
      {"type": "bar_chart", "categories": ["mine", "llama.cpp"],
       "series": [{"name": "tok/s", "values": [142, 120]}]}
    ]
  }'

TypeScript SDK

@infinity/benchmark-hub-client ships a fluent SpecBuilder (type-checked against this whitelist) and a dependency-free HubClient.

import { SpecBuilder, HubClient } from "@infinity/benchmark-hub-client";

const spec = new SpecBuilder()
  .header("MLX Whisper vs baselines", 1)
  .kpiRow([{ label: "tok/s", value: "142", delta: "+18% vs llama.cpp", delta_direction: "up" }])
  .barChart(["mine", "llama.cpp"], [{ name: "tok/s", values: [142, 120] }])
  .roofline(7000, 400, [{ label: "gemm", intensity: 40, performance: 3800 }])
  .validate(); // optional: fail locally against the whitelist before publishing

const hub = new HubClient("https://benchmark.infinity.inc", process.env.HUB_API_KEY!);

await hub.publishProject("apple-m2-whisper", "Apple M2 · Whisper", {
  hardware: "Apple M2", model: "Whisper",
});
await hub.publishBenchmark(
  "apple-m2-whisper", "20260709-181500-fp16", "2026-07-09 18:15 · fp16",
  spec, "Apple M2 · 16 GB · macOS 15",
);

Python

Publishers on ML hardware don't need the SDK; the API is plain HTTP. Build the spec as a list of dicts and POST it.

import os, httpx

HUB = "https://benchmark.infinity.inc"
h = {"Authorization": f"Bearer {os.environ['HUB_API_KEY']}",
     "Content-Type": "application/json"}

httpx.post(f"{HUB}/api/v1/projects", headers=h,
           json={"slug": "apple-m2-whisper", "name": "Apple M2 · Whisper",
                 "hardware": "Apple M2", "model": "Whisper"})

spec = [
    {"type": "header", "text": "MLX Whisper vs baselines", "level": 1},
    {"type": "kpi_row", "metrics": [
        {"label": "tok/s", "value": "142", "delta": "+18%", "delta_direction": "up"}]},
    {"type": "bar_chart", "categories": ["mine", "llama.cpp"],
     "series": [{"name": "tok/s", "values": [142, 120]}]},
]
httpx.post(f"{HUB}/api/v1/projects/apple-m2-whisper/benchmarks", headers=h,
           json={"slug": "20260709-181500-fp16", "name": "2026-07-09 18:15 · fp16",
                 "spec": spec, "hardware": "Apple M2 · 16 GB · macOS 15"})