The API Was Written for Someone Who Isn't Coming

Share
The API Was Written for Someone Who Isn't Coming

Let's say you ask an agent to check a customer's latest order. It does not open a browser, hunt for a menu, and click the button that says Order history. It looks for an address — a URL — and sends a request: give me this person's orders.

That request is an API call (yes, I'm talking about API calls again, but for a different reason). API means Application Programming Interface: an agreed-upon way for one program to ask another program for something. On the web, that ask usually travels as HTTP. The answer usually comes back as JSON, a simple way to write data as text so computers can send it and humans can still read it.

If the API was built the way most APIs are still built, here is what the agent finds.

The API documentation says, "See the example on the right." Technically there is no "right" when you are not looking at a webpage. There is, however, a field named created in one place on the webpage and created_at in another part of the webpage. When an error comes back as `Something went wrong', a person would shrug, open Slack, and ask for help. But not the agent. The agent retries automatically. Then it guesses. Then it calls the wrong thing.

This is the difference between a human and an AI agent. Nothing crashed in the demo when a human tried it. The human could read between the lines and see what is really going on. The agent cannot. They are more black and white.


89 and 24

Postman's 2025 State of the API Report surveyed more than 5,700 developers, architects, and executives around the world. Two numbers from that survey are doing most of the talking.

89% of developers were using generative AI in their daily work.

24% were designing their APIs with AI agents in mind.

Read that again slowly. Almost everyone on the building side had already picked up the new tool. Almost nobody on the product side had rebuilt the door the new visitor would walk through.

The 24% is not even "agents only." Postman broke it down further. About 13% said they design equally for humans and agents. About 7% said they design primarily for agents — for machines reading the response, not people reading the docs. Another 5% said they were in the middle of switching. The rest of that "one in four" is people who have started, not people who have finished.

Meanwhile, about 60% still design APIs primarily for humans. 16% had not even considered that an agent might be a consumer.

The consumers had changed faster than the producers. Agents were already hitting APIs. Most APIs were still written as if a human would read the docs and write the client by hand.


What "Written for a Human" Actually Means

It does not mean the API is bad. A lot of those APIs work fine when a person is in the loop.

A person can:

  • Skim a long page of documentation and ignore the outdated screenshot
  • Notice that status is sometimes "failed" and sometimes "FAIL" and handle both
  • Hit a rate limit, wait, try again after lunch
  • Read Something went wrong and go look at the logs
  • Ask a teammate which of three similarly named endpoints is the real one

An agent does not do any of that well. It does not "notice." It does not "ask around." It takes the words in front of it and acts.

So "designed for a human" really means:

  • The docs assume eyeballs
  • The field names are a little sloppy because a person can map them
  • The errors are written for a developer, not for the next call
  • The limits assume someone who gets tired
  • The examples live in a blog post from 2019

A short example. A person writing a mobile app reads: "To add a song, POST to /playlists/{id}/songs." They copy the example, try it, fix a typo, ship it. An agent given "add this song to the playlist" has to find that sentence among three other endpoints that also mention songs, guess whether {id} is the playlist or the user, and decide if the body wants songId or track_id. If the docs are messy, it does not ship a slightly wrong app. It posts the song to the wrong list. Or it posts it ten times.

The API made a promise. Clients — people, apps, now agents — build their lives around that promise. Then someone "just adds a small change," and the thing that trusted the old answer falls over. When the client was a person, you heard about it. When the client is an agent, you hear about it as a spike of traffic and a pile of bad data.


Agents Don't Scroll. They Fan Out.

A person looking at GitHub opens a file, maybe two, and reads them. An agent that is "looking at the repo" does not sit and scroll. It asks the system for a lot of pieces at once: the folder list, the file contents, the tests, the last ten changes. Each of those asks is an API call. So one "look at my code" from you can turn into dozens of requests behind the scenes.

That is why this gap is not a documentation nit. It is a volume problem and a shape problem.

Gartner had already said that by 2026, more than 30% of the increase in demand for APIs would come from AI and tools that use large language models. Cloudflare has said that more than half of the dynamic traffic it sees — the requests that aren't just a cached file — is API-related. GitHub's own platform, by 2026, had agents starting more than 40% of pull requests. Those pull requests are not chat replies. They are chains of calls: read, edit, test, commit, open the PR.

If only a quarter of APIs were designed with that consumer in mind, the other three quarters are being used as if they were.

You can feel this inside a single company, not just on the public internet. Turn on an in-house agent — a support bot, a Copilot in the editor, a "ask the product" box — and every user question becomes a workflow. Look up the customer. Look up the order. Look up the ticket. Generate the answer. Log the conversation. Update the pulse. One message in the chat. Ten, twenty, a hundred calls on the graph.

The API that was written for a person clicking Save once is now being asked the same question, correctly and incorrectly, at machine speed.


The Rest of the Gap Looks Like the First Gap

Postman did not only ask "do you design for agents?" They asked what else is lagging. The answers have a particular rhyme.

The new handshake is famous. Few use it.
The Model Context Protocol — MCP — is a way for an agent to discover what it is allowed to touch: here are the tools, here are the fields, here is how you call them. At the time of the survey, 70% of developers had heard of it. 10% were using it regularly. Another 24% said they planned to explore it. Hearing about a tool is not the same as putting it to work. The new rules are still catching up to what agents are already doing — same as the APIs.

We test that the server works. We barely test that the promise held.
Developers are pretty good at checking that the server works. Many are not very good at checking that the API still sends back what it said it would. An API makes a promise: if you ask this way, you’ll get this back — the same fields, in the same form. Functional tests and integration tests each sat around 67%. Contract testing — did that data still look like what last year’s app expected? — sat at 17%.

That’s the test that catches the Thursday problem. The demo account still looks fine. However, two partner companies that integrate their product with your's still expect created_at to show up in an API call as a date written as text. On Monday it shows up as a number, which then broke their integration. A person might catch that in QA, but an agent will not. It will just send the new version of that data to everything it can reach.

The docs are already a mess for humans.
93%
of teams reported collaboration problems: inconsistent documentation, duplicated work, difficulty finding APIs that already exist. 69% of people in the survey spent ten or more hours a week on API-related work. If a human teammate cannot find the right endpoint, an agent guessing from a stale wiki page does not have a better chance. It just fails faster, and more often.

Security was built for a person with a password.
51%
of developers named unauthorized or excessive agent calls as a top concern. 49% worried about AI systems reaching data they should not see. 46% flagged credentials leaking or keys that can do too much. A person clicks, gets tired, goes home. An agent with a key that is too powerful does not get tired. Rate limits meant for a mobile app in someone's pocket do not mean the same thing when the caller is a loop.

None of that is a reason to keep agents away from APIs. It is a picture of APIs that were never asked to survive this kind of visitor.


What "Designed for an Agent" Looks Like

It is less glamorous than the 89% makes it sound. It is mostly the same work that makes APIs better for people, but done on purpose.

Name the thing the same way every time.
/users/45821/orders is the orders. Not /getLatestOrder in one place and /user-orders in another. REST already wants this — resources, and the same HTTP methods everywhere: GET to read, POST to create, PUT or PATCH to change, DELETE to remove. Agents like REST because that grammar is already everywhere. They can reuse what they learned on GitHub when they later talk to Stripe or Jira. They cannot reuse a nickname you only explained in a meeting.

Keep the promise stable, or say when it changed.
If created_at is a date written as text, it stays a date written as text until you version the API and tell everyone. Contract tests are how you find the break on Thursday. Agents are how the break becomes everyone's problem on Monday if you don't.

Make errors actionable.
400: created_at must be an ISO-8601 string is something an agent can use. Something went wrong is something an agent will retry until a rate limit saves you, or doesn't.

Write docs a machine can parse.
A paragraph with a screenshot is for a person. A schema, an example request, an example response, and a list of error codes is for both. The person can still read it. The agent can finally use it.

Assume the caller will not get tired.
Limits, keys that can only do one job, a way to tell a human click from an agent workflow. Postman's respondents were already nervous about this. They should be. The volume is the point of an agent. The volume is also the incident.

A short example. Same question as before — latest order for customer 45821.

Written for a person:

"You can find order history under the customer record. Click through to see the most recent."

Written for an agent (and still fine for a person):

GET /users/45821/orders?limit=1
{
  "id": 9901,
  "customerId": 45821,
  "total": 49.99,
  "status": "failed",
  "created_at": "2026-11-10T14:02:00Z"
}

The second one is not "more technical." It is more honest. It says what to ask, and what you will get back. A person can still click a button that makes that same call. An agent can make it without the button. Either way, the promise is the same.


The Funny Part

Developers did not skip designing for agents because they hate agents. They are the 89%. They use ChatGPT, Copilot, Gemini. They ask an agent to write the client, find the bug, open the pull request.

They just still publish APIs the old way. For a teammate who will read the README. For a mobile app that a person will tap. For a partner who will email if something looks off.

That teammate is still real. The mobile app is still real. The partner is still real. They are no longer the only ones in the room.

Postman also found that 82% of organizations had adopted some level of "API-first" — treat the API as a product, not an afterthought — and that fully API-first teams were the ones more likely to make real money from those APIs. REST still dominated, at 93%. The industry knows how to build this. It has not yet admitted who the new reader is.

MCP will help some of it. Better catalogs will help some of it. None of it replaces the boring work: same field names, same types, errors that mean something, a test that fails when the promise moves.


Bottom Line

The docs are still written like a person is coming. Someone who will squint at the screenshot, ping a teammate, and write the client by hand.
That person still exists. They are just no longer the one making most of the calls.

Almost every developer is already using AI. Almost every product is growing a chat box, a Copilot, an agent that "just does it." Those agents do not think their way into Stripe or Jira or your own order system. They call. They call a lot. They call in shapes the original authors never sat down and designed.

So the APIs that were written for a person who would read the docs and write the client by hand are now being read by something that does not read like a person and does not write the client by hand. It guesses from whatever it can find, as fast as it can, until the job looks done.

Companies need to stop publishing APIs as if only a person will read them. So if you are in charge of API creation or documentation at your company, design the next endpoint — and fix the old ones that matter — as if the next caller has no eyeballs, no Slack channel, and no patience. Name it clearly. Keep the structure. Spell out what’s in the response — every field, every type — and write the docs so an AI can follow them. That’s how the tools we already rely on become as useful as we expect them to be.