What Actually Makes an API Agent-Friendly? A Real Audit

"Agent-friendly" gets used a lot right now without much behind it, a vague stamp of approval rather than a checked-against-anything claim. Fern and Mintlify, two companies that build API documentation platforms for a living, have actually published specific, checkable criteria for what that means. So instead of asserting that AIOZ Stream's own llms.txt files qualify, this checks them against those criteria directly, point by point, including the places they fall short, treating the label itself as something to verify rather than something to take on faith just because the file exists.

TL;DR:

• Fern's own numbers: a typical HTML docs page runs about 16,000 tokens for an AI agent to parse; the same content as Markdown runs about 1,600, a 90%+ reduction.
• Real criteria worth checking: self-contained sections, complete type definitions, documented error responses, consistent heading structure, and content negotiation (serving Markdown automatically to an agent instead of a separate file it has to know to ask for).
• AIOZ Stream's llms.txt files get the structural basics right: H1 plus summary, sections organized by resource, instructions written explicitly for an AI reader.
• Where it falls short: no automatic content negotiation, and the files are maintained by hand rather than generated from the API definition, which is exactly how two small but real inconsistencies crept into AIOZ Stream's own docs elsewhere.

The actual criteria, not a vibe

Fern's own published guidance lays out what "LLM-friendly" documentation is supposed to do: keep each section under a clear heading complete enough to make sense on its own if an agent retrieves just that piece, use consistent heading hierarchy rather than an ad hoc structure, give complete type definitions instead of bare parameter names so an agent doesn't have to guess a shape, document every non-200 response code, and generate the reference directly from the API definition so it can't silently drift from what the API actually does. Mintlify's approach adds one more piece: content negotiation, detecting that a request is coming from an AI agent and serving Markdown automatically instead of the same HTML a browser gets, no separate file required.

The token math behind why this matters

Fern's own comparison is specific: a standard HTML documentation page runs roughly 16,000 tokens once an agent parses the markup, navigation, and styling along with the content. The same page as plain Markdown runs about 1,600, over a 90% reduction. That's not a rounding difference, it's the gap between an agent being able to load ten relevant pages of context or one, which compounds further once an assistant is following links across a multi-page reference rather than reading a single isolated page. It's also the same reasoning already covered in this series for why AIOZ Stream favors plain Markdown section files over a heavier format like OpenAPI/Swagger: structural overhead costs context budget an agent doesn't get back.

Where AIOZ Stream's llms.txt gets it right

Checked directly against the file at aiozstream.network/docs/llms.txt: it opens with an H1 title and a summary, exactly the structure Fern recommends, followed by an explicit "Instructions for AI Assistants" section, ten numbered points covering credentials, the SDK auth pattern, base URLs, and sequencing. The API sections underneath are organized by resource, media-video, webhooks, players, and so on, each one a self-contained file rather than one long undifferentiated document. That matches the "complete thought that makes sense when retrieved independently" standard directly, an agent pulling in the webhooks section doesn't need the payments section loaded to make sense of it.

Where it falls short, honestly

Two real gaps, not hypothetical ones. First, there's no content negotiation. Fetching the regular docs site as a browser and fetching it as an AI agent returns the same HTML either way, you have to already know the separate /docs/llms.txt URL exists and fetch it deliberately. That's a meaningfully different experience from what Mintlify's own platform does automatically, detect the request source and serve the right format without anyone needing to know a second URL.

Second, the files are maintained by hand rather than generated straight from the API's own definition, which is exactly the setup Fern's guidance warns can drift. It already has, in a small but real way: this series' own developer guide article found the webhook event names documented in snake_case (encoding_started) on one page and dot notation (encoding.started) on another, and the API keys article found the key-creation endpoint documented on a different subdomain than the list/update/delete endpoints. Neither is llms.txt-specific, they're general documentation inconsistencies, but they're a concrete illustration of the exact risk that comes from docs a person maintains by hand instead of docs generated from one source of truth.

