Building APIs for AI Agents: A Practical Playbook
How crmkit's agent-first API design reshapes conventions: text over JSON, short IDs, bulk operations, and self-documenting endpoints.
A developer building crmkit, a headless CRM designed exclusively for AI agents, shares lessons on API design for a new kind of caller: a language model with a token budget instead of a browser rendering JSON. The core shift is that agents read responses rather than parse them, which overturns many conventional API design assumptions.
Recommendations include defaulting to plain, grep-friendly text over JSON, using short prefixed identifiers instead of UUIDs, and proactively surfacing data an agent is likely to need next to avoid costly follow-up calls. Bulk operations matter for both writes and reads, since each agent decision costs a thinking step, not just a network round trip.
Other practices covered: error messages must include actionable hints and clearly signal whether retrying is worthwhile, since agents default to retrying on failure. Idempotent writes are essential because agents frequently retry or restart operations, and documentation should live inside the API itself as a machine-readable endpoint rather than an external docs site.
Why it matters: as agentic systems increasingly consume APIs directly, engineers need to rethink API ergonomics around token efficiency, composability, and failure recovery rather than pure human readability.