Something has shifted quietly. The people who write API docs still imagine a human on the other end: someone who reads examples, follows links, understands context, knows when to ask for help. But that human is increasingly not the one writing the code. An LLM is. And the LLM reads your API differently than a person ever did.
This is not about the obvious stuff. It is not about code generation being faster or slower, or about developers losing their jobs, or about prompt engineering. It is about a change in who the consumer of an interface is, and what that consumer needs to operate correctly. The consumer of your API is increasingly a machine generating code, not a human reading docs. This changes type systems, error messages, documentation patterns, language design, and the economics of interface design itself.
The first sign of the shift is visible in the pendulum of API design history. SOAP was machine-first: WSDL contracts, strict schemas, generated stubs. Everything was a spec. Then REST happened, partly as a rebellion against that machine-first world. Humans wanted readable URLs, discoverable resources, docs you could curl and understand. REST was the consumer internet saying "make this usable for people." Now AI agents are swinging the pendulum back toward machine-readable contracts, but with a twist: this time the machine consumer is non-deterministic. A WSDL client either works or it does not. An LLM calling your API might guess wrong, hallucinate a parameter, or silently misuse a return value. The old machine-first approaches assumed deterministic consumers. We need something between the strictness of SOAP and the ambiguity of REST, something designed for probabilistic consumers.
Consider what happens when an API gives an ambiguous error. A human reads "403: insufficient permissions" and knows exactly what to do: find the person who manages access, file a ticket, wait. An AI agent has none of that social context. It retries with different headers. It changes the authentication method. It tries the endpoint without parameters. It hallucinates a workaround. It loops. The error message costs differently per consumer type: humans pay the cost of context switching to find a human who can help, machines pay the cost of a search loop that might never converge. Error messages designed for AI consumers need to say exactly what to do next. "You need write access to the widgets collection. Contact your admin at admin@example.com" is a useful error. "403 Forbidden" is a tax every AI agent pays forever.
The same logic applies to versioning. A human reads changelogs. An AI agent was trained on code written against v1 of your API and has no idea v2 exists. The v2 docs are invisible to it because they were published after its training cutoff. API versioning breaks fundamentally when the consumer is an LLM trained on old code: the new version is not discoverable through any mechanism the agent has access to. Migration requires either retraining (expensive, slow) or runtime shims that translate between versions transparently. We are going to see a resurgence of backward-compatible API design not because it is elegant but because the alternative is millions of LLM-generated calls targeting dead endpoints.
The token overhead of API interaction is becoming a real design constraint. Claude Code sends around 33,000 tokens of scaffolding for a typical interaction. OpenCode sends about 7,000. When AI agents consume APIs, every piece of chatty interface design has a dollar cost proportional to the context window. APIs that minimize token overhead for common operations win. This is a new axis of interface quality: not just latency or throughput, but the token cost to get from zero to a useful call. A verbose API that requires three round trips to discover a base URL and authenticate and call the actual method costs real money when every round trip consumes context.
This points to something concrete: the capabilities endpoint. Every API should serve a /capabilities endpoint returning a minimal machine-readable operation list. Not OpenAPI, which is too verbose for context windows, just endpoint plus params plus return type. AI agents need a navigation protocol because they cannot browse docs, click links, or infer structure from examples the way a human does. They need a machine-readable table of contents that fits in 500 tokens.
Type systems matter more than ever here. When an AI consumes your API, the type signature is not documentation: it is the sole contract. TypeScript's edge over Python for AI coding agents is not ergonomics or developer experience. It is that the type system constrains the search space. Given a function signature `(a: number, b: number) => number`, an LLM has a narrow range of valid calls. Given a Python function with no type hints and the name `process`, the LLM is guessing. Consistency in type design is the new documentation surface. Here is a test: give an LLM your type signatures with zero docs. If it produces a working call on the first try, your API is consistent enough for machine consumption. If it fails, every AI agent forever pays the same guessing tax.
The determinism question cuts deeper than type signatures. Consider browser fingerprinting: Math.tanh in Chromium 148 returns OS-specific floating-point values. The same deterministic precision that lets scrapers identify users is what AI coding agents need from APIs. Machine consumers and fingerprinters both want deterministic, predictable behavior. The question is who controls the API's behavior and how much variation they allow. An API with OS-dependent return values is useless to an AI agent that needs to write cross-platform code. Predictability at the edges, even for edge cases, becomes a feature.
There is a deeper convergence at work. Are APIs adapting to machines, or are machines adapting to existing APIs? Both happen simultaneously but at different velocities. Prompt engineering adapts weekly: new patterns, new chain-of-thought tricks, new ways to help LLMs navigate existing interfaces. Type system redesign takes years. The gap between these speeds determines who bears the adaptation cost. For now, the burden falls on the machine consumer: prompting gets more creative, tools get more scaffolding, context windows get larger. But this is not sustainable. At some poin