THE PM’S GUIDE TO AGENTIC APIs

Ship APIs That
AI Agents Can Find,
Read, and Use

Your APIs are either the front door to the autonomous economy—or an obstacle to it. Here’s how to ship agent-ready APIs as a PM.

Why This Matters Now

$183B
AI agents market
by 2033 (49.6% CAGR)
85%
of enterprises adopting
AI agents by end 2025
97M+
monthly MCP SDK
downloads
73%
increase in AI-related
API traffic (Postman)
THE PARADIGM SHIFT
→
APIs are no longer just for developers. AI agents are now primary consumers of your API surface. They don’t troubleshoot—they stop and report errors.
→
B2A is the new B2B. Business-to-Agent means your API docs are your “landing page”—agents read them to decide if your product solves their user’s problem.
→
Machine-readable or invisible. Agents can’t navigate scattered docs, video tutorials, or interactive playgrounds. They need structured, parseable contracts.

The 3 API Surfaces for Agents

REST API CLI TOOL MCP SERVER
DISCOVERY Pre-loaded docs / OpenAPI spec LLMs trained on shell patterns Built-in tools/list with JSON schema
TOKEN COST Moderate (docs in system prompt) 1,365 tokens per task (32x cheaper) 44,026 tokens per task (schema-heavy)
RELIABILITY High (mature ecosystem) 25/25 success rate in benchmarks 18/25 (72%) — TCP timeout failures
AUTH API keys, OAuth, JWT No standard — varies by tool OAuth built-in, multi-user support
COMPOSITION Chain via code / orchestration Native piping: cmd | jq | next Multi-step stateful workflows
MATURITY Production-ready Battle-tested Rapidly evolving
REST API
External integrations, well-documented services, high-volume production workloads, existing SDK ecosystems
CLI Tool
Developer tools, file operations, composable pipelines, cost-sensitive agent workflows
MCP Server
Dynamic tool discovery, multi-step stateful workflows, OAuth/multi-user auth, agentic analytics
The PM’s take: Ship all three. REST for production volume, CLI for developer pipelines, MCP for agent discovery. Your API needs a multi-surface strategy.

7 Principles of Agent-Friendly API Design

1
Machine-Readable Contracts
OpenAPI 3.0+ spec for every endpoint. Complete description fields—agents can’t ask for clarification.
2
Structured Error Responses
Machine-readable codes + remediation hints. Never return unstructured 500s. E.g.: RATE_LIMIT_EXCEEDED
3
Idempotency Keys
Support Idempotency-Key header for all writes. Agents retry on timeout—without this, you get double charges.
4
Cursor-Based Pagination
Return next_cursor + has_more fields. Offset pagination breaks under concurrent agent access.
5
Rate Limit Transparency
Return X-RateLimit-Remaining and Retry-After on every response. Agents need to self-throttle.
6
Consistent Naming
Never mix userId, user_id, and uid. Pick one convention. Agents perform better with predictable patterns.
7
Structured Output Envelopes
Separate data, metadata, and pagination: { "data": [...], "meta": { "cursor": "..." } }
AX
Agent Experience is the new DX. Everything that made APIs good for developers—specificity, consistent semantics, helpful errors—matters even more when the consumer can’t ask for help.

The PM’s Agent-Ready API Checklist

PRE-BUILD
  • Define consumers: humans, agents, or both?
  • Contract-first: write OpenAPI spec before code
  • Plan for 10-100x call volume vs human users
  • Set rate limits and pricing tiers for agent traffic
DESIGN
  • Every endpoint has a clear summary + description
  • All params documented with types, examples, defaults
  • Structured errors with machine-readable codes
  • Cursor pagination + idempotency keys
SECURITY
  • Restricted API keys with granular permissions
  • Scope-based access: agents get only what they need
  • Audit logging for all agent-initiated actions
  • Clear guardrails: what the agent CAN vs CANNOT do
SHIP
  • Test with real LLM agents, not just human QA
  • Publish MCP server alongside REST API
  • Add an “agent quickstart” to your docs
  • Monitor agent-specific usage patterns post-launch

6 Mistakes PMs Make with Agent APIs

1
Skipping Descriptions
Agents need natural language context to interpret endpoints. Empty description fields = broken agent workflows.
2
Designing Only for Humans
Screenshots, interactive playgrounds, and video tutorials are useless to agents. They need structured contracts.
3
No Idempotency Support
Agents retry on timeout. Without idempotency keys, retries cause double charges and duplicate creates.
4
Underestimating Traffic
A single agent loop can generate 100x the API calls a human would. Plan capacity for bursty, high-volume patterns.
5
No Rate Limit Headers
Without Retry-After and remaining-limit info, agents either hammer your API or fail silently.
6
Treating MCP as Optional
MCP is becoming the standard discovery mechanism. No MCP server = agents can’t find your API.

Who’s Doing This Well

GOLD STANDARD
Stripe
  • Agent Toolkit — Python + TypeScript for OpenAI, LangChain, CrewAI
  • Remote MCP server at mcp.stripe.com with OAuth
  • Restricted keys (rk_*) for granular agent permissions
  • Docs organized around real developer goals, not just endpoints
npx -y @stripe/mcp --api-key=YOUR_KEY
ECOSYSTEM PLAY
MCP Protocol
  • Donated to Linux Foundation’s Agentic AI Foundation
  • Co-founded by Anthropic, Block, OpenAI
  • Backed by Microsoft, Google, Amazon
  • 75+ connectors in Claude alone
tools/list → JSON schema → structured responses
COMMERCE
Shopify
  • MCP-powered agentic commerce across merchant ecosystem
  • Product catalog made machine-readable for AI shopping
  • Task-based API docs for agent consumption
  • Optimized for natural language queries over catalogs
Agent → Shopify MCP → browse + purchase

The Multi-Surface API Architecture

YOUR PRODUCT
Core Business Logic + Data
↓  Exposes three surfaces  ↓
REST API
Production volume,
existing integrations
CLI Tool
Dev pipelines,
cost-efficient agents
MCP Server
Agent discovery,
multi-step workflows
↓  Consumed by  ↓
Enterprise agents
Developer tools
AI assistants
Workflow engines
Partner systems
Internal copilots
Ship the Surface, Not Just the Endpoint
  • REST is your production backbone — existing SDKs, high-volume calls, billing integrations
  • CLI is your cost play — 32x cheaper tokens, 100% reliability, native composition
  • MCP is your discovery layer — agents find your tools via tools/list without pre-configuration
  • All three share the same auth, rate limits, and business logic — implementation differences are only at the transport layer
“
Your APIs are no longer just endpoints—they’re instructions for intelligent action. In the agentic era, a slow API is a lost sale.
— The shift from DX to AX
Rizvi Haider by Rizvi Haider