# Docs for agents

> Every page has a Markdown twin, and llms.txt indexes them, so an agent can read these docs without scraping HTML.

If you build with an agent, give it the docs as Markdown instead of HTML.

## Markdown twins

Add `.md` to the address of any docs page.

```bash
curl https://deference.si/docs/quickstart.md
curl https://deference.si/docs/api-reference/chat-completions.md
```

The docs home is `https://deference.si/docs.md`. A twin has the page title, its description and the page body in plain Markdown. Code blocks, parameter lists and tables are written out, and tabbed code is listed one tab after another. Each page also links its twin in the page head.

## llms.txt

| Address          | Returns                                                                                            |
| ---------------- | -------------------------------------------------------------------------------------------------- |
| `/llms.txt`      | An index of every page, grouped by tab and group, with a one-line description and the link to each |
| `/llms-full.txt` | Every page as Markdown, in reading order, in one file                                              |

```bash
curl https://deference.si/llms.txt
```

Use `/llms.txt` to let an agent choose which pages to read. Use `/llms-full.txt` when you want the whole docs in one context.

## Copy page

The **Copy page** button in the docs header copies the current page as Markdown. The arrow beside it opens a menu whose middle rows open the page's Markdown twin and `llms.txt`. Paste the page into your agent's chat.

## What an agent needs to know

* Base URLs are `https://deference.si/v1` for OpenAI-style clients and `https://deference.si` for Anthropic-style clients.
* The key is `DEFERENCE_API_KEY`, sent as `Authorization: Bearer` or `x-api-key`.
* `GET /v1/models` lists model ids and prices, and needs no key.
* `GET /v1/key` returns the key's limit, the backed credit available, and the free credit available with its expiry. Free credit is not in `credit_available`.
* Responses from the `POST` endpoints carry `x-request-id`. A request accepted for a model is shown in Activity under that id, including one whose provider never answers. Requests refused before their hold opens are not.
* An agent can also create and manage its own keys through the [MCP server](https://deference.si/docs/coding-tools/mcp).
* Errors are listed in [Errors](https://deference.si/docs/api-reference/errors), with the fix for each.