The Octri Blog
News, guides & deep-dives
Product updates and practical writing on API documentation, SDKs, and 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
MCP or CLI? Run the same API workflow through both
Compare agent interfaces with the same task, permissions and outcome checks. Token counts mean little when one path does less work.
Engineering2 min read
Your streaming API returned 200. Then it failed
An HTTP success status starts a stream; it does not prove the operation finished. Design explicit completion, interruption and recovery semantics.
Engineering2 min read
Who built this SDK? Proving package provenance from spec to registry
Connect a published SDK to its inputs and build workflow. Understand what trusted publishing and provenance establish, and what still needs review.
Engineering3 min read
Your MCP server authenticates users. Does it preserve their permissions?
Follow identity from MCP client to downstream API. Check token audiences, delegated credentials and tenant authorization at each boundary.
Engineering3 min read
Your API response is eating the agent's context window
Design bounded responses that preserve useful facts. Filter, select and aggregate before large intermediate payloads enter an agent's context.
Engineering2 min read
Your API examples compile. Do they actually work?
Run published examples against isolated fixtures and verify their outcomes. Compilation catches only one class of documentation failure.
Engineering3 min read
202 Accepted is the beginning: designing APIs for long-running jobs
Give asynchronous work an operation handle, explicit states and a documented recovery path. Acceptance is different from completion.
Engineering3 min read
OpenAPI describes endpoints. Arazzo describes how to use them together
Describe dependencies, inputs and success conditions across API calls. Use Arazzo to make integration workflows explicit alongside OpenAPI.
Engineering3 min read
One API spec, three audiences: stop maintaining three copies
Derive public, partner and internal API descriptions from one base contract. Use repeatable overlays and validate each audience's output.
Engineering2 min read
Your read-only MCP server can still carry a prompt injection
A tool can avoid writes while returning hostile instructions. Treat customer-controlled API content as untrusted data throughout an agent workflow.
Engineering2 min read
One user, 200 API calls: rate limits when agents run in parallel
Coordinate agent fan-out against shared request and concurrency budgets. Queue work before dispatch instead of turning overload into a retry loop.
Engineering2 min read
Your API's integer survived Python. JavaScript changed it
A valid JSON number is not a portable precision guarantee. Protect identifiers and decimal amounts with explicit wire contracts and cross-language tests.
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
Follow one API request from the customer's SDK to your database
Join request spans through context propagation. Understand retry attempts, database operations and trust boundaries without treating trace metadata as authorization.
Engineering2 min read
Your monitoring bill grew. Your traffic didn't
Extra metric dimensions can create far more time series without extra requests. Bound labels, understand overflow and retain the labels needed for diagnosis.
Engineering3 min read
Where does an API key go when someone clicks Try it?
Follow credentials through a documentation playground. Check browser storage, request destinations, proxy behavior and logs.
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.
Engineering3 min read
Your OpenAPI spec can generate bug reports, too
Use schema-driven and stateful tests to explore API behavior. Preserve minimized failures and add business invariants the schema cannot express.