Should an llms.txt for API documentation list every endpoint?

No. Agents do not need 400 endpoint URLs in an index — they need the twenty pages that explain how your API works, plus one link to the complete reference or the OpenAPI file. A flat dump of every generated endpoint page costs thousands of tokens before any prose loads, and it buries the authentication, error and versioning pages that actually prevent broken code. Group links by resource (charges, customers, payouts) and let the reference page or llms-full.txt carry the exhaustive list.

Should llms.txt link to HTML pages or to Markdown versions?

Link to whichever one returns clean content to a non-JavaScript fetcher. A Markdown twin such as /api/authentication.md is usually the better target: it is one fetch, it arrives without navigation chrome, and it is served as text/markdown. Stripe's llms.txt links to .md URLs throughout. If your documentation is client-rendered, an HTML link that returns an empty shell is worse than no link at all, so verify with curl before publishing.

Does llms.txt actually help coding agents use my API correctly?

Partly, and unevenly. The file is most useful to agent-driven developer tools that already fetch documentation when writing an integration, because it tells them which page answers which question. It does not make an agent fetch anything: a widely cited 2026 Ahrefs study of roughly 38,000 domains found 97% of llms.txt files received no requests in a month. Treat accuracy and current version numbers in your docs as the main fix, and llms.txt as the index that makes the right page easy to find once a client looks.

API Docs · September 2026

llms.txt for API Documentation

An API reference is the one site type where llms.txt has a job that pays for itself: telling a coding agent which page answers which integration question. Here is what to list, in what order, and how to keep the file small enough that an agent actually reads it.

Why API Docs Are the Exception

Most llms.txt files are aimed at a chatbot citation that may never come. Developer documentation is different, because the reader is often a program mid-task: an IDE agent, a CLI assistant or a support bot that is about to write a request against your API. When that reader gets a path wrong, the failure is expensive — a hallucinated endpoint, an SDK version pinned from training data, a webhook signature verified the old way.

That is also where adoption is concentrated. The hosted documentation platforms generate a file for every site they serve, so documentation-heavy domains are far more likely to have one than marketing sites. If you maintain an API, you are not early to this — you are behind if the file is missing.

What Belongs in an API llms.txt: Five Buckets

The mistake is treating the file as a sitemap. It is a curriculum: the shortest path from "I need to send a payment" to working code. Five buckets cover almost every API.

Auth and quickstart — one page each. Authentication first, then the fastest path to a successful first call.
Reference, grouped by resource — charges, customers, payouts. One link per resource concept, not one per method.
Errors, limits and versioning — the pages that stop an agent from retrying a 402 forever or calling a deprecated field.
Operational surfaces — webhooks and event types, idempotency, pagination, sandbox and test fixtures.
Machine-readable targets — the OpenAPI file, Markdown twins, an MCP server, a status page.

Leave out the auto-generated permalink for every endpoint, changelog archives, marketing pages and anything behind a login. The leak rules apply with extra force on API docs, where it is easy to paste an internal staging host or an admin route into a section header.

A Copyable API llms.txt

# Acme Payments API

> REST API for charges, refunds, customers and payouts. Authenticate with a Bearer secret key.

## Start here

