Designing APIs for Agents - Freestyle Blog svg]:px-2.5" data-state="closed" data-slot="context-menu-trigger" style="-webkit-touch-callout:none">Freestyle<br>Search⌘Ksvg]:px-2.5" target="_blank">DocsDsvg]:px-2.5 md:mr-2">Sign InS

Ben Swerdlow<br>Founder/CEO

Ben is the founder and CEO of Freestyle.

Designing APIs for agents is different from designing them for humans. Most consumers of APIs today do so through agent-written code. This was not true two years ago, and it changes how we should think about designing them.<br>I no longer believe in most systems built for humans. I'm skeptical of most packages, I'm anti-utility, and I'm pro extremely long names now — all opinions I've done complete 180s on in the past 24 months.<br>Good APIs for humans<br>When I design a good API for humans, my first step is sketching the minimal usage patterns, the onboarding, and the top ten use cases. From those, I imagine the code I'd ideally write to get there. Then I try using it, find the edges where I got stuck, and add good defaults and configuration where necessary.<br>I want people to have something functional in fifty lines. From there, the API should be approachable enough that reaching for more functionality is obvious — that's where they'd look. Ideally, someone who needs only one of twenty fields should only become aware of the other nineteen through the autocomplete around the one they want. A good SDK should be self-explanatory enough that you can use it with only minimal skimming of the docs, if that.<br>Some great examples:<br>twilio.pyclient.messages.create(<br>body="Join Earth's mightiest heroes. Like Kevin Bacon.",<br>from_="+15017122661",<br>to="+15558675310",<br>stripe.tsconst paymentIntent = await stripe.paymentIntents.create({<br>amount: 1099,<br>currency: "usd",<br>automatic_payment_methods: {<br>enabled: true,<br>},<br>});<br>These embody the values above. I implemented both as a fourteen-year-old with no issues, and without having to learn about Stripe's tax options, what ACH is, or any of the fifty other things Stripe does — and without learning about Twilio's scheduling, bots, or anything else. Later on I did. But these SDKs let me make a ton of progress without knowing much about what was actually going on.<br>This is the opposite of how you should design for agents<br>AI agents can read our entire docs in one sitting. The average Claude Code prompt uses 10k+ tokens; on their first prompt, agents can read your entire API and every relevant document. They can also produce thousands of lines of code to reach their goals in seconds. This changes everything.<br>Good APIs for agents<br>Agents need clarity above everything else — APIs where reading the code tells you exactly what it does. There is a lot more code in the AI-agent era, which makes debugging much harder, and the only way to solve that is through precise definitions of what the code is expected to do.<br>That means:<br>Defaults are bad. Agents can be expected to read the documentation, register what good starting values are, and fill them all in, in place. Explicitness is cheap now, and bringing specificity to expected behavior reduces bugs. The examples above each had thirty fields I didn't fill in because I didn't comprehend them. An agent should fill in every single one.<br>This isn't to say the less important fields shouldn't have a comment between them and the more important ones to separate them — just that the tax on filling out large amounts of seemingly unimportant fields has disappeared, while the tax of understanding what code does has gone way up.

Errors are not bad. Many great APIs I've used have smoothed over my stupidity: accepting uppercase for lowercase-only fields and coalescing it, or accepting multiple keys for the same thing the way Postgres booleans accept true, yes, on, 1. This is actively bad for agent codebases. It leads to different functions using different values for the same thing, which causes headaches for later reviewers.<br>Modern harnesses can be expected to read the docs when debugging — bonus points if you tell them to in the error message. Half-correct coalescing should not happen; let the agent explicitly coalesce the values however it wants on its side. For humans, errors in onboarding are bad and you should minimize them. For agents, they are opportunities to clarify what something actually means.<br>This doesn't mean all errors are good. Blank internal errors with no direction make agents spiral, but that's an argument against bad errors, not errors. A good error is an amazing tool: it means the AI had a misconception about your API and solved it. And it will have misconceptions. Even with everything in context, backwards compatibility breaks and confusion happens. Errors that lead to clarity solve this.<br>Errors are one of the best surfaces an agent has for finding the happy path, but only if they're precise. Unlike humans, agents follow instructions literally, so a vague or wrong error makes them spiral instead of recover. In our data, 27% of the friction agents hit comes from...