Quickstart

From zero to your first authenticated request in under five minutes.

Last updated: April 25, 2026 Reading time: 3 min
Heads up: /v1/ is live today, but only for invite-only Partner keys (non-profit / research / open-source). Self-serve paid tiers (Starter / Pro / Enterprise) are demand-gated; the Stripe + key-creation flow described below ships once the waitlist hits launch threshold. Until then, paid Subscribe CTAs put you on the waitlist instead. Partner applicants follow a different path — see Overview.

1. Subscribe and create a key

  1. Sign in to suprabench.com with Google.
  2. Open Profile → API & Billing.
  3. Pick a tier and click Subscribe — you'll be sent to Stripe Checkout.
  4. After payment you'll land back on the dashboard. Click Create new key, give it a descriptive name (e.g. laptop-dev), copy the value once.
The key is shown exactly once. Store it in a password manager or your shell's .env file immediately. If you lose it, revoke and create a new one — we cannot recover plaintext.

2. Make your first request

Fetch the top 5 ranked models:

export SUPRABENCH_KEY="sb_live_…"

curl "https://api.suprabench.com/v1/models?limit=5" \
  -H "Authorization: Bearer $SUPRABENCH_KEY"
import os
import requests

API = "https://api.suprabench.com/v1"
KEY = os.environ["SUPRABENCH_KEY"]

resp = requests.get(
    f"{API}/models",
    params={"limit": 5},
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=10,
)
resp.raise_for_status()
for model in resp.json():
    print(f"{model['name']:30s} {model['supraScore']:6.2f}")
const API = "https://api.suprabench.com/v1";
const KEY = process.env.SUPRABENCH_KEY;

const r = await fetch(`${API}/models?limit=5`, {
  headers: { Authorization: `Bearer ${KEY}` },
});
if (!r.ok) {
  const err = await r.json();
  throw new Error(`${err.error.code}: ${err.error.message}`);
}
const models = await r.json();
for (const m of models) {
  console.log(`${m.name.padEnd(30)} ${m.supraScore.toFixed(2)}`);
}
package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

type Model struct {
    Name       string  `json:"name"`
    SupraScore float64 `json:"supraScore"`
}

func main() {
    req, _ := http.NewRequest("GET",
        "https://api.suprabench.com/v1/models?limit=5", nil)
    req.Header.Set("Authorization", "Bearer "+os.Getenv("SUPRABENCH_KEY"))
    resp, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()

    var models []Model
    json.NewDecoder(resp.Body).Decode(&models)
    for _, m := range models {
        fmt.Printf("%-30s %6.2f\n", m.Name, m.SupraScore)
    }
}

Expected response

[
  {
    "slug": "claude-opus-4-7",
    "name": "Claude Opus 4.7",
    "provider": "Anthropic",
    "familyTag": "claude",
    "tags": ["reasoning", "coding", "long-context"],
    "supraScore": 92.41,
    "benchCount": 28,
    "updatedAt": 1745000000000
  },
  // … 4 more
]

3. Filter by tag

Want only models good at coding? Pass ?tag=coding. Tags come from the public taxonomy; list them with GET /v1/tags. 

curl "https://api.suprabench.com/v1/models?tag=coding&limit=10" \
  -H "Authorization: Bearer $SUPRABENCH_KEY"
coding = requests.get(
    f"{API}/models",
    params={"tag": "coding", "limit": 10},
    headers={"Authorization": f"Bearer {KEY}"},
).json()
const params = new URLSearchParams({ tag: "coding", limit: "10" });
const r = await fetch(`${API}/models?${params}`, {
  headers: { Authorization: `Bearer ${KEY}` },
});
const coding = await r.json();
req, _ := http.NewRequest("GET",
    "https://api.suprabench.com/v1/models?tag=coding&limit=10", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SUPRABENCH_KEY"))
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var coding []Model
json.NewDecoder(resp.Body).Decode(&coding)

4. Drill into one model

Get the full per-bench breakdown for any model by slug:

curl https://api.suprabench.com/v1/models/claude-opus-4-7 \
  -H "Authorization: Bearer $SUPRABENCH_KEY"
detail = requests.get(
    f"{API}/models/claude-opus-4-7",
    headers={"Authorization": f"Bearer {KEY}"},
).json()
for s in detail["scores"]:
    print(f"{s['benchName']:25s} {s['normalizedScore']:6.2f}")
const r = await fetch(`${API}/models/claude-opus-4-7`, {
  headers: { Authorization: `Bearer ${KEY}` },
});
const detail = await r.json();
for (const s of detail.scores) {
  console.log(`${s.benchName.padEnd(25)} ${s.normalizedScore.toFixed(2)}`);
}
req, _ := http.NewRequest("GET",
    "https://api.suprabench.com/v1/models/claude-opus-4-7", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SUPRABENCH_KEY"))
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var detail struct {
    Scores []struct {
        BenchName       string  `json:"benchName"`
        NormalizedScore float64 `json:"normalizedScore"`
    } `json:"scores"`
}
json.NewDecoder(resp.Body).Decode(&detail)
for _, s := range detail.Scores {
    fmt.Printf("%-25s %6.2f\n", s.BenchName, s.NormalizedScore)
}

Returns the full ModelDetail object with one entry per benchmark the model has scores for, plus raw and normalized scores, source URL, accessed-at timestamp, and community vote tallies.

5. Handle errors

Always check the status. SupraBench errors include both a human message and a stable machine code:

{
  "error": {
    "code": "rate_limited",
    "message": "> 60 req/min",
    "hint": "Slow down or upgrade tier."
  }
}

Branch on error.code in your code, never on the message text (messages may be reworded; codes are stable). Full reference: Errors →.

What's next

Previous ← Overview