Learn the six layers of AI-readable API design with a full DexPaprika case study: llms.txt, OpenAPI specs, MCP servers, skill files, platform integrations, and CLI tools.

AI-readable APIs: the developer guide to agent-friendly design

An AI-readable API is one that AI agents can discover, understand, and call correctly without human help. It means machine-readable specs, content indexes for LLMs, standardized tool interfaces, and agent self-configuration files. With 79% of organizations deploying AI agents and Gartner projecting 40% of enterprise apps will embed agents by year-end 2026, an API that isn't agent-readable is invisible to an increasing share of developers.

Traditional API docs are built for a human in a browser: HTML pages, navigation menus, interactive playgrounds. An AI agent can't click menus or scroll. It consumes your API's description inside a finite context window, picks the right endpoint, constructs a valid call, and interprets the response, all without asking for clarification. Gaps that a human fills from experience become failures for an agent.

Making an API agent-readable isn't a rewrite. It's a stack of layers you add on top of what you already have. Each layer solves a different part of the agent's workflow: discovery, understanding, connection, and execution.

The six layers of an AI-readable API

There are six layers, and they build on each other. You don't need all six on day one, but the more you implement, the more AI agents can do with your API.

Layer 1: llms.txt (documentation discovery). A markdown file at your website root that indexes your most important content for LLMs. Instead of forcing an agent to parse raw HTML (wasting 90%+ of its context window on navigation and styling), llms.txt gives it a curated table of contents with links to clean markdown pages. Add llms-full.txt to serve the entire documentation as one file for RAG pipelines and large-context models.

Layer 2: OpenAPI/AsyncAPI specs (the machine-readable contract). Your OpenAPI spec is the source of truth for what your API does. Every endpoint, parameter, schema, and auth requirement in one structured file. Agents and frameworks use it to generate valid calls. Research from AutoMCP tested 5,066 endpoints and found that initial tool call success was 76.5%. Every failure traced to spec inconsistencies. After fixing them, success hit 99.9%.

Layer 3: MCP server (standardized tool interface). The Model Context Protocol gives agents a runtime connection to your API. Instead of the agent generating HTTP requests from documentation, it connects to your MCP server and discovers available tools with typed schemas. 97 million+ monthly SDK downloads tell you this isn't optional anymore.

Layer 4: Skill files (agent self-configuration). This is the most underrated layer and arguably the one that prevents the most agent failures. A markdown file that encodes domain knowledge: how to authenticate, common workflows, known pitfalls, endpoint quirks. An agent fetches it at task start and self-configures. Different from MCP (which is runtime execution), skills are reference material that prevents the agent from learning your API the hard way through trial and error.

Layer 5: Platform integrations (meet agents where they live). ChatGPT Actions via OpenAPI, Claude Code plugins, Cursor and VS Code MCP connections. Each platform has its own integration surface, and agents on those platforms expect your API to speak their language.

