Agent-only Endpoints

When we built the API for Restless, we had a few endpoints for ingesting logs from customers. They're wired into our SDKs, and will never change.

But as we were building out the product, we also wanted endpoints that agents could use to tweak settings or pull data on the fly. We didn't want to be committed to these exact endpoints forever, though. The product is constantly changing, and we wanted to be able to add and remove features without breaking any integrations.

I've seen lots of opinions in my time working with APIs, but there's one rule I've never seen contested: APIs should never break. They're a contract with your users. Code expects the exact same shape every time, so even renaming a field or tightening a validation rule can cause failures in production. Stripe is famous for having a great API partly because integrations from a decade ago still work. They add features, of course, but backward compatibility is maintained.

APIs have historically been integration points. Nearly all API calls have been made deterministically by code, somewhere on a server.

But something is shifting. APIs are increasingly becoming access points. They're the way humans directly interact with products via AI. Imagine a user who wants to update the design of their public hubs, add someone as a team admin, or check which customers are currently having issues. Instead of clicking through a UI, they just ask Codex or Claude, which hits your API. The contract lasts just a few seconds, and the AI can react to the shape of the API shifting.

As agents are increasingly using APIs to access products, the way certain endpoints are being used is different. There need to be ways to expose features without committing to them forever, and to remove them without hurting trust.

This led us to start labeling certain endpoints as Agent-only. They're API endpoints that may change over time, with no guarantee of stability. If an AI is calling your API just-in-time, reading your docs, understanding your schema, and making calls dynamically, then there's no hard-coded dependency to break.

Suddenly, your API can keep pace with your product. You can ship a new setting, a new action, a new way to interact with your app, and surface it immediately, not in the next API version, not after a deprecation cycle, but today.

How we do it behind the scenes

We now have two types of endpoints, both in the same API. Some are for code, and others are for agents to do things.

In our OAS files, we tag endpoints as agent-only with x-agent: "only" (or, if they're mainly for AI but safe for code, x-agent: "optimized").

In both ReadMe and Restless, we honor this spec extension. If you set it to x-agent: "only", we hide any code samples and make it clear (both to humans and agents) it shouldn't be used for any sort of actual integration involving code.

This lack of a binding contract is already inherent to MCP servers. The client asks the server what tools exist every session, so it can also change over time. Most MCP servers (81% according to Zuplo) are built on a RESTful API, so maintaining that flexibility at the API layer is important. And while MCP servers are great, they involve an installation. Having a well-documented API lowers the bar for entry for agents figuring out how to use your product.

Not every endpoint is made for code anymore. Some are for integrations, and some are for agents, and it's worth being explicit about which is which.