OpenAPI: an API description an agent can read.

What it is

The OpenAPI Specification is a JSON or YAML format for describing HTTP APIs. The latest release is 3.2.1¹; the released lines are 2.0, 3.0, 3.1, 3.2¹.

Tools turn it into clients, docs and tests. An agent uses it the same way: it reads the routes, the fields and the errors, then makes the call.

How many products publish one

104 of 151 products we drove publish an OpenAPI document. 146 of 151 have a public API.

How to add it

1. 1

   Publish it at a stable address.

   For example /openapi.json, without a sign-in. Agent payment discovery reads it from that address too.²

2. 2

   Describe the errors as well as the success.

   List each error answer with a field that says what to do next. An agent that knows the fix doesn't need a person.

3. 3

   Include sign-up and keys.

   If an agent can create an account or an API key over the API, put those routes in the document. They are the first an agent needs.

4. 4

   Link it from your docs and llms.txt.

   An agent looks there first.

Check it yourself

1. Fetch it from a server.

   It should parse as JSON or YAML and name its version.

   curl -s https://example.com/openapi.json | head -c 300

2. Find your key route in it.

   Search the document for the route that creates an API key. If it isn't there, an agent can't find it either.