Since the dawn of time—or at least since StackOverflow launched—software engineers have turned to search engines and developer forums for guidance. But the resources of choice are changing; Postman’s 2025 State of the API Report found that 89% of developers use generative AI to assist with their daily tasks. Instead of Googling the error you’re getting, you might be asking ChatGPT for answers. Maybe you’re prompting Claude to generate some or most of your code to begin with.
In turn, AI agents are reading more documentation, making more software decisions, and writing more API implementations. For engineers building and documenting external APIs, this means the developer experience is no longer limited to the human experience.
Why invest in the experience of a machine?
SaaS providers invest in the developer experience (DX) to drive adoption, retention, and revenue; you win more customers when you’re easy to build with. With more developers using generative AI, coding agents are the new consumers of your APIs and documentation. And when agents are telling users what APIs to use, you want to be their #1 choice.
Building AI-friendly APIs
When evaluating your API implementation, consider Murphy’s law: anything an agent can interpret incorrectly, it will. There’s no room for guesswork. Successful AI interactions thrive on predictability and reliability, which you can facilitate through the 3 D’s: design, documentation, and discovery.
Design
Simple, RESTful APIs with minimal variability help LLMs anticipate what endpoints to use, when to use them, and how to use them. Your end goal should be a clear endpoint-to-function-call mapping with patterns that are nearly impossible to miss.
Many REST principles already solve for this, as REST prioritizes a standardized interface with clearly identifiable resources and uniform object representation. For example, an LLM should be able to intuit that a POST request to a `/phones` endpoint will create a phone object, and a GET request to `/phones` will retrieve a list of phone objects. Conversely, avoid API complexity: optional fields or multiple request structures boost flexibility but also introduce more states of failure. This forces an agent to consider all possible outcomes: “Should I include this field? What happens if I omit it? And what value should I use if I include it?” RESTful APIs also support stateless operations, which prevents the need for agent-side session management and allows an agent to simply retry upon failure.
Lastly, latency matters more than ever because agents rely on fast response times. A human may get impatient waiting for a reply, but an agent may give up altogether.
Documentation
Even a well-designed API will fall short without a clear instruction manual; agents don’t have intuition. To avoid agent confusion, your API documentation should be machine-readable, consistent, and crystal clear.
OpenAPI is a widely adopted specification used to define APIs with limited ambiguity. OpenAPI specs are written in JSON or YAML, which meets the need for a machine-readable format. Remember that agents are built on probability; where your spec is ambiguous, the agent will choose the statistically most likely next step, which may not be accurate. To prevent this, nothing should be left for interpretation.
- OpenAPI allows operationIds to be defined for each API operation. Define them consistently and carefully throughout your specification.
- Provide detailed descriptions for object schemas and components.
- Outline all possible error codes, and use HTTP verbs properly.
- Consistency is more important than ever, and all naming, formatting, and functionality should be intentionally predictable.
- You can even go the extra mile by providing runnable request and response examples to make expectations even more obvious.
On the other hand, inaccuracies in your spec can make it unusable for an agent. Even something as small as failing to document an edge case can cause silent failures. A human developer might use trial and error to rectify typos, missing fields, or incorrect data types, but an agent won’t stop to troubleshoot or ask questions; it will just move on to the next best option.
Discovery
Once you have an easy-to-use API with documentation that is easy to understand, your documentation must also be discoverable, so that agents are able to find it, recommend it, and use it! Make your docsite publicly available with an intuitive organizational hierarchy —the aim here is to be crawlable. This could mean providing an llms.txt page or a nested tree of files that reflects the structure of your API suite. The ultimate goal is for the agent to find the appropriate API for the end user’s request, quickly and reliably. Once again, speed matters. If your docsite doesn’t load within a few seconds, it might as well be invisible to a machine-driven search.
In short…
The shift from human-centric to agent-centric API consumption is happening whether your platform is ready or not. Invest in AI-informed DX (some people are calling this AX) to increase the likelihood that agents will use and recommend your APIs. Keep in mind that LLMs are built on pattern recognition and probability rather than human understanding, and use the 3 D’s to guide you:
- Design your APIs to be clear and consistent
- Write Documentation that leaves zero room for guesswork
- Make your specs easily Discoverable by AI agents
Next stop: Scaling your AI applications with the right APIs.
