The Agent-Era API Standards Onramp

About this paper

A team shipping its first public API used to have years to grow into the standards. The agent era collapsed that timeline: the five-year API maturity journey is now a five-week onboarding, and the engineer who drew the short straw is staring at OpenAPI, JSON Schema, Arazzo, discovery metadata, MCP, agent skills, AGENTS.md, async patterns, and agent-payment standards all at once — with nobody telling them what to learn, when, or why. The result is either paralysis, or a pile of half-adopted standards that don’t reinforce each other: an MCP server bolted onto a spec that was never right, agent skills describing an API nobody can discover, a payments layer on an operation that can’t yet be trusted to read safely. All of it comes from the same missing thing — there is no sequence.

This paper is that sequence. Eight rungs in the order I would put them if you were starting today — OpenAPI, JSON Schema, Arazzo, discovery, MCP, agent skills, async, and agent payments — each with its minimum viable artifact, the one governance rule that keeps it honest, and the single failure mode teams hit when they skip it. It closes with a bottom-up leadership buy-in playbook for making the case upward without sounding like AI hype, and a provider self-assessment that tells you which rung you are actually standing on. The one rule underneath all of it: this is a sequence, not a checklist you attack in parallel. Climb in order and every rung makes the next one cheaper. Skip around and you build failure into the foundation.

What's inside

1. The onramp, not the reading list
2. Rung one — OpenAPI, the contract
3. Rung two — JSON Schema and shared properties, the data elements
4. Rung three — Arazzo, the workflows
5. Rung four — APIs.json and discovery metadata
6. Rung five — MCP, the agent-facing surface
7. Rung six — Agent skills and AGENTS.md, the operational context
8. Rung seven — Async patterns, beyond request/response
9. Rung eight — Agent-payment and commerce standards, only when transactable
10. The bottom-up leadership buy-in playbook
11. Anti-patterns I'll be watching for
12. Provider self-assessment

What you get for $25.00