Compatibility

We may add response fields, endpoints and optional request parameters. We may also add values to open response sets. Ignore unfamiliar response fields and keep accepting responses when a new value appears.

Existing endpoints, fields and parameters will not be removed, renamed or retyped within /v1. Their documented meaning will not change. A breaking contract needs a new API major version; it does not redefine the existing /v1 contract.

Before customer launch, we made two exceptions to this policy. On 11 October 2026, horse search stopped returning fei and ueln, and the fei_contains and ueln_contains filters were removed. The exact fei and ueln filters remain available as inputs; responses identify horses only by their Hippomundo id. MCP users need version 0.1.2 or later. On 19 October 2026, horse search results replaced sire and dam, which carried parent IDs, with sire_name and dam_name; the exact sire_id and dam_id filters remain. Both pre-launch changes are recorded in the changelog and do not create a general exception to the v1 policy.

Response enumerations are open sets. The documented x-known-values list the currently known values, not a closed set. Keep the original string, provide a fallback for an unfamiliar value, and avoid exhaustive switches or runtime validators that reject new response values. A strictly typed client still needs an unknown-value path. Request enumerations are closed: send only values allowed by the operation's request schema.

Pass next_page_token back as page_token without reading or modifying it, using the same filters and API key. Omit page_size and sort on subsequent requests: the token preserves the original values, and repeating either parameter returns 400 invalid_page_token. Tokens can expire. Their contents and encoding are not a client-facing contract.

For long backfills of search, results or other lists, use sort=id where offered and follow each next_page_token in order. With name, date or place ordering, rows can be renamed, redated, replaced, deleted or merged between requests. Reconcile after completion to account for changes during the traversal; finishing the pages does not establish an immutable snapshot. Do not fetch pages of one list in parallel. Partition concurrent competition work across independent editions or classes using the hierarchy endpoints. If a token expires, start a new traversal rather than constructing a position yourself.

The /v1 path carries the API major version. OpenAPI info.version identifies the contract document revision: its minor number goes up when the contract adds a field, parameter, schema or operation or renames a schema, and its patch number goes up for wording changes. The optional Hippomundo-Version header pins the API version your integration was built against: its only accepted value is v1, which today changes nothing. If a later version of the API changes behaviour in a way that is not backwards compatible, requests that send v1 keep the v1 behaviour. Review the changelog when updating your integration or generated client.