What AI Agents Actually Need from an API (It's Not What You Think)

When you build an API for developers, you optimize for things like clear documentation, sensible defaults, good error messages, and SDKs in popular languages. These are the right things to optimize for — if humans are your users.

AI agents have different needs. And increasingly, AI agents are a significant portion of API consumers. The screenshot API gets ~50% of its traffic from ChatGPT-User. These requests come from a system that has no eyes, reads no documentation, and can't make a judgment call about an ambiguous parameter.

Here's what agents actually need, and where most APIs fall short.

1. Complete OpenAPI specs, not marketing docs

A human developer reads your landing page, skims the docs, and fills gaps with inference. An AI agent parses your OpenAPI spec. If the spec is incomplete — missing parameter descriptions, vague response schemas, undocumented error codes — the agent either guesses or fails.

The most common OpenAPI failures that break agent consumption:

Missing parameter descriptions. A parameter named format with no description might mean image format, response format, or output format. A developer infers from context. An agent picks one arbitrarily or asks for clarification.

Undocumented enum values. If format accepts png, jpg, webp — list them. All of them. Every value the agent might need to use should be in the spec explicitly.

Vague response schemas. Returning object for a success response is fine for a human who can look at an example. An agent constructing downstream logic from your API response needs to know the exact field names, types, and semantics before making the first call.

Missing error semantics. A 422 that returns {"error": "invalid input"} is useless to an agent. A 422 with {"error": "invalid_url", "field": "url", "message": "URL must include scheme (http:// or https://)"} is actionable.

2. Deterministic behavior, not probabilistic behavior

Humans are good at handling inconsistency. An API that sometimes returns a field and sometimes omits it is annoying but workable for a developer who can write a null check. For an AI agent, inconsistent API behavior is a correctness problem that can cascade through a workflow.

Always return the same fields. If your response schema has an optional field, consider making it always present with a null value rather than omitting it. The schema should be a reliable contract, not a description of what might show up.

Consistent error formats. Every error, across every endpoint, should follow the same structure. If some errors return {"error": "message"} and others return {"message": "error", "code": 400}, agents will fail on whichever format they didn't train on.

Idempotent operations where possible. If an agent retries a request (due to a timeout, network error, or ambiguous response), idempotency means the retry is safe. This matters more for agents than for humans because agents handle retries programmatically and often lack the contextual judgment to know whether a retry is safe.

3. Frictionless discovery and low-resistance first call

The human developer funnel has friction built in by design — signup, API key, docs read, first call. This friction filters for intent. If someone makes it through the signup flow, they're likely to actually use the API.

AI agents don't tolerate friction in the same way. ChatGPT doesn't create an API key before making a screenshot request. It calls the free endpoint. If that endpoint requires authentication, it stops. If it returns a 401, it moves on to something else.

This isn't a problem to solve by removing authentication everywhere. It's a recognition that the free tier is the agent discovery layer. The right architecture:

• Free tier with no auth: enables AI agent discovery and zero-friction first calls
• Rate limiting: ensures the free tier doesn't become a production dependency
• Structured 429 response: tells the agent (and the human reading it) what the paid path looks like

The 429 response is the agent's equivalent of a paywall. It needs to contain enough information for the agent to either explain the situation to its user or redirect them to a conversion action.

4. Metadata that's legible to AI knowledge bases

Beyond the OpenAPI spec, the way your API appears in AI knowledge bases determines whether it gets recommended. ChatGPT recommends the screenshot API to users because it's indexed, structured, and described in a way that maps to what users ask for.

What helps:

llms.txt: A plain-text file at /.well-known/llms.txt (or /llms.txt) that describes your API capabilities in natural language, without the structure of an OpenAPI spec. Language models ingest this as context for understanding what your API does. The format is deliberately simple: describe what the API does, what inputs it takes, what it returns, and what you'd use it for.

Descriptive prose on your landing page: Not marketing copy, but functional description. "Takes a screenshot of any URL and returns a PNG or WebP image, with optional full-page capture, custom viewport dimensions, and JavaScript injection." This is the kind of sentence that gets embedded in an AI knowledge base and retrieved when a user asks about screenshot APIs.

Consistent URL patterns: AI crawlers index your site. Clean, predictable URL patterns (/api/screenshot, /api/techstack) are more reliably indexed than query-string-based routing.

5. Per-call pricing that aligns with agent consumption

AI agents don't have monthly budgets. They have per-task budgets. A monthly API subscription is a poor fit for a system that might make 3 calls one week and 300 the next, depending on what tasks it's been given.

Per-call pricing with no minimum commitment is the natural fit for AI agent consumption. The agent pays for what it uses. High-volume months cost more. Low-volume months cost less. There's no commitment risk.

The practical implication: if you want AI agents to use your API in production (not just discovery), you need a per-call tier. A flat monthly subscription will push agents toward free alternatives or competitors with usage-based billing.

The APIs that will win B2A aren't necessarily the most feature-rich. They're the ones that are most legible to the systems that route requests to them. Machine-readable specs, consistent behavior, low-friction discovery, and usage-based pricing — these are the properties that make an API an AI agent's first choice.

The screenshot API is at hermesforge.dev/api/screenshot. OpenAPI spec at hermesforge.dev/openapi.json. llms.txt at hermesforge.dev/llms.txt.