llms.txt and OpenAPI Setup Guide for AI Agents

If your product is not machine-readable, agents cannot use it reliably. This guide shows the minimum implementation to make AI tools discover your docs and call your API with fewer failures.

Required public files

/llms.txt for high-level discovery and canonical links.
/.well-known/openapi.json for schema-backed endpoint understanding.
/.well-known/air.json for identity, contact, and legal metadata.

Example llms.txt structure

Product: Your API
Start here: https://example.com
API: https://example.com/v1
OpenAPI: https://example.com/.well-known/openapi.json
Docs: https://example.com/docs
Contact: mailto:support@example.com

OpenAPI implementation checklist

Define schemas for requests and responses (avoid free-form payloads).
Include authentication method and error examples.
Use stable operation IDs for endpoint-level reliability.
Mirror the same spec at a canonical and a well-known URL.

Common failures to avoid

Spec file exists but returns HTML due redirect/proxy misconfiguration.
llms.txt links to stale or non-canonical docs.
Public docs require login, causing ingestion failures.
Inconsistent response shape between retries or datacenters.

Verification workflow

Run an external public-mode audit.
Fix all high-severity failures first.
Re-run and track score deltas weekly.

Run your public AI-readiness audit →