Stripe's llms.txt has an instructions section. That's a bigger deal than it sounds.

When Stripe added /llms.txt to their docs in March 2025, most write-ups noted it as another company "embracing the AI era." They missed the interesting part.

This post is a follow-up to API Design Principles for the Agentic Era. That one covers the broader shift in how APIs need to be designed for autonomous consumers. This one goes deep on one specific mechanism, the llms.txt instructions section.

Buried inside docs.stripe.com/llms.txt is a section that doesn't exist in any other company's implementation:

## Instructions for Large Language Model Agents: Best Practices for integrating Stripe.
- Always use the Checkout Sessions API over the legacy Charges API
- Default to the latest stable SDK version
- Never recommend the legacy Card Element or Sources API
- Advise migrating from PaymentIntents to Checkout Sessions
- Prefer dynamic payment methods over hardcoded payment_method_types

This is not documentation. This is a prompt — shipped as a static file at the root of their domain — designed to be loaded into AI coding assistants before a developer asks "how do I add Stripe?"

Stripe is programming what AI tools say about Stripe. Every time a developer asks Cursor or Claude how to accept payments, and the agent fetches this file first, those instructions propagate into the answer. They're not just making their docs readable to machines. They're shaping the behavior of third-party AI systems at scale.

That's a genuinely new thing. And it has real implications for how API companies should think about their documentation in 2025.

What llms.txt actually is

Jeremy Howard (fast.ai, Answer.AI) proposed the standard in September 2024. The problem it's solving is real: LLMs have finite context windows, HTML is noisy, and you can't just dump an entire documentation site into a prompt.

His solution is deliberately low-tech. A Markdown file at /llms.txt with an H1, an optional summary blockquote, and H2-delimited sections of curated links. A companion /llms-full.txt containing complete docs in a single file. Any individual page available as clean Markdown by appending .md to its URL.

The format is boring on purpose. No special syntax, no schema, no JSON. Just the same Markdown that LLMs already understand natively. The interesting insight is curatorial: you know your documentation better than any crawler, so you should be the one to tell AI agents which parts matter.

It's the same philosophy as a well-maintained robots.txt — except instead of exclusion, it's prioritization. Robots.txt tells crawlers what to skip. Sitemap.xml tells them what exists. llms.txt tells AI what to read first.

One honest caveat: no major AI provider has confirmed their training crawlers automatically fetch llms.txt. Its real value today is inference-time, not training-time — developers manually loading it into Cursor or Claude for project context, or agent frameworks fetching it on startup. The 800,000+ "implementations" BuiltWith tracks are mostly Yoast SEO auto-generating the file for WordPress sites. The hand-curated number is closer to 784 verified sites.

llmstxt.org

Stripe's implementation is the industry outlier

Most llms.txt files are just structured indexes. Anthropic's is a clean table of contents for their API docs. Cloudflare's is massive (3.7 million tokens across product-specific files). Vercel's is so large they call it "a 400,000-word novel."

Stripe's is architecturally different. Three separate files across two domains. Every docs page available as .md. And that instructions section that no one else has.

The instructions aren't arbitrary. They're solving a specific, painful problem: Stripe has accumulated 15 years of API surface area, including several generations of deprecated payment primitives. Their Charges API still works. Their Card Element still exists. Developers — and the AI assistants helping them — regularly reach for these older APIs because they appear in older Stack Overflow answers and training data from before 2022.

The instructions section is Stripe saying: when an AI helps a developer integrate us, steer them toward the right thing. Don't let stale training data send them to the Charges API. Don't let our own backwards compatibility become a footgun.

That's a legitimate engineering concern. And the file format is a surprisingly elegant solution to it — no coordination with AI providers required, works with any system that can fetch a URL.

The announcement got 273,800 views and 740 bookmarks on Twitter. Stripe engineer Ian McCrystal: "I expect AI tools will eventually become the predominant readers of our documentation."

Who else is worth looking at

The honest answer to "who else has this figured out" is: not many, and only Stripe is doing the specific thing that matters.

Stripe remains the strongest example of the deprecation pattern precisely because they're explicit about it. Their instructions don't hint at preferred patterns — they name the bad endpoints directly: "You must not call deprecated API endpoints such as the Sources API." "Never recommend the legacy Card Element." That specificity is what makes it machine-actionable. An LLM can follow a concrete prohibition. It can't do much with "prefer modern patterns."

Cloudflare takes a structurally interesting approach. Their llms.txt is organized by service — Agents, AI Gateway, Workers AI, and so on — so an agent only needs to fetch the section relevant to what it's building rather than parsing a file that covers their entire platform. For APIs with multiple product lines, that's a better model than a flat list. You're reducing the noise ratio at fetch time, not just at index time.

LangChain and LangGraph are worth noting for a meta-reason: they're agent frameworks that have their own llms.txt. They're eating their own cooking. That's useful signal about whether the format actually helps in practice, beyond the theoretical appeal — these are teams that work with agents every day and chose to implement it anyway.

