# Designing APIs for Agents is no longer RESTful > Source: > Published: 2026-06-04 16:24:47+00:00 For thirty years, API design has been a discipline aimed at one reader. A human developer, sitting at a workstation, reading documentation, writing code that calls endpoints she already knows about. Every choice REST made and every convention OpenAPI standardized assumed this reader. The endpoints were stable because the developer needed to write code against them. The verbs were generic because the developer would translate her intent into the generic vocabulary on the way to writing the call. The contract was frozen at build time because the developer's intentions were knowable at build time. The reader changed. Agents now make most of the interesting API calls. The agent receives a goal at runtime, reasons about what it needs to accomplish that goal, and has to find or propose an endpoint that matches its intent in a single step. The agent has read no documentation. The agent has no prior knowledge of the API surface. The agent reasons in natural language about user goals and matches that reasoning against whatever it finds at the server. Every assumption baked into thirty years of API design fails to hold for this reader, because the reader is doing different work. This is the part of the agent infrastructure conversation that has been moving slowly, because the implications are uncomfortable. They mean rethinking the surface of the system that has been the most carefully designed surface in software engineering. [Agentic APIs on AGTP](https://agtp.io) is what that rethinking looks like when somebody does the work. To see why the new reader changes the design, look honestly at what the old reader was being served. REST gave the human developer a small, generic vocabulary of verbs (GET, POST, PUT, DELETE, PATCH) and a strong convention that the path encoded the resource and the verb encoded the operation. This worked because the developer brought a translation layer with her. She knew that "book a table" meant POST against `/reservations` , because creating a reservation resource is the developer-mode encoding of booking a table. The HTTP vocabulary mapped to the server's data model, and the developer translated her user-facing intent into the data-model vocabulary in the moment of writing the code. The translation was a feature for the developer, because she only had to learn one pattern (CRUD against resources) and could apply it everywhere. The translation worked because she had time to think about it. She read the docs. She matched her need against the endpoints. She wrote the call with care, and if she got it wrong, she debugged the response, fixed her code, and tried again. The asynchronous, slow-loop nature of human API consumption is what made the translation layer cost-free. OpenAPI extended this design. Frozen contracts in YAML files. SDK generation from those frozen contracts. Compile-time guarantees that the developer was calling endpoints that existed and passing parameters in shapes the server expected. Every piece of this works beautifully for the human developer. None of it survives contact with the agent reader. Strip an agent's interaction with an API down to what is actually happening, and four properties become non-negotiable. The agent has no prior knowledge of the API surface. It arrives at the server cold. The agent has to discover what the server can do in the same call where it tries to do something. Documentation that the human developer would consult before writing code is documentation the agent never sees. The discovery has to be on-protocol. The agent reasons about user goals in natural language. The mapping from that reasoning to an endpoint is a single inference step. Generic CRUD verbs force the agent to perform a translation the human developer performed in advance, and the empirical evidence is now overwhelming that this translation step is where agents get things wrong. The vocabulary the API exposes has to speak the language the agent is reasoning in, because the agent has no opportunity to translate. The agent may need capabilities the server failed to anticipate. A human developer who finds an endpoint missing writes a feature request and waits for the next release. An agent that finds an endpoint missing has the user's goal in front of it now. The API surface has to admit a runtime negotiation primitive that lets the agent propose what it needs and lets the server evaluate whether the proposal is something it can support. The agent will compose interactions with other agents the API author never met. Two agents from two different organizations will use the same API, in coordination with each other, with audit trails that have to compose across organizational boundaries. The API surface has to expose enough structure for cross-server reasoning, which means shared vocabulary, predictable path grammar, and identifiable semantic blocks on every endpoint. These four properties together describe an API surface that an agent can actually use. The OpenAPI surface satisfies none of them. The agent ecosystem has been working around the gap with prompt engineering, custom wrappers, and bilateral integration. AGTP-API based on [Agentic API](https://agenticapi.com), is the proposal that the gap should be closed at the protocol layer instead. AGTP-API takes the verb question seriously. There are two layers to the answer, and the distinction between them matters. The first layer is the protocol floor: eighteen methods that every compliant AGTP server MUST support. Seven cognitive verbs (QUERY, DISCOVER, DESCRIBE, INSPECT, SUMMARIZE, PLAN, PROPOSE). Six mechanics verbs (EXECUTE, DELEGATE, ESCALATE, CONFIRM, SUSPEND, NOTIFY). Five lifecycle verbs (ACTIVATE, DEACTIVATE, REINSTATE, REVOKE, DEPRECATE). This floor is the contract every agent can rely on, every server has to honor, and every gateway can route on. The floor is the part the protocol pins down. The second layer is the open catalog: 465 intent-aligned verbs covering the action vocabulary agents actually use across domains. BOOK. RESERVE. AUDIT. REFUND. ESCALATE. SCHEDULE. NOTIFY. DELEGATE. The catalog is curated as an open living document at a published URL, versioned under semver, indexed by category. A server's manifest declares which catalog version it supports. Agents reasoning about the server can look up any verb they encounter against the same shared catalog and get a consistent semantic. The catalog is deliberately wider than the floor. The floor exists for cross-server interoperability. The catalog exists for expressiveness inside any given domain. A booking-server uses BOOK and RESERVE. A trading-server uses BUY and SELL and TRANSFER. A medical-records server uses ADMIT and DISCHARGE and PRESCRIBE. Each verb in the catalog satisfies the same lexical rules and the same curatorial principles (imperative action-intent, single semantic, distinguishable from HTTP method names), and each one is registered with category metadata that downstream systems can use for filtering, discovery, and analysis. A note worth making explicit: there is no IANA registry path for adding verbs to the AGTP-API catalog, and this is deliberate. IANA's process is the right cadence for things that should change conservatively. Status codes, media types, response headers. These are infrastructure-level grammar that everyone in the ecosystem has to agree on, and the slow careful pace of IETF process is exactly what gives them their stability. AGTP-API requests IANA registries for its status codes, its media types, and its response headers, and respects the cadence those registrations imply. Verbs are different. The vocabulary an agent ecosystem needs grows at the cadence of agent deployments, which is a different scale of time from IETF process. A new industry that puts agents into operation discovers new verbs almost immediately. A medical domain wants PRESCRIBE and TRIAGE. A logistics domain wants DISPATCH and ROUTE and CONSOLIDATE. A creative domain wants SKETCH and ITERATE and FINALIZE. Locking the verb vocabulary at IETF cadence would freeze the ecosystem at the moment the registry closes, and the gap between what agents need and what the registry permits would grow. The open catalog solves this by moving curation out of the standards body. The catalog is published, versioned, machine-readable, and openly maintained. The curatorial discipline (imperative form, single intent, distinguishable from HTTP) is enforced by the maintainers in public. Anyone can propose a verb. Acceptance happens at the cadence the ecosystem actually moves. The protocol governs the contract for using a verb; the catalog governs which verbs exist. This is the architectural distinction the agent ecosystem has been missing. The protocol layer needs IETF discipline. The vocabulary layer needs open-document discipline. AGTP-API is one of the first protocols to acknowledge that those two things are different and to treat them differently. The 18-verb floor and the 465-verb catalog could be defended on philosophical grounds alone. The empirical evidence is stronger than that. A [controlled benchmark across 7,200 trials](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6460766) and four model families measured exact endpoint selection accuracy for agents using intent-aligned verbs versus the same agents using CRUD verbs against the same underlying capabilities. The gap at frontier scale was substantial: 10 to 29 percentage points of accuracy, depending on the model. Aggregated across the three frontier models in the study, the average lift was 18.5 percentage points with a z-statistic of 3.77 and a p-value below 0.001. Three independent model families, built on different architectures by different organizations, all moved in the same direction by similar magnitudes. The mechanism was isolated through three ablations. Stripping documentation while keeping intent-aligned verbs improved accuracy further (the verb was carrying the signal, the documentation was adding noise). Swapping descriptions between paradigms collapsed CRUD accuracy by 39-43 percentage points while leaving intent-aligned accuracy approximately unchanged (the verb survived bad documentation; CRUD failed to). Constraining the candidate set to include the right answer kept the gap intact (the issue is verb selection rather than endpoint discovery). A one-paragraph summary of what these results mean: when the reader is a frontier-scale language model, the method name is the strongest single signal in the entire endpoint description. The verb beats the path. The verb beats the parameters. The verb beats the documentation. The 18.5-point average lift is what you get from changing nothing about your server except the verb you put in front of it. This is the empirical case for AGTP-API's design. Intent-aligned verbs are how agents reason. CRUD verbs were how humans translated their reasoning into the server's data model. When the reader is the agent, the translation step has to disappear, because there is no second pass to fix it. The verb has to carry the intent on the first try. There is one more shift worth naming, because it is the one that gets understated in technical discussions. The APIs of the last thirty years were designed for application-to-application integration. Application A calls Application B. The developers at A and B might never meet, but their applications meet at a stable contract, written down, versioned, frozen. Both sides build to the contract. The interaction is bilateral by design. Agents are doing something different. Agent A discovers Agent B at runtime. Agent A and Agent B may share no organizational boundary, no prior introduction, and no bilateral agreement. Their interaction has to compose on the fly from primitives both sides can understand without having coordinated in advance. This is why AGTP-API looks the way it does. The 18-verb floor exists so two agents that have never met share a baseline vocabulary. The 465-verb catalog exists so the broader vocabulary they reach for is also shared. PROPOSE exists so the agent that needs a capability the server lacks can ask for it without bilateral negotiation. The semantic block on every endpoint exists so an agent can reason about whether an endpoint matches its intent without reading a human's prose description. Every choice in AGTP-API is in service of agent-to-agent collaboration rather than application-to-application integration. They look similar on the surface and they are fundamentally different problems. API design that targets application-to-application integration treats the API surface as a contract between the two parties who will use it. API design that targets agent-to-agent collaboration treats the API surface as common ground that any number of agents will reason against, most of whom have never seen this server before, none of whom can wait for documentation. The first is a private agreement. The second is public infrastructure. AGTP-API designs for the second. Every era of API design has had a reader in mind. SOAP designed for the enterprise integration tool. REST designed for the curl-friendly human. GraphQL designed for the frontend developer chasing payload efficiency. OpenAPI designed for the SDK generator. Each one optimized the surface for the reader the designer had in mind. The reader has changed. The agent is here, and the agent will write more API calls in the next five years than every human developer combined has written across the history of the field. The surface that has been carefully built for the human reader is the wrong surface for the new one. This is the discipline shift AGTP-API represents. A protocol floor that pins down the structural contract. An open catalog of intent-aligned verbs that an agent can actually reason against. A negotiation primitive that admits capabilities the API author never anticipated. A semantic block that lets cross-agent reasoning compose without bilateral introduction. Empirical evidence that the design choices produce measurable accuracy gains at frontier scale. The reader sets the design. The reader changed. The design changes with it.