How to read API documentation
Corbin Brown
2 min read
Here's a vibe coding paradox: your agent writes all the API code, yet the ability to read API documentation still pays off constantly. The reason is that agents were trained on yesterday's docs — providers change endpoints, rename parameters, and deprecate features, and an agent confidently writing against the version in its memory is one of the most common failure modes in modern building. The fix is you, spending ninety seconds in the current docs and handing the agent the right page.
Docs are a menu — read them like one
Every API doc, from Stripe to some indie weather service, has the same skeleton. Authentication: how to prove who you are (almost always an API key in a header). Endpoints: the list of things you can ask for, each with a URL and a verb — GET fetches, POST creates, DELETE removes. Parameters: the options for each request, with required ones marked. Responses: the shape of what comes back, usually shown as example JSON. That's the whole grammar. You're never reading docs cover to cover — you're finding the one endpoint that does your thing and checking its ingredients.
The agent-era workflow
- Find the endpoint yourself, then link it: “Add a refund feature using this endpoint: [URL].” Grounding the agent in the live page beats “add refunds via Stripe” every time.
- Steal the code samples. Docs ship official examples in every language — paste one into chat and say “adapt this to our project.” Now the agent starts from the provider's own current truth.
- When integration code fails mysteriously, suspect version drift first. Check the docs' changelog or migration page; if the API changed, that page is exactly what to paste into the chat.
FAQ
What's the fastest way to test an endpoint before building?
Most modern docs have a “try it” button that fires real requests from the browser — use it to confirm the endpoint returns what you expect before any code exists. No try-it button? Ask your agent to make the test call and show you the raw response.
What does “rate limited” mean in docs?
A ceiling on requests per minute or day. Blow past it and the API returns errors until the window resets. It matters at the design stage: if you'd need to call an endpoint once per user per page view, check the limit math before your agent builds it that way — and mention the limit in your prompt so it adds sensible caching.