OpenCALL — Command And Lifecycle Layer
A single-endpoint, operation-based API protocol.
Instead of dozens of routes, verbs, and status codes, every request is a
POST /call carrying a typed operation name and its arguments.
The server responds with a predictable envelope—every time.
The Problem
Endpoint Sprawl
REST APIs grow into forests of URLs. /users,
/users/:id/orders, /users/:id/orders/:oid/items—each
with its own combination of HTTP verbs, query strings, and path
parameters. Clients need a map just to find the door.
Inconsistent Errors
One endpoint returns {"error": "not found"}. Another
returns {"message": "Not Found", "code": 404}. A third
returns an HTML error page. There is no standard error envelope, so
every integration is a special case.
No Self-Description
REST APIs are opaque by default. Without a separately maintained OpenAPI spec (which is often out of date), clients have no machine-readable way to discover what operations exist, what arguments they accept, or what they return.
Agents Deserve Better
AI agents today are forced to navigate web pages built for humans, burning tokens on HTML parsing, scraping forms, and guessing at UI flows. Developers spend weeks building translation layers between human-focused interfaces and agent-focused actions. The data is right there—behind a wall of markup.
The Answer
OpenCALL collapses every API surface into a single endpoint:
POST /call. Each request carries an operation
name and an arguments object inside a minimal
JSON envelope. The server always responds with a consistent structure
containing either a result or an error.
POST /call HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
{
"op": "v1:catalog.list",
"args": {
"type": "book",
"limit": 10
}
}Operations are namespaced, versioned, and discoverable. The server can describe every operation it supports—including argument schemas and return types—through built-in introspection, no sidecar spec needed.
Yes, we know. But hear us out.
The world doesn’t need another protocol for the sake of it. But the world has changed. Agents aren’t a future concern—they’re calling your API right now, and they’re doing it by scraping HTML, parsing screenshots, and burning thousands of tokens just to click a button.
OpenCALL gives humans and agents the same interface. One endpoint, typed operations, self-describing capabilities. An agent can discover what’s available, call it directly, and get structured data back—no browser automation, no token-expensive page parsing, no translation layer between what the human sees and what the agent needs.
Don’t take our word for it. The demo server is live:
curl -X POST https://api.opencall-api.com/call \
-H "Content-Type: application/json" \
-H "Authorization: Bearer demo_token" \
-d '{"op":"v1:catalog.list","args":{"limit":5}}'Or explore the interactive playground:
Open the Demo AppCompare
See how OpenCALL stacks up against the protocols you already know.
| OpenCALL | REST | GraphQL | gRPC | JSON-RPC | SOAP | MCP | A2A | |
|---|---|---|---|---|---|---|---|---|
| Endpoint pattern | Single POST /call |
Many verb + path combos | Single POST /graphql |
Per-service & method | Single endpoint | Single endpoint | Single endpoint | Single endpoint |
| Self-describing | Built-in introspection | Requires OpenAPI sidecar | Built-in introspection | Reflection or .proto files | No | WSDL | Yes | Yes |
| Error model | Consistent envelope with code, message, and details | Ad-hoc; varies per API | Partial data + errors array | Status codes + metadata | Structured error object | Fault element | Structured | Structured |
| Auth model | Bearer token in header; scopes per operation | Varies (header, query, cookie) | Varies; often context-based | mTLS or token metadata | Out of band | WS-Security | OAuth / tokens | OAuth / tokens |
| Async support | First-class polling & callbacks | No standard pattern | Subscriptions (WebSocket) | Streaming (HTTP/2) | No | No | No | No |
| Human + Agent | Yes | Manual | Manual | No | No | No | Agent only | Agent only |
| Chunked results | Yes | No | No | Yes (streaming) | No | No | No | No |
| Caching | Operation-level cache hints | HTTP caching (GET only) | Difficult (POST-based) | No built-in HTTP caching | No | No | No | No |
Agents in the Real World
We built a working demo library with full agent instructions, gave it a real domain, and asked ChatGPT and Claude to reserve Fahrenheit 451. The results tell you exactly where the industry is right now—and where it’s going fast.
SDK agents work today
Agents built on frameworks like the Claude Code SDK can make HTTP requests, hold tokens, and call APIs directly. They read the OpenCALL instructions, authenticated, searched the catalog, and reserved a book—exactly as designed. The protocol works. The new generation of agentic tools is already here and growing rapidly.
Browser agents can’t POST—yet
Chat-based agents like ChatGPT and Claude.ai have browsing tools that are read-only. They understood the instructions perfectly but couldn’t execute them—no POST requests, no token handling, no API calls. This is a temporary limitation of browser-sandboxed agents, not a protocol problem. It’s already being solved by the SDK-based agents that developers are building right now.
Safety rails need nuance
ChatGPT refused to authenticate on behalf of a user—even to a demo library with a fake card number. “Acting on behalf of the user” triggered safety guardrails that made no distinction between a banking API and a toy library. The guardrails are well-intentioned but blunt. They need a way to know when the user has genuinely said “go ahead.”
Mandates: the missing trust layer
The answer is a mandate—a signed, verifiable payload that says “this user authorises this agent to act on their behalf, with these scopes, until this time.” Not a session cookie. Not a bearer token someone could have scraped. A cryptographic proof of intent that travels with the request. A2A protocols are heading this way, and OpenCALL’s mandate envelope is next on the roadmap.
The protocol works. The API works. SDK-based agents are using it today. The next frontier is the trust layer—giving browser-based agents a verifiable mandate so they can act with confidence, not just caution. Things are moving fast, and we’re building for what’s coming.
Read the Spec
The full OpenCALL protocol specification covers the envelope format, operation naming conventions, error taxonomy, authentication model, introspection, async patterns, and more.
Read the Specification →Read the Client Guide
The client guide walks through building an OpenCALL client from scratch: constructing requests, handling responses, authentication, error recovery, and best practices for production use.
Read the Client Guide →