API & webhooks

curl https://llmroster.dev/api/v1/roster.json

curl -X POST https://llmroster.dev/api/v1/subscriptions \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com/hooks/llmroster", "events": ["model.became_paid"]}'

What the roster returns

The payload is derived from the same snapshot as this site, so it cannot drift from the tables. generated_at tells you how fresh it is.

endpoints

A model can be callable on more than one provider, and the id differs between them. Use endpoints[].model_id with endpoints[].base_url rather than assuming the normalized id works everywhere.

Known base URLs:

• nous — https://inference-api.nousresearch.com/v1
• opencode-zen — https://opencode.ai/zen/v1
• openrouter — https://openrouter.ai/api/v1

benchmarks

Webhooks

A webhook is an HTTPS endpoint we POST to when something changes. You choose the event types; each event is delivered per model rather than as a batch.

What a delivery looks like

{"at": "2026-09-29T18:00:00Z", "attempt": 1, "data": {"last_seen_free": "2026-09-20T00:00:00Z", "model_id": "z-ai/glm-5.2", "name": "GLM 5.2", "pricing": {"completion": 1.1e-06, "prompt": 4e-07}, "source": "openrouter"}, "id": "3f9c1a7be2d04c85", "type": "model.became_paid"}

data carries the fields relevant to the event type. model.became_paid includes pricing, which is the observed price that caused the transition.

Verifying a delivery

Every delivery is signed. Compute the signature over the timestamp and the body exactly as received — the timestamp is inside the signed material, so a captured delivery cannot be replayed with a fresh one.

expected = "sha256=" + hmac.new(
    secret.encode(),
    timestamp.encode() + b"." + body_bytes,
    hashlib.sha256).hexdigest()

Use hmac.compare_digest rather than == to compare. Reject anything whose timestamp is older than a few minutes.

X-Roster-Event: model.became_paid
X-Roster-Timestamp: 1790714400
X-Roster-Delivery: 42
X-Roster-Signature: sha256=...

X-Roster-Delivery is the id of the delivery attempt and is useful for deduplicating on your side: one event can be delivered more than once if a retry happens.

Limits and rules

• Reads are anonymous and rate limited to 30 requests per minute per address, with a burst. Exceeding it returns 503, not 429, so it is not confused with a rate-limit page from a proxy in front of the site.
• Registration is limited to 10 requests per minute per address and to 5 active subscriptions per address, because each attempt costs us an outbound request to your endpoint.
• Endpoints must be https and publicly routable. Loopback, private ranges, cloud metadata addresses and IPv4-mapped IPv6 forms of them are refused.
• Retries are bounded. A delivery is retried with backoff, and a subscription that keeps failing is disabled rather than retried forever.

Verifying you control an endpoint

Before a subscription is created we POST a challenge containing a random token in the X-Roster-Challenge header. Your endpoint must return 2xx and include that token in the response body. This is what stops our service being used to send unwanted traffic to an address you do not control.

{
  "type": "endpoint.verification",
  "challenge": "<token sent in X-Roster-Challenge>"
}

A response of 200 that does not echo the token is refused. If you need the challenge and a real delivery to be distinguishable, the presence of the header tells them apart.

The secret is returned exactly once, in the 201 response to registration. It is not sent again and not recoverable afterwards. Store it before you discard the response.

Questions or corrections: contact page.