A short piece of fiction, written by API Evangelist. The reader is imagined; the post, and every number and quotation from it, is real: "Designing For The Agentic Experience at Nordic APIs," Kin Lane, November 10, 2026, https://apievangelist.com/2026/11/10/designing-for-the-agentic-experience-at-nordic-apis/
Marit wrote documentation for a payments team, and she read the post on a Tuesday evening with a cold cup of tea beside her. A colleague had sent the link with no comment, which was how he sent things he wanted her to have opinions about.
The first thing that landed was Erik's point that a developer carries informal knowledge into an integration: which APIs matter, how they fit together, what the business is trying to do. Point an agent at a pile of APIs and that knowledge disappears. Marit had spent six years being the place where that knowledge went to live. She had never thought of her job as supplying context to a machine, but she recognized the shape of it immediately. Half her pages existed because someone once asked her how two endpoints were supposed to work together.
The part about the author running APIs.io with an agent for each plan, plus a product manager agent that implements the issues, made her uncomfortable, and she let herself stay uncomfortable. It sounded tidy. Daniel, the post says, called it a romantic idea that most companies are not living yet, and she felt relieved that someone had said so. She also noticed the author's own admission that it works because he is a one-person company with sixteen years of context sitting in Markdown and YAML. Her team had none of that. They had a wiki, three half-maintained OpenAPI files and a style guide nobody had opened since a reorganization. If the foundation was sixteen years of tidy files, then the story was about the files, not the agents, and her files were not tidy.
She was also unsure about the advice to turn agents loose on your APIs and see what breaks. Her company would never allow that on a Tuesday, and she suspected the first thing an agent would break was her sense of how good the docs were. Still, she could not argue with the logic of finding weak spots by having something use the API every day.
Then she reached Erik's thirty-day answer, and it was the one she could actually use: improve the descriptions, with more examples, better errors and better explanations, before you touch any implementation. That did not require a budget or a reorganization. It did not even require anyone's permission, because descriptions were the one layer she already owned.
She was not going to adopt Arazzo workflows or an agents.md file this month, and she was not going to claim her estate was agent-ready. She would not be measuring anything either, because she had no way to yet.
She opened the OpenAPI file for the refunds endpoint, the one that generated the most support tickets. Its description was a single sentence that restated the path. She wrote three paragraphs: what the operation is for, what must already be true before calling it, and what each error actually means in practice. She added one realistic example request. Then she saved the file, opened a pull request, and left the implementation alone.