Moving Beyond OpenAPI for Agentic Experience

Teaching AI agents to use your API.

Forget all you learned about developer experience. The goal has changed. Now, API design is not just about helping people build integrations. Now what matters the most is making sure that AI agents have as smooth an experience as possible. Why? Because a growing percentage of API requests is not made by developers. More than that, a growing number of API integrations aren’t needed anymore. AI agents can easily access APIs on the fly, without needing a previously configured integration. But to make the most of APIs, AI agents need to have a full understanding of what they do. While humans care about reading nicely written documentation, agents are more interested in structure, semantics, and machine-readable definitions. So, how do you improve the quality of those elements? Keep reading to learn more.

---

This article is brought to you with the help of our supporter, Scalar.

Scalar is the modern OpenAPI platform for the entire API lifecycle. Govern APIs with Scalar Registry, test offline with their built-in Client, generate beautiful documentation, and ship SDKs instantly - all from your single source of truth.

---

Until not long ago, it was easy to onboard API consumers just by handholding them into their first request. Time-to-first-request, or TTFR, became the golden metric for API DX. We all got used to talking about TTFRs of days or, at best, a couple of hours. And that all worked, even with less-than-ideal documentation. Usually, a few demos and support calls would solve any difficulties. Well, that doesn’t work (and doesn’t scale) where we are now. AI agents aren’t good at navigating ambiguity. They can only infer what they have to do from the information you share with them. Here are the three examples of the friction points AI agents find when they interact with an API:

1. Semantic Ambiguity: Sometimes the name or structure of an operation can be interpreted in more than one way, even if it seems obvious to the person who designed it. An AI agent doesn’t have that human experience to fill in the blanks. Without explicit definitions, the agent has to guess what the operation actually does, which often leads to integration errors and broken workflows.

2. Fragile Error Handling: When an API fails, a developer manually writes a retry loop or handles rate limits. An AI agent facing a generic 400 Bad Request or an HTML error page is blind. It has no programmatic way to determine if an error is transient, permanent, or how long to back off before trying again.

3. Interactive Security Obstacles: Redirection-heavy OAuth 2.0 authorization flows, session cookies, and interactive CAPTCHAs are built to stop bots. But they also render APIs completely inaccessible to autonomous agents that need to authenticate programmatically.

These are just three examples of factors that can contribute to a poor agentic experience, or AX. The more difficulties an agent has in interacting with an API, the worse the results will be. Solving this problem is possible, though.

Designing for AX doesn’t mean you have to throw away your existing APIs. Your API definitions and documentation aren’t just reference material, though. They’re structured runtime contexts for AI agents. With those resources, you can help AI agents navigate your API reliably and safely. So, how do you make your API ready for AI agentic consumption? Well, an AX-optimized API needs to have a few qualities. First, it has to be highly semantic so that any AI agent can understand what each operation does without doubt. To get there, use precise resource naming, descriptive metadata on every operation, parameter, and attribute, and explicit parameter constraints. With that in mind, the API definition becomes a deterministic contract that AI agents will follow. But that’s not enough. It should also explicitly declare real-world side effects to help AI agents know if an operation can be potentially destructive. You can do that with the help of the MCP tool annotations that you can add to your OpenAPI document. To add it, create the x-mcp-annotations object inside any operation. Then populate it with a combination of the readOnlyHint, descructiveHint, and openWorldHint, just to name a few options. The next step is improving all error messages by providing responses with machine-interpretable recovery instructions, with the help of RFC 9457. Finally, you should indicate which level of trust AI agents need to access your API. You can do that using the OpenAPI x-agent-trust extension and specifying one of the existing trust levels that go from L0-UNTRUSTED up to L4-FULL. This information tells agents how they can authenticate themselves and what the minimum level of trust is. In essence, the goal is to tell agents in a machine-readable way what they can or can’t do with your API.

All the solutions I just shared are really interesting. However, they’re quite new and are prone to evolving rapidly, so keep that in mind. Also, pay attention to a few difficulties you might find along the way. One of the things you’ll notice is that documentation can no longer be a secondary priority. Whatever you deploy to production needs to be properly documented. Otherwise, AI agents won’t be able to use your API to its full extent. Speaking about the full extent, something else to keep in mind is the potential increase in costs due to adding more information to prompts. The more information you add to your OpenAPI document, the more tokens you’ll spend. That happens because the full API definition needs to be injected into the model’s context window. The final difficulty has to do with security. To avoid having AI agents use your API in destructive ways, you need to invest in fine-grained authorization and rate limiting. Otherwise, you risk having unauthorized access or even denial of service.

Are you convinced yet? It’s undeniable that the main API consumers are increasingly AI agents. However, it’s also undeniable that the costs of improving AX aren’t negligible. At this point, you can choose to stick with traditional, human-only DX. You keep maintaining standard API documentation and hoping the next generation of AI agents is smart enough to guess their way through your ambiguous endpoints. Or, you can make an investment now and adapt what you have to welcome AI agents as API consumers. I know what I’d do if I were you.

---