ModelRefs / API Reference
API Reference
Reference for the ModelRefs Evidence API: authentication, the coverage and evidence endpoints, response shape, every error code and the rate-limit headers.
Base URL and authentication
https://vmwgrcnqpavfrwrxsinx.supabase.co/functions/v1/evidence-apiSend the key as a bearer token. Keys are created on the API keys page and shown once, because only a SHA-256 hash and a short prefix are stored. A key that is lost has to be revoked and replaced rather than recovered.
Authorization: Bearer mr_live_...The coverage endpoint is the exception and needs no key. Every other request is authenticated and counts against the monthly allowance.
Endpoints
GET /v1/coverage
No key required. Every model slug ModelRefs holds governed evidence for, plus the size of the catalogue. Call it before iterating a model list so requests are spent only on models that have evidence.
GET /v1/models/{slug}/evidence
Requires a key. A model's citations and governed benchmark runs. Each run carries its source, publisher, claim scope and methodology limitations, so a score never travels without the conditions under which it holds.
curl -H "Authorization: Bearer $MODELREFS_KEY" \
https://vmwgrcnqpavfrwrxsinx.supabase.co/functions/v1/evidence-api/v1/models/gpt-4/evidenceResponse shape
An evidence response carries the model, its citations, its governed runs, and a disclosure block stating the scope of what is returned. The last three fields on a run are the point of the product: a score without its methodology limitations and claim scope is a number that reads as authoritative and cannot be defended.
{
"model": { "slug": "gpt-4", "name": "GPT-4" },
"evidence": {
"citationCount": 3,
"governedRunCount": 5,
"citations": [{
"claim": "...", "claimType": "...",
"confidence": 0.82, "authorityScore": 0.9,
"sources": [{ "title": "...", "publisher": "...", "url": "...",
"publishedAt": "...", "retrievedAt": "...", "strength": "..." }]
}],
"governedRuns": [{
"benchmark": "gpqa-diamond", "score": 91.9, "scoreUnit": "%",
"modelVersion": "...", "benchmarkVersion": "...",
"sourceUrl": "...", "publisher": "...", "claimScope": "...",
"methodologySummary": "...",
"methodologyLimitations": "...",
"contaminationRiskNote": "..."
}]
},
"disclosure": { "scope": "...", "coverage": "..." },
"plan": "free"
}Responses
| Status | Meaning | What to do |
|---|---|---|
| 200 | Evidence returned. | Read evidence.citations and evidence.governedRuns. |
| 401 missing_api_key | No Authorization header was sent. | Send Authorization: Bearer followed by your key. |
| 401 invalid_api_key | The key is unknown, revoked, or inactive. | Check it has not been revoked on your API keys page. |
| 404 no_evidence_for_model | ModelRefs holds no governed evidence for that model. | This describes our coverage, not the model. Check /v1/coverage first. |
| 429 monthly_quota_exceeded | The allowance for this month is spent. | The body carries limit, used and resets. Retry after the reset, or raise the plan. |
| 503 auth_unavailable | Key verification could not run. | Transient. Retry with backoff. |
Rate limiting
Allowances are per account and reset on the first of each month, UTC. The free tier is 1,000 calls a month. Metering fails open: if the counter cannot be read the request is served rather than refused, because a reference layer that goes dark on its own bookkeeping is worse than one that over-serves briefly.
| Header | Meaning |
|---|---|
| X-RateLimit-Limit | The monthly allowance. |
| X-RateLimit-Remaining | Calls left this month. |
| X-RateLimit-Reset | ISO timestamp at which the allowance resets, being the first of next month, UTC. |
| X-ModelRefs-Plan | The plan the allowance was derived from. |
| Retry-After | On 429 only: seconds until the reset. |
Looking for benchmark scores?
This page previously carried a small table of benchmark numbers with no source, date or claim scope attached. Those have been removed rather than left to look authoritative. The 123 governed runs, each with its source, claim scope and methodology limits, are published on the benchmark pages and returned through this API.