Designing APIs for AI Agents: Idempotency, Machine-Readable Errors, and 202 + Webhooks

Designing APIs for AI Agents requires careful consideration of several key factors. First and foremost, every mutating request must be idempotent. This means that if the request is retried for any reason, such as a dropped connection or context window compaction, the same result should be produced. To achieve this, an idempotency key should be accepted on every non-GET operation and the result should be stored.

If the same key is used for a replay, the stored response should be returned, whether the original request succeeded or failed. Idempotency keys should be scoped per authenticated client and have a documented expiration period, typically 24 hours as a minimum.

Secondly, errors in the API should be presented as machine-readable data rather than plain text. This allows AI agents to better understand and respond to issues. The RFC 9457 Problem Details specification provides a standardized way to represent errors, including a type, a title, a status code, a detailed description, and any relevant field-level validation errors. Agents can use this information to determine whether a request is retryable, when to retry, and what specific arguments may have caused the error.

Long work operations that take an extended period of time should not block API requests. AI agents are impatient schedulers and will time out and retry calls that take too long. Instead, such operations should return immediately with a job handle, and progress can be tracked using a status endpoint. The 202 Accepted HTTP status code, along with a Retry-After header, should be used to indicate that the request is being processed asynchronously.

The job handle, status, and status URL should be included in the initial response, and a terminal state with the result can be retrieved using the result URL. The error format should be consistent with synchronous calls, and a standardized set of terminal states should be used to avoid ambiguity.

In addition to strict schemas, explicitness is crucial for AI agents. Request bodies should not allow additional properties beyond those defined in the schema, and enum or const values should be used for closed value sets. Optionality should be clearly indicated, and nullability should be expressed explicitly using the proper type syntax. Reusing named schemas in components/schemas helps to reduce duplication and ensures that all operations using the same concept share a consistent definition.

Pagination of collections should be straightforward and agent-friendly. A stable pagination envelope with opaque cursors should be returned, and the stop condition should be clearly defined to avoid unbounded arrays. This approach ensures that agents can easily track progress and know when to stop processing collections.

Finally, the OpenAPI document should describe the behavior of the API, not just the shape of the data. Operations should include summaries and detailed descriptions that outline the operational facts, such as side effects, time windows, rate limits, and ordering guarantees. Agents rely on these descriptions to make informed decisions about request handling and can avoid unexpected behavior that may arise if the API does not adhere to established HTTP semantics.

By focusing on these six key aspects, APIs can be designed to be more effectively consumed by AI agents, reducing the potential for errors and duplication that may occur when misusing APIs designed primarily for human consumption.