How we designed an API specifically for AI agents (not humans)

When we started building APIClaw, the obvious approach was to follow what every other Amazon data API does — return as much data as possible and let the developer figure out what to do with it.

We almost shipped that. Then we started actually using it with AI agents and realized the problem.

Language models don't browse data. They reason about it. And every extra token they spend parsing nested JSON, normalizing inconsistent field names, or filtering out irrelevant fields is a token they're not spending on the actual task.

So we rebuilt it around three principles:

Flat JSON over nested structures. An agent can reason about monthlySalesFloor: 450 without traversing three levels of nesting. Simple rule, massive difference in practice.

Pre-processed signals over raw data. Instead of returning raw numbers and expecting the agent to calculate derived metrics, we include signals the agent can act on directly — opportunity scores, brand concentration, price band analysis. The agent reasons about signals, not spreadsheet math.

Consistent field naming across every endpoint. Sounds obvious. Almost nobody does it. When ratingCount is ratingCount on every single endpoint, agents can write predictable logic without field mapping tables.

The result was roughly 80% lower token consumption compared to feeding agents raw scraped HTML — and agents that actually produce useful output instead of hallucinating field names.

If you're building APIs that AI agents will consume, happy to share more of what we learned.