- [Authentication](https://docs.example.com/api/authentication): Creating and rotating secret keys, and which key belongs in a browser.
- [Quickstart](https://docs.example.com/api/quickstart): First charge in five minutes, with curl and Node examples.
- [Test mode](https://docs.example.com/api/testing): Test card numbers, magic amounts and how to simulate failures.

## API reference

- [API overview](https://docs.example.com/api/reference): Request format, idempotency, pagination and versioning rules.
- [Charges](https://docs.example.com/api/charges): Create, capture, retrieve and refund a charge.
- [Customers](https://docs.example.com/api/customers): Create a customer and attach payment methods.
- [Payouts](https://docs.example.com/api/payouts): Move balances to a bank account and list payout history.

## Errors and operations

- [Error codes](https://docs.example.com/api/errors): Every error type, its HTTP status, and the retry behaviour we recommend.
- [Rate limits](https://docs.example.com/api/rate-limits): Limits per key and the headers that tell you when to back off.
- [Webhooks](https://docs.example.com/api/webhooks): Event types, signature verification and replaying failed deliveries.

## Machine-readable

- [OpenAPI 3.1 specification](https://docs.example.com/openapi.json): The full spec, generated from the same source as the reference.
- [llms-full.txt](https://docs.example.com/llms-full.txt): Every page above concatenated as Markdown, for one-shot ingestion.
- [MCP server](https://docs.example.com/mcp): Tools an agent can call instead of generating raw HTTP requests.

Four sections, thirteen links, roughly 400 tokens. Every line is a decision an agent cannot make from a URL alone — which is exactly what the description slot is for. The description guide covers how to phrase those colons if you want them quoted back accurately.

Point at Specs, Not Only at Pages

A well-run docs site has three surfaces, and the file should name all three because they serve different fetches:

Surface	Best for	Serving note
HTML page or its `.md` twin	Reading one concept	Verify the `.md` returns `text/markdown`
OpenAPI 3.1 file	Generating request code	Serve it at a stable URL, no auth
MCP server	Calling instead of writing	Announce the endpoint; it is not discovery by itself

Resend's file is a clean example of this layering: the five sections include a "When to use Resend" block that names the actual endpoints, then links to the OpenAPI spec, an official CLI, an MCP server and discovery manifests. It is under 8 KB and answers the first three questions a coding agent asks. The mechanics of an MCP announcement live in the llms.txt vs MCP comparison.

The Hidden Slot: Instructions Before the First H2

Everything between the H1 and the first ## is free text, and most sites use it for one summary line. Some API teams use it for hard rules. Stripe's file — fetched September 26, 2026, served as text/markdown, about 92 KB — opens with plain paragraphs instead of a blockquote, telling agents to check the npm registry rather than pin a memorised SDK version, and which sandbox to use for which workflow.

That is a deliberate trade: it spends the file's most-read real estate on the two mistakes that break the most integrations. If your support queue is full of the same agent-generated bug — deprecated parameter, wrong environment, missing idempotency key — that is the paragraph to write. Keep it short: this is a notice board, not documentation.

Size: Page-Level or Endpoint-Level?

Stripe's file runs 453 links across 26 sections, and Mintlify's documentation index shows the other strategy — one section collapses an entire 183-page manual into a single Markdown link. Both work, and the choice comes down to what a fetch costs:

Under ~40 pages — one flat list, one link per concept, no nesting.
40–500 pages — group by product or resource, one or two levels deep, and let the largest sets collapse into a single index page.
Every endpoint — that belongs in llms-full.txt or the OpenAPI file, not in the index. Four hundred lines at ~12 tokens each is a 5,000-token tax on every fetch.

The split between a curated index and a full dump is covered in llms.txt vs llms-full.txt; API docs are the case where shipping both is usually correct.

Verify the Fetch, Then Verify the Links

API docs fail llms.txt in a specific way: the file is fine, the targets are not. A reference page that only renders in the browser returns an empty shell; a versioned docs URL from a previous release 404s after a rewrite. Three commands catch nearly all of it.

# 1. how the file itself is served
curl -sI https://docs.example.com/llms.txt

# 2. every link answered, with its status
curl -s https://docs.example.com/llms.txt \
  | grep -o 'https://[^)]*' \
  | while read u; do echo "$(curl -o /dev/null -s -w "%{http_code}" "$u") $u"; done

# 3. the way a Markdown-fetching client sees a target page
curl -s -H "Accept: text/markdown" https://docs.example.com/api/errors.md | head -5

Expect 200 and text/plain or text/markdown on the file, no redirect chain, a status list with nothing but 200s, and a Markdown target whose first line is a heading rather than an empty body. Generate a spec-compliant starting point with the llms.txt generator, then run the production URL through the llms.txt checker before you add another link.