Standard · Describe
OpenAPI and the API catalog
A machine-readable description of your API, and a list of your APIs at a known address.
What it is
An OpenAPI document lists an API’s endpoints, inputs and outputs. The API catalog is a single file at a well-known address that points to each of a site’s API descriptions.
An analogy
At a glance
- Owner
- OpenAPI Initiative (versions 3.1 and 3.2); RFC 9727 (IETF, June 2025)
- Maturity
- Stable OpenAPI is the common standard for describing HTTP APIs. RFC 9727 defines /.well-known/api-catalog as a list of a site’s APIs.
- Where it lives
- OpenAPI Initiative
- Framework domain
- Describe: Be understood
- What it serves
- Let agents and developers see what your API does
- Make your API easy to find
Who should care
The roles this standard touches most. See all the roles on the personas page.
- Engineering and product. Build the access, data, endpoints and actions that agents use, on open standards.
How to adopt it
- 1
Publish an OpenAPI description for each public API.
- 2
Write clear descriptions for every operation, since agents read the words.
- 3
List the descriptions in an API catalog at /.well-known/api-catalog.
The Institute’s view
If you have a public API, you almost certainly have, or should have, an OpenAPI file. Good descriptions matter more than they ever did, because an agent chooses endpoints by reading them.
Standards change fast. Last reviewed November 2026.