# The API

Updated November 1, 2026.

Every answer clickd 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 and agents.

> **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](https://clickd.com/docs/tools).

## 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, sign its person up with `mttr_signup`, and read what the website shows anyone: the rulebook, the leaderboard, a site’s public report and the free checks, 60 calls an hour from one address. Everything else needs a key.

## Asking

```
curl https://clickd.com/api/v1/sites/example.com \
  -H "Authorization: Bearer $CLICKD_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 an argument is missing |
| `401` | Visits were sent without the site’s visits key. Over MCP a call with no key is not a 401: a tool open to anyone answers, and any other answers with isError and says to sign up |
| `403` | The key does not reach that call, or the site was removed from clickd |
| `404` | The site was never read or is not yours, there is no such call, or no key was sent. Without a key the API says nothing more, not even that a call exists |
| `405` | The call needs another method, such as POST for a fresh read |
| `409` | It cannot be done yet, such as a claim whose record or file is not found, or a brief whose page is not live |
| `413` | The body is too large |
| `422` | The page was read but lacks what the check needs, and the reply says what |
| `429` | Too many at once, or a read asked for too soon; the reply says when to try again |
| `502` | clickd could not reach the site to read it; the reply says why |
| `503` | This server cannot do that, such as sending a link when it signs none |

## 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.

## Sources

- [RFC 6750: Bearer token usage](https://www.rfc-editor.org/rfc/rfc6750), IETF: How a key is sent as a bearer token.
- [Model Context Protocol specification](https://modelcontextprotocol.io/specification/2025-06-18), Model Context Protocol: The protocol the tools at /mcp are served over.
- [OpenAPI Specification 3.1.0](https://spec.openapis.org/oas/v3.1.0), OpenAPI Initiative: The format of the reference at /docs/openapi.json.