How do coding agents decide which API to recommend?
A coding agent recommends an API it already knows about and can use correctly. It learns about tools from training data and web search, and it learns how to use them from the docs it can read at the moment it writes code. If either step fails, the agent picks a competitor or writes broken code against yours, and the developer blames your product.
This is a different job from docs visual design, which we cover in developer documentation site design. Here the reader is a program. It doesn't see your sidebar or your brand colors. It sees the HTML or Markdown your server returns, the code blocks inside it and the links between pages. Our developer tools website design guide covers the human side of the same site.
We won't quote adoption numbers for coding agents, because the figures in circulation change monthly and few are primary research. The mechanisms are stable, though, and they're what you can control.
What is the difference between AI search and agents reading your docs?
AI search answers a question by citing pages; a coding agent fetches pages to finish a task. They overlap, but they reward slightly different things, so it helps to treat them as two channels.
Channel | When it reads your docs | What it needs |
|---|---|---|
AI search (ChatGPT, Perplexity, AI Overviews) | When a developer asks which tool to use | Indexable pages, clear answers, comparisons and mentions on other sites |
Agent with web access | Mid-task, when it looks up how to call your API | Fast, crawlable pages with complete code |
Indexed docs in an editor | After a user adds your docs URL to the tool | A crawlable entry page that links to every section |
Docs served over MCP or an API | When the agent calls a docs tool you or a vendor provide | Up-to-date content split into clean, searchable pages |
Some AI editors, Cursor among them, let a user add a docs source by entering a URL and then follow links from that page, so an entry page that links to every section, like a page with a full sidebar, gives the indexer the most to crawl. That's a small detail with a big consequence: if your sidebar is built by JavaScript after load, the crawler may find almost nothing to follow. The recommendation side is covered in how to get your brand recommended by ChatGPT.
How should you structure developer docs for AI search?
Structure developer docs for AI search by making every page answer one task, start with the answer and carry everything needed to complete that task. Agents fetch single pages, often without the surrounding context, so a page that only makes sense after reading three others gets misused.
- One task per page, named the way people ask. "Send a webhook signature check in Node" beats "Security concepts".
- Answer first. Open with one or two sentences and the code, then explain options and edge cases.
- One canonical method. If there are three ways to authenticate, say which one is recommended and why. Agents copy the first example they see.
- Stable URLs and headings. Renaming pages breaks the links that search engines, agents and users have stored.
- Explicit version labels. State which SDK and API version each page covers, and mark deprecated pages clearly at the top.
- Error messages as headings. Developers paste errors into chat; a page titled with the exact error string is easy to match.
The same answer-first habit helps human readers and AI citations, which is why the advice in FAQ sections that get cited carries over to docs pages.
Do llms.txt files help coding agents?
llms.txt helps some coding agents find the right pages, but it has no proven effect on AI search citations, so treat it as a cheap index, not a ranking lever. The proposal, published by Jeremy Howard at llmstxt.org, describes a Markdown file at your site root with the project name, a short summary and sections of links to the pages an agent should read.
For AI search, the evidence is flat. Ahrefs found that 97% of llms.txt files it checked got zero requests, and Google's AI features documentation says special files like this aren't needed to appear in its AI features. Our take on the citation question is in does schema markup help you get cited by ChatGPT.
For agents that fetch docs on demand, the file is still worth the hour it takes. Some docs platforms generate it for you: Mintlify's documentation says it hosts an llms.txt file and a combined llms-full.txt automatically, and links each page's Markdown version. If you build your own, our free llms.txt generator drafts one from your page list.
What makes a code example agent-ready?
An agent-ready code example runs when pasted into an empty project, with nothing the reader has to guess. Agents copy code literally, so every gap you leave for a human to fill becomes a bug in someone's codebase.
Include imports and installs
Show the package install command and every import. A snippet that starts at the function call forces the agent to guess the package name.
Pin versions
Name the SDK version the example was tested with. When the API changes, update the example and the label together.
Use environment variables for secrets
Read keys from an environment variable and say its exact name. Never put a fake key that looks real in a code block.
Show the response
Print or return the real response shape, including one error case. Agents use it to write the code that handles your API's output.
Test examples in CI
Run the docs examples against the current SDK on every release. Broken examples are the fastest way to get an agent to write broken code.
Hypothetical example: one page, two versions
For example, suppose a payments API has a page titled "Create a charge" whose only snippet calls client.charges.create() with no import, no install line and a placeholder key. An agent asked to add payments copies the call, guesses the package name and invents an option that was removed in the last major version.
Now suppose the page is rewritten: install line, import, key read from a named environment variable, the call with the recommended options, the JSON response and the shape of a declined-card error. Nothing about the API changed, but the agent now has one complete, current pattern to copy. That is the whole goal of agent-ready docs.
How do you make API docs crawlable by AI agents?
Make API docs crawlable by serving the full text and code in the initial HTML, keeping AI crawlers allowed in robots.txt, and offering a plain Markdown version of each page. Many AI crawlers don't run JavaScript, so content that only appears after scripts run may as well not exist.
- Server-render or statically generate docs. Next.js, Docusaurus and most hosted docs platforms do this by default. Single-page apps that fetch content on load are the risk.
- Don't hide content behind tabs that load later. Code tabs for different languages are fine if all languages are in the HTML.
- Check robots.txt. Make sure you aren't blocking OAI-SearchBot, PerplexityBot or Googlebot from docs, often by accident through a staging rule.
- Publish an OpenAPI spec at a stable URL. Agents and tools can read a spec more reliably than prose.
- Keep docs public where you can. Docs behind a login can't be indexed, cited or fetched by an agent working for a prospect.
If your docs and marketing site are on different stacks, check both. A fast docs site next to a client-rendered marketing site still loses the comparison and pricing questions, which our API company website guide covers.
How do you test whether agents recommend and use your API?
Test it the way your users work: open the coding tools they use, ask them to build something with your API from a blank project, and record what they get wrong. This takes an afternoon and finds problems no audit tool catches.
- Write 10 to 20 realistic tasks, such as "add [your category] to a Next.js app", without naming your product.
- Note whether the agent suggests your API, a competitor or nothing.
- Repeat with your product named, and run the code it writes.
- Log every wrong import, invented parameter or outdated method, and trace each to the docs page that caused it.
- Fix those pages, then re-run the same tasks next month.
Wrong recommendations usually point to off-site problems: few comparisons, few mentions, an unclear category. Wrong code usually points to the docs themselves. That split tells you whether to spend the next month on content or on docs fixes.
Who should own developer docs for AI agents?
Developer docs for AI agents should be owned by whoever owns the docs today, with engineering responsible for examples and the website team responsible for rendering and crawl access. It fails when it becomes a marketing side project, because the fixes live in code samples and build settings.
Where a studio helps is the part between docs and marketing: a fast, server-rendered site, clear comparison and pricing pages, and docs joined to them with consistent naming. That's the work on our devtools industry page and in our AEO website service. If you're weighing a rebuild to get there, Framer to Next.js migration cost covers one common path.