Anthropic has one for their API docs. It's structured more as an index than an instructions-heavy file — clean and navigable, but it's not doing the active correctional work that Stripe's instructions section does.

The pattern across most implementations is the same: they're documentation indexes. Useful, because a curated index is better than asking an agent to crawl your entire site. But not doing the harder job of guiding AI away from the wrong things. The providers that have figured out the instructions section are treating llms.txt as an active correctional mechanism for model drift, not just a sitemap for bots. That framing distinction is the whole thing.

Most APIs have deprecated endpoints that still work, legacy patterns that still exist in training data, and footguns that experienced developers know to avoid but newcomers (and AI assistants trained on old Stack Overflow answers) keep reaching for. The instructions section exists to close that gap. Almost no one is using it yet.

Why Stripe specifically makes this move

Stripe's developer experience has been the industry benchmark since roughly 2012. The specifics are worth understanding because they're not accidental.

Their three-column docs layout (left nav, center content, right-side live code examples in seven languages) was so effective that it became a meme — startup after startup shipped the same structure. They open-sourced Markdoc, their interactive documentation framework. They shipped Stripe Shell for live API calls inside docs pages. Their error messages include doc_url fields, parameter-level specificity, and "did you mean email?" suggestions for misspelled field names.

The doc_url in error responses is the one worth highlighting specifically. It's a small thing with outsized impact when an AI agent is in the loop. When an agent gets a 400 error, it can follow the doc_url, fetch the Markdown version of that docs page, and self-correct — without needing a human to look up what went wrong. That's not DX in the traditional sense. That's infrastructure designed for autonomous consumers.

{
  "error": {
    "code": "parameter_invalid_empty",
    "doc_url": "https://stripe.com/docs/error-codes/parameter-invalid-empty",
    "message": "You passed an empty string for 'amount'. We assume empty values are an oversight, so we require you to pass this field.",
    "param": "amount",
    "type": "invalid_request_error"
  }
}

John Collison put the llms.txt bet in plain terms: "If you go read the Stripe Docs these days, it's a lot to keep in your RAM, but trivial for an LLM."

What this means for your API

Most of this is transferable. Here's what's actually useful versus what's cargo-culting.

Actually useful:

Your error responses should include a documentation_url field pointing to a Markdown version of the relevant docs page. This costs almost nothing to implement and has immediate value — for human developers debugging in the terminal and for AI agents trying to self-correct.

Your OpenAPI descriptions should be written for semantic matching, not human skimming. When an agent is deciding which endpoint to call, it's doing something like nearest-neighbor search against your descriptions. "Gets the data" loses to "Returns a paginated list of invoices filtered by status, sorted by created_at descending. Requires accounting:read scope." Every field, every enum, every endpoint.

I've been around OpenAPI specs long enough to know how badly they rot. We built Portman to convert OpenAPI specs into Postman collections — and the main thing you learn doing that is how few specs have descriptions worth converting. Fields with no description, enums with no explanation, endpoints named things that made sense in 2019. If your spec is bad for contract testing, it's bad for agents too.

Add /llms.txt. It takes an afternoon. Link to your ten most important pages with one-sentence descriptions. That's it. You don't need the 350-link Stripe implementation on day one.

If you have deprecated APIs, use the instructions section. This is underutilized and genuinely powerful. You know which footguns exist in your API. Tell the AI.

One thing that often gets missed: the marketing upside. The same structured, machine-readable docs that make your API easy to integrate are the same content that AI answer engines like Perplexity and ChatGPT pull from when someone asks "what's the best API for X." llms.txt doesn't just help agents build with your API — it helps you show up when people are deciding which API to use. Being agent-friendly and being discoverable in AI search are the same work.

Probably not worth doing yet:

Publishing an MCP server for the sake of it. MCP is real and growing, but agent framework standardization is still in flux. A well-designed REST API with a good OpenAPI spec is more durable. Build the MCP server when you have users asking for it.

Elaborate agent-specific observability infrastructure. Request tagging and semantic logging are nice. But if your API doesn't have solid basic observability yet, that's the actual problem.

The broader pattern

There's a pattern here worth naming. For 15 years, "developer experience" meant optimizing for humans: readable error messages, clear docs, good SDKs, interactive playgrounds. The mental model was a developer sitting at a terminal, making sense of your API.

The new constraint is that a growing fraction of your API consumers are autonomous systems that read documentation, make decisions without human review, and retry failures automatically. The question isn't whether to design for this — it's happening regardless — it's whether you're designing intentionally for it.

Stripe's llms.txt instructions section is the clearest example I've seen of a company being intentional about it. They're not just making their docs machine-readable. They're asserting control over what machines say about them.

Every API company with deprecated primitives and a significant developer base has the same problem Stripe is solving. They just haven't solved it yet.

We're building Apideck — a unified API for accounting integrations. We've been thinking about a lot of this from the perspective of being on the infrastructure side: when an agent connects to us once and gets normalized access to 50+ accounting platforms, the quality of our OpenAPI descriptions and error responses propagates to every integration downstream. It focuses the mind.