Why Most APIs Fail in AI Systems and How To Fix It

"Over the past few years, I've reviewed thousands of APIs across startups, enterprises and global platforms. Almost all shipped OpenAPI documents. On paper, they should be well-defined and interoperable. In practice, most fail when consumed predictably by AI systems. They were designed for human readers, not machines that need to reason, plan and safely execute actions. When APIs are ambiguous, inconsistent or structurally unreliable, AI systems struggle or fail outright."

"Integration, Not Intelligence, Is the Real Challenge As influential founder Tim O'Reilly recently argued, the real challenge in achieving value from AI is not making models smarter, but integrating them into existing systems and workflows. Intelligence is rapidly becoming a commodity. Integration is the moat. Enterprise AI initiatives run aground on this reality repeatedly. Studies show companies eagerly experiment with AI, but only a small fraction of pilots reach production, and in some cases, as low as 5%."

"If those APIs are unclear, unsafe or incomplete, no amount of model capability can compensate. To understand how APIs behave when consumed by intelligent systems, we analyzed more than 1,500 public APIs. Each API had to be parsed, validated and interpreted in a machine-first way, not just skimmed as human documentation. The patterns that emerged were sobering: Servers often missing or misleading: Many OpenAPI documents had no servers defined. When present, the first was often QA or sandbox rather than production."

Thousands of APIs across startups, enterprises and global platforms commonly ship OpenAPI documents that appear well-defined but are often unsuitable for machine consumption. APIs frequently lack accurate server definitions, and authentication details are unclear or absent, preventing safe automation. Structural validity issues such as missing path parameters, unresolved references, and incoherent schemas create failures for AI systems that must reason, plan and execute. Integration, not model intelligence, is the primary barrier to AI value because intelligence is becoming commoditized while integrating models into existing systems and workflows remains difficult, causing many pilots to never reach production.

Read at thenewstack.io