The Octri Blog
News, guides & deep-dives
Product updates and practical writing on API documentation, SDKs, and developer experience.
Showing articles tagged #api-documentation.
Guides5 min read
Documenting webhooks in OpenAPI 3.1, and the half it cannot describe
3.1 finally gave webhooks a home in the spec. It describes the payload, which is the easy part, and says nothing about delivery, which is where integrations break.
Guides6 min read
Getting your API docs cited when someone asks an AI about your product
People are asking assistants what your API does before they visit your site. What gets quoted back is decided by how your docs are structured, not by a file at your root.
Guides5 min read
Your MCP server needs documentation, and it is not your API docs
There is no spec format for MCP servers yet, so what an integrator gets is a README and a config snippet. Here is what actually has to be in it.
Engineering5 min read
llms.txt for API docs, and what AI crawlers actually read
A file at your docs root that tells a model what your product is and where to look. Cheap to publish, easy to get wrong, and not a substitute for the thing it points at.
Guides5 min read
Your changelog is part of your API
Every integrator eventually asks the same question: did something change? If the answer lives in a release-notes page nobody subscribes to, they ask your support queue instead.
Guides5 min read
The API docs your OpenAPI spec cannot generate
A generated reference answers what an endpoint accepts. It never answers which endpoint to call, in what order, or what to do when one fails. That part is yours.
Guides6 min read
How to Generate API Documentation from an OpenAPI Spec (2026 Guide)
How to generate API documentation from an OpenAPI specification, and how to keep it in sync so it stops drifting from your code.