OpenAPI spec

The whole API as a machine-readable document, at /openapi.json. Generate a client in your language, import it into an API tool, or point a code generator at it.

It is generated from the same registry the documentation and the router share, so it cannot describe an endpoint that does not exist or miss one that does. When we add an endpoint, the spec has it the same minute.

What is in it

• Every endpoint, with its parameters, their types and which are required.
• Response schemas inferred from real captured responses, not written by hand, so a schema and its example cannot disagree.
• A real example response per endpoint, harvested from the live API.
• Every error the endpoint can return, with its code and when it fires.
• The rate limit headers, so a generated client can read them.

Plan restrictions are in the spec

This is the part most specs get wrong. A generated client is built from this file, so an endpoint most keys cannot call has to say so, or the first a developer hears about it is a 403 in production on a method their own library offered them.

Statistics endpoints carry [Analyst] in the summary, a note in the description, and an x-plans extension listing exactly which plans reach them.

Using it

curl -O https://apihorseracing.com/openapi.json

# generate a client
npx @openapitools/openapi-generator-cli generate \
  -i openapi.json -g python -o ./racing-client

OpenAPI 3.1. Import it into Insomnia, Bruno, Stoplight or anything else that reads a spec. If you would rather have a collection you can click through, the Postman collection is the same surface in that format.

One thing to know

The examples are real responses, which means they carry real dates. An example showing a race from last month is not stale documentation; it is what the endpoint actually returned when the sample was captured. The meta.data_as_of in each one tells you when.