You run developer relations for a mid-sized API company. Your changelog is a page nobody has touched since spring, your reference docs are prose with a few code blocks, and this week someone on your team asks whether any of it is ready for AI agents. You go looking for advice, and you land on Zapier's guide to API documentation, how to write it and examples.
Much of it is familiar. Reference docs, guides and tutorials, code samples, release notes and changelogs. The bluntest line is the one you will probably quote in your next meeting: "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 that matters to you is the newer one. "A growing share of your 'readers' aren't people anymore," Zapier writes. 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. Then the practical list: give every status code 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, and test the documentation itself, ideally with automation.
You should know what kind of source this is. It is a content-marketing post. It has no vendor figures to discount, only advice, and the advice stands or falls on its merits. None of it is new. But the framing is right, and Zapier gets credit for putting the agent audience inside every format rather than bolting on a separate "AI docs" page.
So you do what the post invites you to do: you check whether Zapier writes what it recommends. The APIs.io catalog lists Zapier with 13 API pages, and the agent half of the story is visibly there. A Zapier MCP server and a Zapier AI Actions API are the structured layer, instead of agents guessing at endpoints from prose. The surface agents act on is documented too, across the Actions, Zaps, Authentications and Inputs APIs. The agentic access profile counts 27 operations, five of them acting.
The measurements mostly back the post up. Zapier scores 67.4 on the Kin Score, rated 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, an MCP server, a well-known catalog and dynamic client registration all lit. That is the status-codes-and-examples advice, measured, and it holds up.
Then comes the turn, and it is the part you should not skip. The weakest facet is contract governance at 28.0, the lowest of the six, and it is the one that tracks the post's own release-notes-and-changelogs advice. The company that tells you changelogs keep users from wandering off scores lowest on the facet closest to that practice.
The agent side has gaps too. Idempotency, reversibility and dry-run mode are unlit. That 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, and the docs alone cannot tell it.
What you take away is practical. The agent-docs advice is sound, and following it shows up in the numbers: a spec beside the prose, real examples, clear error semantics, an MCP server. But even a company with an exemplar rating and a content team writing guides on the topic has a soft spot where its own advice is hardest to follow. Before your next meeting, look at your own changelog and your own acting operations. Ask whether an agent reading your docs would know what happens when it calls something twice.
Read the original: https://apis.io/2026/11/03/zapier-says-agents-now-read-your-api-docs-and-its-own-docs-mostly-pass/