API Documentation Standards

Write operation descriptions as complete sentences that explain what the endpoint does, why you would use it, and what the expected outcome is - agents parse descriptions to determine whether an endpoint matches their intent.

Add x-agent-hints custom extensions to your OpenAPI spec that describe common use cases, prerequisite calls, and recommended call sequences - agents use these hints to plan multi-step API interactions.

Specify exhaustive enum values and string patterns for all parameters - agents cannot infer valid values from context the way human developers can, so explicit constraints prevent trial-and-error API calls.

Include response examples for every status code, not just 200 - agents need to understand error responses to implement proper error handling and retry logic without human intervention.

Publish your OpenAPI spec at a well-known URL (/.well-known/openapi.json) and reference it in your robots.txt and HTML meta tags - this enables agent discovery without requiring prior knowledge of your API.

Describe side effects explicitly - if a POST endpoint creates a resource and also sends a notification, document both effects; agents need complete effect models to make informed decisions about whether to call an endpoint.

Document rate limits, quotas, and throttling behaviour in the spec itself, not just in a separate page - agents that hit rate limits without warning will retry aggressively, compounding the problem.

Specify idempotency guarantees per endpoint - agents operating autonomously may retry failed requests, and knowing whether a retry is safe (idempotent) or dangerous (non-idempotent) is critical for autonomous operation.

Include latency expectations and timeout recommendations - agents managing multi-step workflows need to set appropriate timeouts, and undocumented latency causes cascading failures in agent orchestration.

Document authentication scopes at the endpoint level, not just the API level - agents operating with delegated authority need to know exactly which permissions each endpoint requires to request minimal necessary access.

Provide complete, copy-pasteable request examples for every endpoint - include headers, authentication tokens (with placeholder values), query parameters, and request bodies as a single executable unit.

Show multi-step workflow examples that demonstrate common sequences of API calls - agents planning complex operations benefit from seeing the intended call order, data flow between steps, and error handling at each stage.

Include negative examples that show what happens when requests are malformed, unauthorised, or exceed limits - agents that understand failure modes can implement defensive patterns proactively.

Add SDK code examples in the languages most commonly used by agent frameworks (Python, TypeScript, Go) - agents that generate code to interact with your API produce more reliable integrations from language-specific examples.

Version your examples alongside your API - stale examples that reference deprecated endpoints or outdated parameter formats cause agent integration failures that are difficult to diagnose remotely.

Implement OAuth 2.0 with machine-to-machine (client credentials) flow as the primary agent authentication method - this eliminates the need for interactive login while maintaining proper access control.

Support scoped API keys that encode the delegation chain - an agent's API key should carry metadata about who delegated authority, what scope was granted, and when the delegation expires.

Implement token refresh without human intervention - agents operating autonomously need to renew credentials programmatically, and any authentication flow that requires human interaction is incompatible with agentic operation.

Provide a machine-readable capability discovery endpoint that returns available scopes, rate limits, and access levels for a given credential - agents need to discover their own permissions without trial and error.

Design authentication error responses that include actionable remediation steps - instead of just returning 401 Unauthorized, include the specific scope required, the token endpoint URL, and the grant type needed.