llms.txt: The API Documentation Format That AI Actually Reads

2026-03-31 | Tags: [ai, api, b2a, llms-txt, documentation, ai-agents, seo]

There's a quiet documentation crisis happening with AI-consumed APIs: the two formats that have worked well for decades — human-readable prose docs and machine-parseable OpenAPI specs — are each missing something important for AI consumption.

Prose documentation is written for human comprehension. It has navigation structure, progressive disclosure, marketing copy, and conceptual explanations. When an AI system reads it, most of that context is noise that competes with the signal.

OpenAPI specs are written for machine validation. They're precise, but they're also verbose, deeply nested, and optimized for generating code stubs and validation logic — not for explaining what an API is for and when you'd use it.

llms.txt fills the gap: a documentation format written specifically for the way AI language models read and reason about APIs.

What llms.txt is

llms.txt is a plain-text file, typically hosted at /llms.txt on your domain, that describes your API's capabilities in natural language — but structured natural language, not prose documentation.

The format is intentionally simple:

# Hermesforge Screenshot API

Take screenshots of any URL. Returns PNG, JPG, or WebP images.
No authentication required for up to 100 requests/day.

## Endpoint

GET /api/screenshot?url={url}

Parameters:
- url (required): The URL to screenshot. Must include http:// or https://.
- format (optional): png (default), jpg, webp
- full_page (optional): true to capture full scrollable page, false for viewport only (default)
- width (optional): Viewport width in pixels, default 1280
- height (optional): Viewport height in pixels, default 800

Returns: Image file (Content-Type: image/png, image/jpeg, or image/webp)

## Rate limits

Free tier: 100 requests/day, no auth required
Paid tier: 10,000 requests/day, requires API key header (X-API-Key)

## Error responses

429: Rate limited. Retry-After header indicates when to retry. See /pricing for paid tier.
400: Invalid URL. Ensure URL includes scheme.
504: Timeout. Target page took >10s to load.

## Use cases

- Take screenshots for visual testing
- Capture website thumbnails for link previews
- Monitor website changes with visual diffs
- Generate social preview images from URLs
- Enable AI agents to "see" web pages visually

This is not a spec, not a tutorial, and not marketing copy. It's a compact capability description that an AI system can read in a few hundred tokens and use to answer questions like: "What APIs can take website screenshots?" or "How do I programmatically capture a full-page screenshot?"

Why existing formats fall short for AI consumption

OpenAPI specs are comprehensive but context-heavy. The spec for the screenshot API runs to ~800 lines when fully documented — valid JSON/YAML with deeply nested schema definitions. An AI system that reads the full spec to answer "what does this API do?" is burning tokens on information it doesn't need for that question.

More importantly: OpenAPI specs describe the API's interface contract, not its use cases. They tell you what parameters exist; they don't tell you when you'd use full_page=true vs the default, or why WebP is usually the right format choice.

Prose documentation has the inverse problem: it tells you everything about use cases but buries the interface contract in examples rather than stating it structurally. An AI system parsing a tutorial page has to extract the interface from context rather than reading it directly.

llms.txt is optimized for a different reading pattern: an AI system that needs to answer a question about the API's capabilities in a few seconds. The format is skimmable, structurally predictable, and free of navigation chrome, cookie banners, and promotional copy.

The AI discovery mechanism

Here's how AI recommendation actually works for APIs:

  1. A crawler (GPTBot, ClaudeBot, PerplexityBot) indexes your site — including your llms.txt
  2. The content gets embedded into the AI system's knowledge base
  3. A user asks "how do I take a screenshot of a URL programmatically?"
  4. The AI retrieves relevant documents from its knowledge base
  5. If your llms.txt is in that knowledge base and clearly describes screenshot capture, you're a candidate for recommendation

The quality of your llms.txt directly affects step 4 — how confidently the AI can match your capability to the user's query. A vague description ("web capture tool") retrieves less confidently than a specific one ("take screenshots of any URL and return PNG, JPG, or WebP images").

The hermesforge screenshot API gets ~50% of its traffic from ChatGPT-User. Some of that is from ChatGPT having indexed the site directly. The llms.txt is designed to make that indexing as accurate and complete as possible — reducing the chance that ChatGPT misrepresents the API's capabilities or omits important constraints like the rate limit.

Writing a good llms.txt

The key principles:

Lead with the job, not the name. Start with what the API does, not what it's called. "Take screenshots of any URL" is more useful to a retrieval system than "HermesForge Screenshot Service."

State constraints explicitly. Rate limits, authentication requirements, URL format requirements, timeout behavior — all of this should be in the llms.txt. An AI that recommends your API and gets the constraints wrong will frustrate the user, and they'll remember that.

Be specific about formats and values. Don't say "supports multiple image formats." Say "supports PNG (default), JPG, and WebP via the format parameter." Specific values are indexable; vague descriptions are not.

Include error semantics. What does a 429 mean? What does a 400 mean? An AI guiding a user through an integration needs to know how to interpret your error codes.

Use cases should be concrete. "Visual testing" is vague. "Capture before/after screenshots for regression testing in CI/CD pipelines" is specific. AI systems retrieve on specificity.

What to put in it, what to leave out

Include: - Endpoint URLs and HTTP methods - Required and optional parameters with types and valid values - Response format (Content-Type, schema shape) - Rate limits and authentication requirements - Common error codes and their meaning - Concrete use cases (3-5 is enough)

Exclude: - Marketing copy and feature positioning - Pricing details beyond "free tier limits" - Tutorial walkthroughs and code samples - Navigation structure (headers, categories) - Anything that assumes the reader will click through to learn more

The llms.txt is not a landing page. It's a capability specification written for retrieval.

The hermesforge llms.txt is at hermesforge.dev/llms.txt. It describes the screenshot API, the techstack detector, and the dead link checker in a format optimized for AI knowledge base indexing. If your API is being used by AI-relayed traffic, writing a good llms.txt is one of the highest-leverage distribution actions available to you.