Versioning

We version the API in the URL — the major version is in the path, not in a header. This makes it impossible to accidentally call the wrong version, and easy to grep for in your codebase.

Scheme

The base URL is:

v1 is the current and only major version. Inside a major version we ship additive minor changes continuously — new endpoints, new response fields, new optional parameters — without bumping the version number.

What can change without notice

• New endpoints — added under /v1/.
• New response fields — additive only. Always read JSON with a schema that ignores unknown fields (default in Python's json.loads, JSON.parse, Go's encoding/json).
• New optional query parameters — never required.
• Error message text — wording. Codes stay stable.
• Cache TTLs — may be tuned (always reflected in Cache-Control).
• Internal performance — response times, edge-cache footprint.

What counts as breaking

• Removing an endpoint, a response field, or an error.code.
• Renaming any of the above.
• Changing the type of a field (e.g. integer → string).
• Changing required parameters.
• Changing the meaning of a field (e.g. switching updatedAt from milliseconds to seconds).
• Changing the HTTP status for an existing error.code.

Anything in this list triggers a major-version bump (v2, etc.) and a deprecation period for v1.

Deprecation policy

• Major versions are supported for at least 18 months after the next major ships.
• Individual endpoints or fields within a major may be deprecated with a minimum 6 months notice.
• Deprecated calls keep working for the entire notice period — they just emit signal headers (see below) and a notice in the changelog.

Detecting deprecation

Deprecated endpoints set two RFC-standard response headers:

We strongly recommend logging any response with a non-empty Sunset header. The minimum 6-month buffer is plenty to plan a migration if you notice it on day one.

# Print every response header so you can grep for Sunset / Deprecation
# in your monitoring pipeline.
curl -sSI https://api.suprabench.com/v1/models \
  -H "Authorization: Bearer $SUPRABENCH_KEY" | grep -Ei 'sunset|deprecation|link'

r = requests.get(...)
sunset = r.headers.get("Sunset")
if sunset:
    log.warning("SupraBench endpoint deprecated; sunset=%s, see %s",
                sunset, r.headers.get("Link"))

const r = await fetch(url, { headers: { Authorization: `Bearer ${KEY}` } });
const sunset = r.headers.get("Sunset");
if (sunset) {
  console.warn(
    `SupraBench endpoint deprecated; sunset=${sunset}, see ${r.headers.get("Link")}`
  );
}

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
if sunset := resp.Header.Get("Sunset"); sunset != "" {
    log.Printf("SupraBench endpoint deprecated; sunset=%s, see %s",
        sunset, resp.Header.Get("Link"))
}

Future versions

We don't bump major versions for fun. v2 will only happen if we genuinely need to change the contract — for example, switching from limit-based to mandatory cursor-based pagination across all list endpoints. We'll announce intent in the changelog and email all active subscribers at least 90 days before v2 beta.