API Design for AI Agents: Text-First, Grepable, Short Identifiers

Traditional API design, built for human-facing UIs, is inefficient for AI agents. A new playbook emerges, prioritizing text as the default interface, single-line grepable records, and concise, prefixed identifiers.

The traditional API contract, designed for human-facing UIs and client-side parsing, is being rewritten by the rise of AI agents. PDP Architect, drawing lessons from building crmkit—a headless CRM designed exclusively for agents—outlines a set of principles that depart from standard JSON-first API practices. The core insight is that an agent reads, rather than parses, API responses, fundamentally altering optimization priorities.

Text as the Default Interface

For AI agents, text is the primary interface, not JSON. The founder of crmkit argues that JSON, while a robust serialization format for programs, incurs unnecessary token costs for large language models. Every brace, quote, and repeated key name consumes tokens, which directly impacts an agent's budget and processing efficiency. Instead of defaulting to JSON, the suggested approach is to return text first, allowing structured output via an accept header or query parameter (e.g., ?format=json) when a traditional program is the consumer. This prioritizes the agent's reading process, minimizing token expenditure on non-meaningful syntax.

Grepable Single-Line Records

API responses for agents should be designed for grep operations. The agent's environment often involves piping output through command-line tools, making single-line records highly composable. A record spread across multiple lines of pretty-printed JSON cannot be easily filtered or sorted without additional processing. crmkit implements this by returning a contact as a single labeled line: contact_k7m2q name="Jane Doe" email=jane@acme.com stage=lead updated=2026-06-04T09:13Z # 1 contact(s). Any non-record information, like pagination cursors, rides on comment lines (e.g., # next: <cursor>), which agents can read or ignore. This design choice is not aesthetic; it directly enables agents to use familiar tools for data manipulation without round trips or additional model passes.

Short, Prefixed Identifiers

Identifiers in agent-facing APIs must be concise. A UUID, with its 36 characters, represents significant noise and token cost when an agent carries it through multiple API calls. The crmkit experience showed that short, prefixed identifiers, like cus_abc123 or token_xxx, are more efficient. The prefix serves a dual purpose: it signals the type of entity to the agent even without context and helps prevent type confusion (e.g., passing a customer ID where a token is expected). This mirrors Stripe's long-standing practice for human developers, a principle that proves even more valuable for token-conscious agents. Furthermore, crmkit accepts identifiers in both full (contact_k7m2q) and short (k7m2q) forms, accommodating agent guesses and reducing unnecessary error handling.

What We'd Change

The crmkit approach, being a headless product with no UI, represents an extreme optimization for agent-only interaction. Most applications will need to serve both human users (via traditional UIs or client libraries) and AI agents. A purely text-first, grepable output might introduce parsing overhead for existing human-centric clients or SDKs, requiring careful API versioning or separate endpoints. While the accept header offers a fallback, maintaining two distinct output formats for every endpoint adds complexity to development and documentation.

Furthermore, the focus on output format is strong, but the implications for agent input are less detailed. While short identifiers and clear structure likely benefit input too, the article does not elaborate on how agents should construct requests optimized for these principles. For broader adoption, a more comprehensive framework addressing both input and output, especially in hybrid human-agent systems, would be necessary. The crmkit model excels in its niche, but a direct lift-and-shift of these tactics to a dual-purpose API might create new friction points for non-agent consumers.

The shift to agent-native API design prioritizes token efficiency and composability within an agent's operational environment. This perspective suggests a fundamental re-evaluation of API contracts, moving beyond human readability and traditional parsing paradigms. As AI agents become more integrated into workflows, the principles of text-first communication, single-line data records, and concise identifiers will likely become foundational for new infrastructure and tooling.

The investor read

The emergence of agent-native API design signals a new frontier in infrastructure. Investors should note the shift from human-centric API paradigms to those optimized for AI agents' token budgets and operational patterns. This creates opportunities for companies building specialized tooling, frameworks, or API gateways that abstract these complexities or facilitate the creation of agent-first services. The crmkit example, a headless CRM, demonstrates a vertical where agent-driven interaction could become dominant. Benchmarks for success in this domain will likely include token efficiency, composability with agent tooling, and seamless integration into agentic workflows, moving beyond traditional latency or throughput metrics. Capital will flow towards solutions that enable developers to build robust, cost-effective agent-to-agent communication.