Zapier’s guide to API documentation, how to write it and examples covers ground every developer-relations team knows: reference docs, guides and tutorials, code samples, and release notes and changelogs. Its sharpest line is the blunt one: “Poor or missing docs are the fastest way to kill adoption, as developers simply don’t have time to reverse-engineer your endpoints or guess at parameter formats.” The section worth reading, though, is the newer one. “A growing share of your ‘readers’ aren’t people anymore,” Zapier writes, and its advice is to ship a structured spec, OpenAPI or JSON Schema, next to the prose, with endpoint descriptions written in plain English an agent can reason about.
This is a content-marketing post, and it has no vendor figures to discount, only advice. The advice survives on its merits. List every status code with its meaning in your system’s context. Show explicit request and response examples. Treat changelogs as the thing that keeps users from Googling a competitor’s API. Test the documentation itself, ideally with automation. None of it is new, but the agent framing is right, and Zapier gets credit for putting it inside every format rather than bolting on a separate “AI docs” page.
The catalog lets us check whether Zapier writes what it recommends. Zapier on apis.io carries 13 API pages, and the agent half of the story is visibly there: the Zapier MCP server and the Zapier AI Actions API are exactly the “structured layer instead of guessing at your endpoints from prose” the post describes. The platform surface agents act on is documented too, across the Zapier Actions API, Zapier Zaps API, Zapier Authentications API and Zapier Inputs API. The agentic access profile counts 27 operations, five of them acting.
The measurement mostly confirms the post. Zapier scores 67.4 on the Kin Score, exemplar, with developer ergonomics at 74.4 and contract quality at 71.5. Agent Readiness is 66.0, agent-ready, with spec presence, error semantics, OpenAPI examples, MCP server, well-known catalog and dynamic client registration all lit. That is the status-codes-and-examples advice, measured. The weak facet is contract governance at 28.0, the lowest of the six, and it is the one that tracks the post’s release-notes-and-changelogs advice. On the agent side, idempotency, reversibility and dry-run mode are unlit, which matters more now that five of those 27 operations act. An agent that reads the docs perfectly still needs to know whether running a Zap twice is safe.