How should I build APIs for AI applications?

This question splits into two things depending on what you mean: building an API that AI agents will consume, or building an API that wraps/serves an AI model. Given our conversation's context, I'll focus on the first (agent-facing APIs), with a note on the second at the end.

Design for machine consumption from the start

• Serve a machine-readable spec at a standard, discoverable path — /openapi.json or /openapi.yaml, plus increasingly llms.txt and llms-full.txt files that give an LLM-optimized summary. This can cut token consumption by over 90% compared to an agent trying to parse HTML documentation

• The practical bar: an LLM that's never seen your API before should be able to call the right tool with the right arguments on the first try, recover from errors without human help, and chain to the next tool without extra prompting. If it can't do all four, the spec needs work regardless of how good your human-facing docs are

• Agents can't ask for clarification the way a human developer can — they read the spec and either succeed or fail. So parameter descriptions, response schemas, and error codes need to be complete and accurate, not just "good enough for a human skimming it"

• Authentication: skip OAuth's interactive flow for agents

OAuth 2.0 assumes an interactive human approving access, which doesn't fit automated agents well

• API keys with scoped permissions are the standard, more practical pattern for agent/server-to-server auth — stateless, easier to manage at scale, and programmatically rotatable without a human in the loop

Idempotency matters more than it does for human-driven APIs

• Agents retry requests due to timeouts or uncertainty about whether a prior call succeeded — without idempotency keys, this causes duplicate actions. This is a real, documented failure mode: a payment API lacking idempotency protection allowed orders to be placed without charging users when retries and connection failures happened Build idempotency keys into any endpoint with side effects (payments, state changes, resource creation), not just as a nice-to-have

Predictable, typed, well-defined errors

• Agents fail silently when they hit an undocumented error shape — no schema to parse means no way to recover or retry intelligently Standardized, typed error responses across all endpoints (not ad hoc per-endpoint error formats) let an agent actually reason about what went wrong and what to do next

• Security: assume adversarial-scale traffic, not just adversarial intent

• Agents can hit your endpoints thousands of times a second even without malicious intent — just through retry loops, exploration, or bugs in their own reasoning

• Roughly half of developers surveyed in 2026 report specific concern about unauthorized or excessive API calls from AI agents — rate limiting, scoped permissions, and abuse detection need to be part of the initial design, not bolted on later

• RFC 9700 (current OAuth 2.0 security best practices) deprecates the Implicit Grant and Resource Owner Password Credentials flows — if your API still uses either, that's worth fixing regardless of AI consumers

Consider MCP as a parallel interface, not a replacement

MCP gives AI agents a standardized way to discover and use your API's capabilities, including machine-readable metadata and natural-language descriptions that plain REST/OpenAPI don't carry

The practical pattern several platforms now support: expose the same backend logic through both a traditional REST API and an MCP-compatible interface from one source of truth, so you're not maintaining two separate implementations

• (Worth remembering from our earlier conversation: sentiment on MCP specifically has become more mixed through 2026 — some production teams have pulled back toward direct API calls and CLIs for token efficiency, so treat MCP as one option to evaluate, not an automatic requirement)

Architectural style choice for agent-facing APIs

• REST with SSE for streaming remains the default for public-facing, agent-consumed APIs in 2026 — wide compatibility, simple caching, easy debugging
• GraphQL only if multiple divergent client types (including agents) genuinely need different data shapes from the same underlying data and over-fetching is a measurable problem — not by default

If you actually meant "building an API that serves an AI model" (i.e., wrapping an LLM)

• That's a different problem — you'd be looking at things like: streaming responses via SSE for token-by-token output, request queuing/backpressure for expensive inference calls, cost/usage metering per request, and potentially a model-routing layer if you're serving multiple models. Let me know if that's actually what you meant and I can go deeper there instead.