The Octri Blog
News, guides & deep-dives
Product updates and practical writing on API documentation, SDKs, and developer experience.
Showing articles tagged #developer-experience.
Engineering2 min read
Can an AI agent actually integrate your API? Build an eval to find out
Give an agent a real task, an isolated sandbox and a result you can verify. Check the records and code the agent produces.
Engineering2 min read
Works in Node.js. Breaks at the edge. Is your SDK portable?
Test SDK behavior against named runtimes and versions. Successful imports and familiar web APIs do not establish full runtime compatibility.
Engineering3 min read
Your sandbox always succeeds. That's why integrations fail in production
Design deterministic failure scenarios alongside happy paths. Give humans and agents a safe place to practice the behaviors production integrations need.
Engineering3 min read
Measure your API docs by the first successful request
Follow onboarding from discovery to a verified result. Track completed steps and find where developers get stuck without collecting secrets or customer payloads.
Guides5 min read
API-first in practice: what changes when the spec is the source of truth
The phrase is used to mean four different things. Only one of them changes how your team works, and it is the one that makes the spec a build input rather than a report.
Engineering5 min read
Should you hand-write your SDKs or generate them?
The honest answer depends on how many languages you ship and how often your API changes. For one language and a stable API, hand-writing wins.
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.
Engineering5 min read
41% of APIs drift within 30 days, and most of it is invisible
Schema drift is not usually a breaking change. It is a field nobody told you about, found by a test that failed in CI two weeks later.
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
How many tools should an MCP server expose?
Exposing your whole API to an agent makes it worse, not more capable. Tool choice is a selection problem, and every extra option makes the selection harder.
Engineering6 min read
Giving an agent write access to your API: what to exclude first
A tool call is a real request against a real API. Before you connect one, the question is not which endpoints to expose. It is which ones an agent must never reach.
Product3 min read
The Octri CLI: Your Whole Project From a Terminal
One binary pushes your spec, builds SDKs in ten languages, publishes docs, uploads source maps from CI, and reads back the production errors those SDKs report. It carries an MCP server, so an AI assistant can drive the same commands.
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.
Engineering5 min read
Why coding agents invent endpoints you never shipped
An agent asked to integrate your API will recite one it saw in training or guess from the name. Both produce code that looks right and does not run. The fix is not a better prompt.
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.