The OpenAPI contract

The OpenAPI contract is a JSON file that describes every route of the API: its address, its parameters, its responses, its scope and its errors. A tool reads it on its own: a client generator, an API editor or an AI.

Where to read it

Both are read with a plain GET, need no key and cost no credit. The API lets you keep its document for five minutes (Cache-Control) and sends an ETag: read it again with If-None-Match and you get a 304 when nothing changed. To read what the API serves right now, use the API address.

Its version

The version of the contract is in info.version. Read it with a command that needs no key:

curl -s https://api.fitdistance.io/api/partner/v1/openapi.json | jq -r '.info.version'

It is 1.0.0 today. The document follows OpenAPI 3.1. It declares a single server, https://api.fitdistance.io/api/partner/v1, and a single security scheme: your key in the Authorization: Bearer header.

What you find in it

• The read routes, such as GET /students, with their parameters, their response fields and their errors.
• The operations, one address each: POST /operations/<name>. The contract describes their arguments and the envelope of their response, not the content of data, which depends on the operation.
• On every operation, x- fields: x-scope (the scope), x-kind (read, write or delete), x-kind-by-action (the kind of each value of action, for an operation that holds several), x-sensitive (the sensitive scopes to add), x-confirmable (a preview with dry_run is possible) and x-stability.

x-stability is experimental on operations: their data is the internal response as it is and may still change. The read routes are the stable surface: their schemas are frozen.

Generate a client

A generator reads the contract and writes the code of a client. Here are two examples, one command each.

TypeScript types, with openapi-typescript:

npx openapi-typescript https://fitdistance.io/documentation/api/openapi.json -o fitdistance-api.d.ts

A TypeScript client, with openapi-generator-cli (it needs Java):

npx @openapitools/openapi-generator-cli generate -i https://fitdistance.io/documentation/api/openapi.json -g typescript-fetch -o ./fitdistance-client-fetch

These are examples: Fit'Distance does not ship a generated client, and the source stays the contract. A generator can fail on part of the contract, so try another language then. Put your key in the header of your client, never in code you share. The data field of an operation is not described, so do not count on a generated type for it.

What the reference takes from it

The reference reads the routes, their parameters, their scopes, their schemas and their error codes from this document. The site adds the cost labels ("Free", "1 credit" and the "billed" column of the error tables) and the "Stable" badge of the read routes: they are not in the contract. The routes without a family, GET /openapi.json among them, are in General.

What next

GET /operations completes the contract: it is the authority on the kind (kind) and the scope (scope) of each operation, and it can be read without a key. For an AI, llms.txt and llms-full.txt give the same content as text, and the MCP server opens your data to it.