Reference2 min readUpdated October 24, 2026

The API

Every answer mttr gives is JSON under /api/v1, and the MCP tools at /mcp are written on top of it. The same figures a person sees, for scripts, releases and agents.

This page as Markdown

Every call, in full

The API reference at /docs/reference lists every call with its arguments, who may make it, and an example to copy, and lets you try each one with your key. It is also at /docs/reference.md for an agent and /docs/openapi.json for anything that reads OpenAPI.

How do I call the API?

Send your key as a bearer token to an address under /api/v1, such as /api/v1/sites/example.com for a site’s latest read. Every reply is JSON, and a site is named by its domain. To read what one tool is for before its arguments, each has a page of its own.

Keys

A key starts mk_ and is shown once, when it is made. It reaches the sites you have claimed, their reads and jobs, your account and the rulebook. With no key, an agent may list the tools over MCP and sign its person up with mttr_signup, and nothing else.

Asking

Example

curl https://mttr.si/api/v1/sites/example.com \
  -H "Authorization: Bearer $MTTR_KEY"

Calls

Call	What it returns
`GET /rules`	Every rule, with its stage, weight and fix
`GET /sites`	The sites read, 25 at a time, sorted by score unless `sort` says otherwise
`GET /sites/{site}`	The latest read: score, stages, and every fix with the pages failing it
`GET /sites/{site}/brief`	The fix list as Markdown, to hand to an agent
`GET /sites/{site}/plan`	The fixes worth the most as steps, each with its pages and points, and the words to hand an agent
`GET /sites/{site}/citations`	What assistants were found to cite, question by question, and the credits left
`GET /sites/{site}/pages`	Every page read, with its status, depth, words and failing rules
`GET /sites/{site}/changes`	What the latest read changed against the one before
`GET /sites/{site}/compare?with={other}`	Two sites rule by rule; add `view=content` to set their pages side by side by meaning
`GET /sites/{site}/competitors`	Sites near it doing similar work, and similar sites elsewhere
`GET /sites/{site}/tells`	Pages with signs of generated text, such as hidden characters
`POST /sites/{site}/rescan`	Puts the site in line to be read again, with an optional `reason`

Two rules every reply keeps

A score never travels without what it does not mean: every reply that carries one carries caveat, which says “A score says pages are well formed. It does not say an assistant cites the site.”
Words that came from a scanned site travel only under a key that says so, such as quoted, so a site cannot steer the agent that is fixing it.

Errors

Status	When
400	The address cannot be read, such as a private one, or a field is missing
403	The site was removed from mttr and is not read
404	The site was never read, or there is no such call
405	The call needs another method, such as POST for a fresh read
429	Too many at once, or a read asked for too soon; the reply says when to ask again

Limits

A site is read at most once every 10 minutes, whoever asks.
A key asks for fresh reads of sites it has not claimed within an hourly allowance. Reports already kept are not limited, and a claimed site is read whenever it is asked for.
The free checks of one page, such as the product check, share the free tools’ hourly allowance for each key.