Structured Actions vs REST Endpoints: What AI Agents Need (2026)
Why AI agents think in actions and outcomes, not resources and HTTP methods. The shift from endpoint-based to action-based API design.
Traditional REST APIs: designed for human developers
REST has been the dominant API design pattern for over two decades. It organizes operations around resources (nouns) and HTTP methods (verbs). A user resource might expose GET /users (list), POST /users (create), GET /users/:id (read), PUT /users/:id (update), and DELETE /users/:id (delete).
This model works well for human developers who understand HTTP conventions, can read documentation to learn resource relationships, and can reason about state changes across multiple endpoints. Developers learn REST once and apply the pattern across every API they integrate.
Traditional REST API for a messaging service: GET /api/v1/conversations List conversations POST /api/v1/conversations Create conversation GET /api/v1/conversations/:id Get conversation PUT /api/v1/conversations/:id Update conversation DELETE /api/v1/conversations/:id Delete conversation GET /api/v1/conversations/:id/messages List messages POST /api/v1/conversations/:id/messages Send message GET /api/v1/conversations/:id/messages/:mid Get message POST /api/v1/conversations/:id/participants Add participant DELETE /api/v1/conversations/:id/participants/:pid Remove participant
A human developer looks at this and understands the resource hierarchy: conversations contain messages and participants. They can mentally map their task (“send a message to Alice”) to the right sequence of API calls. An AI agent faces a very different challenge.
How AI agents think: actions and outcomes
AI agents do not think in resources and HTTP methods. They think in actions and outcomes. When an agent needs to send a message, it is looking for an action called something like “sendMessage” that takes a recipient and a message body and returns a confirmation.
The agent does not naturally reason about whether it needs to first GET the conversation to check if it exists, then POST to create one if it does not, then POST a message to the conversation's messages sub-resource. This multi-step resource navigation is a human developer pattern, not an agent pattern.
Agents need a flat list of actions that map directly to outcomes. Each action should be self-contained, with all the context needed to execute correctly. The underlying implementation may involve multiple API calls, but the agent should see a single, clear action.
Side-by-side: REST endpoint vs structured action
Here is the same operation described as a REST endpoint and as a structured action. Notice how the structured action provides everything an agent needs in one place.
REST endpoint approach
POST /api/v1/conversations/:conversation_id/messages
Headers:
Authorization: Bearer <token>
Content-Type: application/json
Body:
{
"body": "string",
"content_type": "text/plain" | "text/html",
"metadata": { ... }
}
Notes:
- conversation_id must be a valid UUID
- Conversation must exist (create one first with POST /conversations)
- User must be a participant in the conversation
- Max body length: 10000 characters
- Returns 201 on success, 404 if conversation not foundStructured action approach
{
"name": "sendMessage",
"description": "Send a message in an existing conversation",
"inputs": {
"conversation_id": {
"type": "string",
"format": "uuid",
"required": true,
"description": "ID of the conversation to send the message in"
},
"body": {
"type": "string",
"required": true,
"maxLength": 10000,
"description": "Message content in plain text"
}
},
"outputs": {
"message_id": { "type": "string", "description": "ID of the sent message" },
"sent_at": { "type": "string", "format": "date-time" },
"status": { "type": "string", "enum": ["sent", "queued"] }
},
"reasoning": {
"when_to_use": "Use to send a message in a conversation that already exists. The user must be a participant.",
"when_not_to_use": "Do not use to create a new conversation. Use createConversation first if the conversation does not exist.",
"common_mistakes": [
"Sending without checking if the conversation exists first",
"Using HTML in the body — this action only supports plain text"
],
"expected_output": "Returns the message_id and sent_at timestamp. Status will be 'queued' if the recipient is offline."
}
}The structured action includes the typed inputs, typed outputs, reasoning docs, and constraints that an agent needs. The REST endpoint requires the agent to piece together information from headers, path parameters, body schema, and documentation notes spread across multiple pages.
Why REST breaks down for AI agents
REST was designed for human developers who can apply conventions, navigate documentation, and reason about resource relationships. Agents lack this context, and REST's conventions become ambiguities.
Ambiguous method mapping
What does POST /conversations/:id/archive do? Is it creating an “archive” resource, or archiving a conversation? Agents cannot reliably distinguish between resource creation and action execution in REST. The same method (POST) is used for both, and the semantics depend on convention and documentation.
Nested resource complexity
Deeply nested resources like /orgs/:orgId/teams/:teamId/projects/:projectId/issues/:issueId/comments require agents to know multiple IDs at different levels. Each level is a potential point of hallucination where the agent might use the wrong ID format or reference a non-existent parent resource.
Pagination and filtering
REST APIs implement pagination in dozens of ways: offset/limit, cursor-based, page/per_page, link headers. Filtering varies even more. Agents have to learn each API's specific pagination and filtering conventions, which is a common source of errors.
Authentication complexity
REST APIs use various authentication schemes: API keys in headers, OAuth2 flows, JWT tokens, basic auth, and more. The auth requirements are often documented separately from the endpoint specs, making it easy for agents to miss or misconfigure authentication.
Action-based API design
Action-based design structures an API as a flat list of named operations, each with five components:
Name
A clear, descriptive verb-noun pair that tells the agent exactly what the action does. Examples: sendEmail, createUser, getInvoice, cancelSubscription.
Description
A one-sentence explanation of the action's purpose, written for an agent that has no prior knowledge of your API.
Inputs
Typed parameters with descriptions, constraints, and defaults. Every input the agent needs to provide, with nothing ambiguous.
Outputs
A typed response schema the agent can use to plan subsequent steps. Predictable and consistent across success and error cases.
Reasoning
When to use, when not to use, common mistakes, and expected behavior. This decision-making context is what separates action-based design from a simple endpoint wrapper.
This design pattern eliminates the ambiguities that cause agents to hallucinate. Instead of navigating resource hierarchies and HTTP conventions, agents select from a clear menu of operations with complete specifications.
The broader shift in API design
The move from endpoints to actions is part of a larger transformation in how APIs are built and consumed. As AI agents become primary API consumers, the entire API ecosystem is adapting. This includes new documentation formats, new discovery mechanisms, and new execution patterns.
This shift is explored in depth in The Future of APIs: From Human Developers to AI Agents. The companies that adopt action-based design now will have a significant advantage as agents become the primary consumers of software APIs.
REST is not going away. It remains the right choice for many human-developer use cases. But for the agent-facing layer of your API, structured actions provide a dramatically better interface. Most APIs will end up with both: a REST API for human developers and an action-based interface for agents, served through the same underlying infrastructure.
How Elba transforms APIs into structured actions
Elba takes your existing API and transforms it into a set of structured actions that agents can discover and execute. You define actions with typed inputs, outputs, and reasoning docs. Elba generates the machine-readable formats (agent.json, MCP config, llms.txt) and indexes your API in the agent registry.
The result is that agents can find your API by capability, understand what it can do through structured metadata, and execute actions with confidence. No resource navigation, no HTTP method guessing, no parameter hallucination.
For a complete overview of how Elba compares to other documentation platforms for agent readiness, see Best API Documentation for AI Agents. And to learn how to make your existing API usable by agents, read How to Make Your API Usable by AI Agents.