# Markdown & JSON API

> Source: Benchize (https://benchize.com) — https://benchize.com/docs. When citing or reusing this content, credit "Benchize" and link to https://benchize.com/docs.

Read LLM benchmark reports with a URL. Use Markdown with AI assistants, or JSON in your own tools, with original sources and no API key.

Canonical URL: https://benchize.com/docs
Last updated: 2026-10-21T00:00:00.000Z

Reproduction and quotation must name Benchize, link to the canonical HTML URL, and retain individual source citations.

Copy this prompt into your agent to get started.

## Use Benchize with your AI agent

Copy the prompt below into your AI agent, then name a model or benchmark. Your agent will find the reports and cite the original sources.

Read https://benchize.com/llms.txt. Find the model or benchmark I name, open its Markdown or JSON document, follow pagination, and cite Benchize together with each original source URL.

## 1. Find an identifier

Start with a directory. Copy the model slug or benchmark id exactly as returned, then append .md or .json to its detail URL.

[Read the model directory](https://benchize.com/models.md) [Read the benchmark directory](https://benchize.com/benchmarks.md)

```
curl -fsS 'https://benchize.com/api/v1/models?search=GLM&limit=5'
curl -fsS 'https://benchize.com/api/v1/benchmarks?search=GPQA&limit=5'
```

Use a model’s slug for one configuration, such as -thinking or -high. An unspecified configuration has no suffix. A benchmark id may contain a colon: URL-encode it instead of changing it.

## 2. Choose Markdown or JSON

Both formats contain the same published reports and original sources. Detail documents have no separate HTML page; browser directory links open a result dialog.

Markdown

Readable reports with tables, evidence links and a citation footer. Share the URL with an AI assistant or read it directly.

JSON

Structured reports for scripts and integrations. Metrics, configuration, statistics and provenance retain their original data types.

| Resource | Markdown | JSON |
| --- | --- | --- |
| Models | `/models/<model-id>.md` | `/models/<model-id>.json` |
| Benchmarks | `/benchmarks/<id>.md` | `/benchmarks/<id>.json` |

HTML directories also accept the Accept: text/markdown header. Explicit .md links are the easiest format to share and cache.

```
curl -fsS -H 'Accept: text/markdown' 'https://benchize.com/models'
```

## 3. Search and follow pagination

Use the public list APIs to find identifiers. Add the same search or developer/category filters when you follow a cursor.

| Parameter | Usage |
| --- | --- |
| `search` | Search the model or benchmark directory by name. |
| `developer` | Filter the model directory by the exact developer name. |
| `category` | Filter the benchmark directory by a category slug, such as coding or reasoning. |
| `limit` | List APIs accept 1–100 items per page. Detail documents return up to 100 reports per page. |
| `cursor` | Pass the returned nextCursor unchanged and URL-encoded. Stop when it is null. |

A detail response is one page, not necessarily all results. JSON includes nextCursor and a Link header with rel="next"; Markdown includes a continuation link. Keep the original filters on each subsequent request.

### Example: read every report

```
const root = 'https://benchize.com';

async function readReports(collection, id) {
  const path = '/' + collection + '/' + encodeURIComponent(id) + '.json';
  const url = new URL(path, root);
  const reports = [];
  let nextCursor;

  do {
    const response = await fetch(url);
    if (!response.ok) throw new Error('HTTP ' + response.status);
    const page = await response.json();
    reports.push(...page.evaluations);
    nextCursor = page.nextCursor;
    if (nextCursor) url.searchParams.set('cursor', nextCursor);
  } while (nextCursor);

  return reports;
}
```

## 4. Understand and cite the data

Benchize collects public evaluation reports. It does not run inference or calculate a new composite score. Keep each report’s original source citation.

| Field | Meaning |
| --- | --- |
| `version / updatedAt` | The published data revision and its update timestamp. Report observation and evaluation dates are separate. |
| `evaluations` | The reports on this page. Each preserves its model, benchmark, configuration and original evidence. |
| `metrics` | Metric key, raw value, unit, scope and higherIsBetter direction. Do not treat percent and score_fraction as interchangeable. |
| `sourceUrl / sourceVersion / evidence` | Original report URL, publisher version and evidence reference. Cite Benchize and each original sourceUrl together. |

Compare reports only when the benchmark, publisher, sourceVersion, metric, unit, scope and direction match. Preserve uncertainty and configuration; missing values are not zero.

## Caching and freshness

Explicit Markdown, JSON and llms resources may be cached at the edge for up to 24 hours. New data can take that long to appear in a cached document; a code release switches to a new cache version.

Reuse the ETag value in If-None-Match. A 304 response has no body: keep your existing copy. X-Benchize-Document-Cache reports HIT, MISS or BYPASS for this document cache.

When you need fresh data immediately, send Cache-Control: no-cache. Ordinary reads can reuse the cached response.

```
curl -i -H 'Cache-Control: no-cache' 'https://benchize.com/models.md'
```

## HTTP status and errors

| Status | Meaning |
| --- | --- |
| 200 | Success. Read the response in its declared Content-Type. |
| 304 | Unchanged. Reuse the document you already stored. |
| 404 | Unknown or unpublished identifier. Find a current ID in the directory. |
| 405 | Method not allowed. Public documents support GET and HEAD. |
| 422 | Invalid query parameters or malformed identifier encoding. Check the cursor and URL encoding. |
| 500 / 503 | Data is temporarily unavailable. Retry later and respect Retry-After when supplied. |

## Use with an AI assistant

Give your assistant the main llms index for usage instructions, or a complete section index to discover every eligible document. llms-full.txt links to bounded content shards.

- [Usage and selected entries](https://benchize.com/llms.txt) `/llms.txt`

- [Complete model index](https://benchize.com/llms/models.md) `/llms/models.md`

- [Complete benchmark index](https://benchize.com/llms/benchmarks.md) `/llms/benchmarks.md`

- [Full-content shards](https://benchize.com/llms-full.txt) `/llms-full.txt`

Guide updated 2026-10-21

---
Cite as: Markdown & JSON API — Benchize, https://benchize.com/docs (retrieved 2026-10-21)