What fixing the content negotiation gap would actually take

Content negotiation isn't a documentation-writing problem, it's an infrastructure one, which is part of why fewer platforms have it than have a static llms.txt file. Mintlify's own implementation works by inspecting the request, checking the user agent or an explicit header against a list of known AI-assistant clients, and serving Markdown instead of the rendered HTML page when it matches, all without the requester needing to know a separate URL exists. Building that from scratch means owning the docs-serving layer directly rather than treating documentation as static files, which is a bigger lift than writing a well-structured llms.txt file once and pointing people at it, closer to a docs-platform migration than a documentation-writing task. That's not an excuse for not having it, it's just a more accurate description of why a static file is the more common starting point than full content negotiation, even among teams that clearly care about this.

What generated-from-source would actually fix

The two real gaps identified above, no content negotiation and hand-maintained files, aren't unrelated problems, the second one is partly what makes the first one riskier to skip. If AIOZ Stream's llms.txt files were generated directly from the same source that produces the human-facing API reference, a change to an endpoint or a field name would propagate to both automatically, closing the exact drift risk the webhook-naming and split-subdomain inconsistencies illustrate. Static, hand-maintained files aren't wrong on their own, most companies with an llms.txt file maintain them by hand, but they do mean every future API change carries a small, real chance of updating one doc surface and not the other, unless something in the process specifically checks for that.

What an honest scorecard looks like

Structure and self-containment: yes. Explicit instructions for an AI reader: yes, and more explicit than most competitors researched for this series. Content negotiation: no, it's a separate file you have to know about. Generated-from-source consistency: no, and the two documented inconsistencies above are the visible cost of that. That's not a failing grade, most API documentation, including much larger platforms, hasn't implemented content negotiation either, so AIOZ Stream's llms.txt implementation is closer to the current industry norm than behind it on that specific point. It's a specific, checkable list of what's done and what isn't, instead of a blanket claim either way.

Frequently Asked Questions

Who actually defines what "agent-friendly" documentation means?
There's no single official standard, but companies like Fern and Mintlify, which build documentation platforms for a living, have published specific, checkable criteria that this article uses instead of an informal definition.

Does AIOZ Stream's llms.txt use content negotiation?
No. The regular docs site serves the same HTML to a browser and an AI agent; the llms.txt files are separate, static files an agent has to know to fetch.

Why does hand-maintained documentation matter if the content is still accurate?
Because it isn't always. Two small, real inconsistencies already exist in AIOZ Stream's own docs, a webhook event naming mismatch and a split-subdomain API endpoint, both traceable to pages maintained independently rather than generated from one source.

Is the 90% token reduction figure specific to AIOZ Stream?
No, it's Fern's own published comparison for HTML versus Markdown documentation generally. It's cited here as the reasoning behind the format choice, not as a number measured against AIOZ Stream's specific pages.

Does failing one criterion mean the documentation isn't useful for AI assistants?
No. The structural basics, the parts that matter most for an agent generating correct code, are in place; content negotiation is a convenience improvement, not a blocker.

Why don't more companies implement content negotiation if it's the better experience?
Because it requires owning the docs-serving layer directly, detecting the requester and switching formats server-side, rather than just publishing a well-structured static file. That's a bigger infrastructure lift than writing an llms.txt file once, which is why a static file remains the more common starting point.

Related Reading

• What Is llms.txt?: what's actually inside the files audited here
• AIOZ Stream Developer Guide: source of the webhook naming inconsistency referenced above
• AIOZ Stream API Keys: source of the split-subdomain endpoint inconsistency referenced above

References

• Fern: How to Write LLM-Friendly Documentation: the token-cost comparison and structural criteria used throughout this article
• Mintlify: Improved Agent Experience with llms.txt and Content Negotiation: the content-negotiation standard referenced above
• AIOZ Stream llms.txt: the file checked directly against the criteria above