Layer 6: CLI tools (terminal-native agents). AI agents running in terminals (Claude Code, Aider, Cursor's terminal mode) can install and run CLI tools as native capabilities. A well-designed CLI with JSON output becomes another tool in the agent's toolkit.

The case study: how DexPaprika built the full stack

DexPaprika is worth examining in detail because they've implemented every layer of the AI-readability stack for their DEX data API covering 25 million+ tokens across 33 blockchains. This isn't a theoretical framework. It's a real implementation you can inspect, and it demonstrates something I think most API providers miss: the layers compound. Each one makes the others more effective.

Layer 1: Documentation discovery

DexPaprika publishes both llms.txt and llms-full.txt. The index file (~127 lines) covers all API endpoints, AI integration guides, tutorials, SDKs, and streaming documentation. The full version (~2,847 lines) embeds the complete content of every linked page inline, ready for RAG ingestion or large-context models. Both are auto-generated by Mintlify from the docs source, so they stay in sync automatically.

CoinPaprika publishes the same at docs.coinpaprika.com/llms.txt, indexing 30+ API endpoints, 7 SDK languages, and MCP server docs.

Layer 2: Machine-readable specs

DexPaprika publishes OpenAPI specs (for the REST API) and AsyncAPI specs (for the SSE streaming API) linked directly from their llms.txt. These specs drive everything downstream: MCP server generation, ChatGPT Actions, and SDK generation. When the spec is right, the agent's calls are right. When it's wrong, everything breaks. The AutoMCP research found spec quality is the single biggest determinant of agent success, and I'd argue most teams underinvest here relative to the payoff.

Layer 3: MCP servers

DexPaprika runs a hosted MCP server at mcp.dexpaprika.com with 14 typed tools across three transport protocols (Streamable HTTP, SSE, and JSON-RPC). No authentication. No setup. An agent connects and discovers tools like getNetworkPools, getTokenDetails, getPoolOHLCV, and search instantly.

For organizations wanting local control, there's a self-hosted option via npm: npx dexpaprika-mcp runs the full server locally. Two lines in your Claude Desktop or Cursor config and you're connected.

CoinPaprika runs the same at mcp.coinpaprika.com with 23 free tools covering centralized exchange data: tickers, OHLCV, exchange markets, coin details, and more.

Layer 4: Skill files

This is where DexPaprika goes beyond what most APIs offer. Two skill files let agents self-configure:

The REST API skill tells agents the base URL, available endpoints, pagination patterns, and common token addresses. It even documents a field naming quirk that would trip up any agent: "URL paths use network and token_address, but JSON responses use chain and id for the same values." That single line prevents hundreds of failed API calls.

The streaming skill documents the SSE endpoint, batch streaming for up to 2,000 tokens simultaneously, the HTTP/1.1 requirement (HTTP/2 causes silent failures), and the compressed response field format. An agent reads this once and knows exactly how to stream prices without trial and error.

Layer 5: Platform integrations

DexPaprika covers every major AI platform:

• ChatGPT Actions via the OpenAPI spec at mcp.dexpaprika.com/openapi. Create a custom GPT, import the spec, set auth to none. Done.
• Claude Code via a marketplace plugin. Two commands: /plugin marketplace add coinpaprika/claude-marketplace then /plugin install dexpaprika.
• Cursor IDE via the MCP SSE endpoint. One-click connect from the docs, or manually add mcp.dexpaprika.com/sse in settings.
• VS Code via the same MCP endpoint, working through GitHub Copilot Chat's MCP support.

Layer 6: CLI and SDKs

The dexpaprika-cli is a Rust binary with no dependencies and a single file install. It ships 16 subcommands covering every API operation. Need pipe-friendly output for agent workflows? Use --output json --raw. Need live prices? The stream subcommand connects to SSE. Need interactive exploration? The shell subcommand opens a REPL. The docs explicitly note that AI agents running in terminals can install and use the CLI as a tool.

Four SDKs (TypeScript, Python, Go, PHP) provide typed clients with built-in caching and retry logic. The Python SDK uses Pydantic models for type safety. The TypeScript SDK includes configurable cache TTLs.

The hub: agents.dexpaprika.com

agents.dexpaprika.com ties it all together as a dedicated landing page for AI integrations. It links to every skill file, MCP endpoint, SDK, and tutorial. It serves as both a human-readable overview and an entry point for agents discovering the platform. The pricing comparison tells the story:

This layered approach is what a complete AI-readability stack looks like in production.

Common mistakes that break AI agents

The most frequent failures I've seen in agent-API interactions trace to a few recurring patterns.

Vague tool descriptions. "Get data" doesn't help an agent choose between ten endpoints. "Returns a paginated list of liquidity pools on a specific blockchain network, sorted by 24h volume descending, with token pair details and TVL" does. Research shows vague descriptions increase LLM latency by 30-40% and cost by 2-3x because the model retries with different endpoints. Describe every tool like you're explaining it to a new engineer who can't ask follow-up questions.

Interactive authentication. Any OAuth flow requiring browser redirects, CAPTCHAs, or MFA blocks agents entirely. API keys, bearer tokens, and OAuth client credentials grants are the only agent-compatible auth patterns. In the MCPMark benchmark, 47% of MCP integration failures traced to authentication issues alone. DexPaprika sidesteps this entirely with no authentication required.

Inconsistent response shapes. If the same endpoint returns different JSON structures depending on input, agents can't build reliable parsing. Consistent error envelopes with is_retriable, retry_after_seconds, and specific problem descriptions let agents self-recover instead of crashing.

Missing rate limit headers. Without X-RateLimit-Remaining and X-RateLimit-Reset, agents hit walls and retry blindly. Self-throttling requires machine-readable signals. This is a solvable problem that too many APIs ignore.

No deprecation signaling. Agents trained on old tutorials generate calls to deprecated endpoints. Mark deprecated routes in your OpenAPI spec, add migration hints to error responses, and update your llms.txt.

Frequently asked questions

What to remember about AI-readable APIs