AI Apps & APIs: Why They Don't Connect

In a rapidly evolving digital landscape, artificial intelligence-driven bots are increasingly traversing the internet, diligently seeking out and attempting to interact with Application Programming Interfaces (APIs). While some of these automated explorers harbor malicious intent, a significant and growing number are well-meaning consumers striving to discover, utilize, and benefit from existing APIs. These requests are frequently originating from Model Context Protocol (MCP)-driven platforms, designed to empower autonomous software to engage directly with web APIs.

Despite their sophisticated nature, these AI clients are, by many measures, struggling. Recent statistics paint a challenging picture: the success rate for multi-step AI-driven API workflows hovers around a mere 30%. Compounding the issue, these persistent clients often do not disengage after initial failures. Instead, they continue their attempts, generating excess traffic while diminishing the overall value proposition of the target APIs. This raises a crucial question: why are these advanced AI clients unable to effectively leverage today’s APIs, and what is required to reverse this trend?

The answer, it turns out, is not new. The fundamental requirements for AI-driven API consumers mirror those of human developers: they need clarity, contextual information, and a meaningful structure to interact successfully. Yet, many organizations have historically overlooked these tenets, seemingly forgetting the profound insight from the landmark 2017 paper, “Attention Is All You Need.” This pivotal research introduced the concept of “transformers” to the world of AI – models that mathematically score words based on their relationships within surrounding content. This scoring mechanism, termed “attention,” enables programs like ChatGPT to generate responses that are remarkably coherent and human-like.

The advent of transformer-driven generative AI tools necessitates a complete re-evaluation of how APIs are designed, documented, and implemented. While platforms such as ChatGPT, Claude, Gemini, and Copilot excel at “paying attention” to API designs—identifying URLs, HTTP methods, inputs, schemas, and expected outputs—they inherently lack the capacity for true understanding or reasoning. They can discern what an API looks like, but not why it should be used or what the returned data means. Essentially, today’s AI bots are fast, flexible API consumers that struggle with decision-making and interpreting meaning. The good news is that by leveraging their strength in pattern-matching and contextual association, we can enhance API designs to compensate for their current limitations, thereby making APIs “AI-ready.”

To level the playing field, there are four key practices, long beneficial for human developers, that are equally crucial for AI-driven clients. First, be explicit. Unlike humans, machines are not intuitive explorers. While adept at parsing text, they cannot make intuitive leaps. They require explicit clues about what can be accomplished, how to do it, and why. A terse list of operations like GET /customers/ might be clear to a human, who would seek further documentation for details. For a machine, however, this brevity leads to statistical guesswork. Providing explicit instructions, such as “To retrieve a list of customer records use GET /customers/” or “To create a new customer record use POST /customers/ with the createCustomer schema,” significantly increases success rates by leaving no room for ambiguity.

Second, tell them why. AI models are proficient at discerning how an API can be used, but less so at determining why it should be used. Enriching documentation with contextual explanations addresses this gap. Phrases like “Use the PriorityAccounts endpoint to identify the top ten customers based on market size” or “Use the submitApplication endpoint once all other steps in the employee application process have been completed” provide invaluable hints. AI-powered clients, especially those backed by large language models (LLMs), are adept at recognizing such text and associating it with relevant API endpoints.

Third, be consistent and predictable. The immense power of LLM-based applications stems from the vast datasets of code and documents they are trained on. These accumulated historical patterns enable AI clients to interact with new APIs. Consequently, an API that mirrors common patterns and conventions found in this training data will facilitate smoother interactions. Deviating with unique elements, unexpected responses, or non-traditional uses of standard protocols (e.g., using HTTP PUT exclusively for creation when POST is more common, or relying on XML schemas when JSON is prevalent) will inevitably make it harder for AI-driven applications to succeed.

Finally, make error responses actionable. When humans encounter errors, they typically scan information, deduce the problem, and formulate a solution. Machine-driven clients, however, lack this intuitive problem-solving ability. They often resort to retrying with random changes or simply giving up. To support them, API error responses must be explicit, provide context, and adhere to consistent formats. Adopting the “Problem Details for HTTP APIs” specification (RFC7078) is highly recommended. This structured format not only identifies and explains the error but can also suggest a possible resolution, such as “This update failed because a field was missing: hatsize.” This approach also aligns with the principle of consistency, as RFC7078 is widely recognized in LLM training data. Moreover, by treating errors as “partial attempts” and providing clear feedback, APIs can effectively “re-train” machine clients, populating their local context with examples of how to resolve future issues.

Ultimately, the practices that enhance interactions with AI-driven API clients are precisely those that have long been advocated for improving API design for human developers. Being explicit reduces cognitive load, telling developers (and machines) why streamlines decision-making, consistency fosters an intuitive experience, and actionable error responses lead to quicker problem resolution. Continuous monitoring of API usage—observing common endpoints, persistent error conditions, and traffic patterns—provides crucial insights for future design improvements. Whether serving human developers or machine agents, paying attention to these fundamental design principles yields substantial returns.