Sourced*

Agents

How to implement llms.txt for an API company

· 6 min read · Sourced

  • llms-txt
  • api-docs
  • openapi
  • implementation
  • agents

An API company's llms.txt needs five sections most sites don't bother with: Quickstart, Authentication, API reference (linked per endpoint group), SDKs, and Optional. That structure exists because a coding agent reading your llms.txt is about to write code that calls your API, not browse your product — it needs auth and a request shape fast, not a mission statement. This post is the implementation companion to our earlier llms.txt overview: where that post explains what llms.txt is and why it matters, this one covers exactly what to put in one for an API, how to generate it from your OpenAPI spec instead of writing it by hand, and how to validate it before you ship.

The five sections that work for an API

Per Sourced's llms.txt-for-API-docs reference, these five hold up across API shapes:

  1. ## Quickstart — link to your getting-started page, with one request/response snippet per SDK language.
  2. ## Authentication — the auth flow (bearer, OAuth, API key) in three sentences, plus a link to the full auth reference. An agent that picks the wrong auth header on its first call wastes an entire round trip.
  3. ## API reference — one link per resource or tag group, each pointing to that group's Markdown reference page, not an HTML page.
  4. ## SDKs — install and import paths per language, so the agent doesn't guess a package name.
  5. ## Optional — changelog, migration notes, deep dives, deprecated-endpoint notices. Agents that respect the spec skip this section first when context is tight, so put anything non-essential here rather than in the main sections.

A worked example

# Acme Payments API

> Acme Payments processes card and bank transfers via a REST API.
> Sandbox and production share the same shape; only the base URL differs.

## Quickstart

- [Getting started](https://docs.acme.example.com/quickstart.md): create a charge in under 10 lines, TypeScript and Python.

## Authentication

Acme uses bearer tokens in the `Authorization` header. Sandbox keys start
with `sk_test_`, production keys with `sk_live_`. Full detail:
[Authentication](https://docs.acme.example.com/auth.md).

## API reference

- [Charges](https://docs.acme.example.com/charges.md): create, retrieve, refund.
- [Customers](https://docs.acme.example.com/customers.md): create, update, list payment methods.
- [Webhooks](https://docs.acme.example.com/webhooks.md): event types, signature verification.

## SDKs

- [TypeScript](https://www.npmjs.com/package/@acme/payments): `npm install @acme/payments`
- [Python](https://pypi.org/project/acme-payments/): `pip install acme-payments`

## Optional

- [Changelog](https://docs.acme.example.com/changelog.md)
- [Migrating from v1](https://docs.acme.example.com/migrate-v1.md): the `charges` endpoint replaced `payments` in v2.

Notice every reference link points to a .md path, not the HTML page a human would open — per the llms.txt format reference, agents that follow links get clean text instead of navigation chrome, and it's the single most common gap in hand-written files.

How Sourced generates this from your OpenAPI spec

Writing the above by hand works for a small, stable API. It drifts the moment your API changes — two releases in, the file describes endpoints that moved or no longer exist. Sourced's llms.txt generator builds it from the same OpenAPI source that drives your SDK and docs preview:

  • Operation-level summaries come from your spec's summary/description fields, grouped by tag — so the file mirrors how your team already organizes the API, not an arbitrary regrouping.
  • operationIds are preserved, keeping the generated file's structure stable across regenerations even as descriptions change.
  • The ## Optional section auto-collects examples, changelog, and migration notes so they don't compete with the core reference for an agent's attention.
  • It regenerates on every spec push — no separate llms.txt build step to remember, and no drift between what you ship and what the spec says.

Three ways to get it shipped: upload your OpenAPI spec at signup and it's part of the docs preview before anything publishes; connect a GitHub repo and it rebuilds automatically on every spec change; or, if you already host docs elsewhere, run the migration scanner first — it reports what to keep, redirect, or replace rather than starting from a blank file.

Validating your llms.txt before you ship

Five rules cover almost every valid file, per the format reference:

  1. Served at /llms.txt at the domain root, Content-Type: text/plain or text/markdown, UTF-8.
  2. First non-blank line is a Markdown H1 (# Project name) — the only strictly required element.
  3. An optional blockquote summary right after the H1, kept under roughly 280 characters since some agent fetchers truncate longer ones.
  4. Sections start with an H2, each containing a bulleted list of - [Title](url): description. links.
  5. An ## Optional section for anything an agent can skip under context pressure.

If you're generating with Sourced, the dashboard surfaces the generated file's parsed structure, link count, and any orphaned references — link targets that don't resolve — before you publish. You can also paste an existing hand-written llms.txt into the dashboard to compare it against what Sourced would generate from the same spec, which is a fast way to spot missing endpoints. Outside Sourced, llmstxt.org documents the same five rules directly if you're validating a hand-built file by hand.

What to surface vs hide

  • Surface every public endpoint. An agent that can't find an endpoint in your llms.txt will sometimes invent one that looks plausible instead of admitting it doesn't know.
  • Surface error codes and their meanings. A common agent failure mode is misreading a 4xx response and silently retrying into a loop — a short error-code table heads that off.
  • Hide deprecated endpoints under ## Optional with a clear deprecation note, rather than deleting them outright — agents that read Optional first will avoid them, and you keep a record for anyone still migrating off them.
  • Hide marketing pages entirely from the main sections. Pricing, case studies, and landing pages belong in ## Optional at most, never in ## API reference or ## Quickstart.

Honest scope: when hand-writing is fine

If your API has a handful of endpoints and changes rarely, a hand-written llms.txt following the five sections above is genuinely enough — you don't need a generator for a file that's a few dozen lines and stable for months at a time. Generation earns its cost once your spec changes often enough that keeping a hand-written file in sync becomes its own maintenance task. And llms.txt itself doesn't replace real documentation or an MCP server — it's an index and orientation layer, not the thing an agent calls to actually execute a request. For specs too large to reason about in one read even with llms.txt as an entry point, see when a spec is too large for an LLM's context for slicing and MCP strategies that go further.

FAQ

How is this different from your earlier llms.txt post?

That post explains what llms.txt is, why it matters for API teams, and how Sourced emits it in general. This post is the implementation detail specific to API companies: the exact five sections, a worked example, and the validation checklist.

Do I need separate llms.txt files for sandbox and production?

No — keep one file and note the difference in the Authentication or a caveats line (sandbox key prefix, base URL difference), the way the worked example above does. Two files invite drift between them.

What's the most common mistake in a hand-written API llms.txt?

Linking to HTML docs pages instead of their Markdown equivalents. Agents that fetch an HTML page waste context tokens parsing navigation and layout instead of reading the actual reference content — always link the .md version when one exists.

Can I generate llms.txt without generating an SDK?

Yes. Docs and llms.txt generation are independent outputs of the same Sourced pipeline — you can generate hosted docs and llms.txt from a spec without publishing an SDK at all.

How do I check my llms.txt for broken links before publishing?

Sourced's dashboard reports orphaned references — links that don't resolve — as part of the generated preview. Outside Sourced, spot-check by fetching each linked .md URL directly and confirming it returns content instead of a 404.

Should endpoints behind a beta flag be in the main sections or Optional?

Optional, with a clear note that the endpoint is in beta and may change. Treat it the same as a deprecated endpoint — visible to agents that read that far, but not presented as stable in the main reference.

Ship it

Generate an llms.txt from your OpenAPI spec, or create hosted docs from your repo to get llms.txt, SDK previews, and docs together in one free, unlimited run. See llms.txt examples worth copying if you want to compare real files before you write your own sections.