Changelog

MCP server 0.2.0 follows the horse search change below: its results name the sire and dam with sire_name and dam_name, and the name filters need two characters. A successful call now returns charged_milli_credits, the milli-credits the API debited for that request, and idempotent_replayed: true for a repeat with the same Idempotency-Key that was not charged again. The server sends your key only to a Hippomundo API address, to a local development address, or to another https host you allow with HIPPOMUNDO_API_ALLOW_CUSTOM_HOST=1; before, it accepted any https host, and an empty HIPPOMUNDO_API_BASE_URL meant production, which now stops the server. HIPPOMUNDO_API_KEY_FILE reads the key from a file, and the Claude Code set-up uses it, so the key is not on a command line. The server reads at most 8 MiB of a response and returns result_too_large for a result too large for one MCP message, instead of losing the connection. The tool listing is 23% smaller, requests identify the server in their User-Agent header, and npm installs the dependency versions the server was tested with. Read Use the API from AI assistants, then change the version in your assistant's configuration to 0.2.0 and restart it.

A workspace owner can now give each API key a credit cap per UTC day or per UTC calendar month in the portal. A request that would take the key past its cap fails with the new problem code 402 api_key_credit_cap_reached, costs nothing, and carries Retry-After with the seconds until the next period starts. A key without a cap works as before. Clients should keep their fallback for unknown problem codes. The OpenAPI document's info.version is now 0.5.0.

The OpenAPI document's info.version is now 0.4.0, for the horse search changes below. Horse search results replace sire and dam, which carried each parent's ID and name, with sire_name and dam_name: the recorded name of the sire and of the dam, or null. The pedigrees still return parents with their IDs, and the exact sire_id and dam_id filters are unchanged. The horse search name, sire_name and dam_name filters and the rider search name filter now need at least two characters after surrounding spaces are removed. A shorter value returns 422 validation_failed with out_of_range and is not charged; before, it returned an empty page and was charged. MCP server 0.1.6 and earlier expect sire and dam and report the new horse search results as an unexpected response; MCP server 0.2.0 follows this change.

The OpenAPI document's info.version is now 0.3.0, for the response headers below. Every successful response, except those of GET /v1/usage and GET /v1/openapi.json, now carries Hippomundo-Charged-Milli-Credits: the milli-credits that request debited from your balance, or 0 when it debited nothing. A repeat within 24 hours with the same Idempotency-Key of a successful request that was charged or used a free allowance carries 0 and Idempotent-Replayed: true; its response is read again, so it may hold current data and a new next_page_token. A repeat of a request that cost nothing for another reason is priced like a new request and carries no Idempotent-Replayed. In the sandbox, Hippomundo-Data-Generation names the data that answered and changes with every weekly data refresh, so your application can key the sandbox data it keeps on it. HTTP caches still may not store these responses. Successful responses other than those of usage and the OpenAPI document keep Cache-Control: private, no-store. GET /v1/usage and GET /v1/openapi.json now refuse query parameters and unsupported X-Hippomundo-Freshness values with 422 validation_failed, like every other operation; before, they ignored them. Read the idempotency guide.

The OpenAPI document's info.version is now 0.2.0, for the 16 October pedigree changes. From now on 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 jumping record now states that placings include wins and how a placing is counted. The sandbox demo requests use the default page size, because a page costs the same whatever its size, and the pagination guide recommends sort=id for traversing search and result lists. Read the compatibility policy.

Every dam-line horse and every horse in its offspring lists, in all four pedigrees, now has sire_name, the recorded name of its sire, or null; it carries no sire ID. The sire's best offspring do not have it. In the sport, performance and black-type pedigrees, each best rider has nationality_iso_code, and the jumping record adds second_highest_wins and second_highest_placings for the next lower height with a win and with a placing. Existing fields are unchanged. The best-rider schema NullablePedigreeHorseRef is renamed NullablePedigreeRider; the JSON is unchanged except for the new field, but a generated client that names the schema needs updating. MCP server 0.1.6 passes the new fields through; its bundled result schemas describe them from a later release. Read the pedigree guide.

Your OpenAPI document (GET /v1/openapi.json) and your API reference in the portal now show each available operation's current price in an x-credits extension: milli_credits for programs, credits_text such as "370 credits" for people, the price of each follow-on page for list operations, and any free allowance while one applies. Operation descriptions no longer state whether a price is above zero; they say each successful request is charged at the operation's current price, so a future price change needs no change to the reference or to the MCP server. The published reference and the downloadable public OpenAPI document carry no prices. MCP server 0.1.6 passes each price through in the credits field of its operation catalog. Change the version in your assistant's configuration to 0.1.6 and restart it.

Class, horse, rider, studbook and offspring results now cost credits for each successful page under the current price list, including an empty page, in production and in the sandbox, where play credits pay for them. Errors are never charged, and a retry with the same Idempotency-Key is not charged twice. The studbook list, the edition and class lists, usage and the filtered OpenAPI document stay free. MCP server 0.1.5 ships the current reference text, so its tool descriptions say that the pedigrees and results cost credits; earlier versions say they cost none. Change the version in your assistant's configuration to 0.1.5 and restart it.

The breeding, sport, performance and black-type pedigrees now cost credits under the current price list, in production and in the sandbox, where play credits pay for them. Errors are never charged, and a retry with the same Idempotency-Key is not charged twice. Each operation's description in the reference states whether it costs credits. The pedigree tool descriptions shipped with MCP server 0.1.4 still say these operations cost no credits; the API reference is authoritative.

Breeding, sport, performance and black-type pedigrees share a genealogy tree and bounded dam families. Breeding replaces the basic route. Richer formats add sport and result information; performance also includes aggregate international prize money. Each horse has its public ID. MCP server 0.1.4 includes the four tools and their updated result schemas. This changes the earlier pedigree response shapes; update integrations and restart your assistant with 0.1.4. Read the pedigree guide for fields and limits.

Version 0.1.3 changes getEntitlementFilteredOpenAPI to a compact operation catalog. Full and per-operation schemas are available through explicit MCP resource reads, which recheck current access and cost no credits. The public HTTP OpenAPI endpoint and one tool per public operation are preserved. Malformed forwarded headers now fail as uncharged invalid_arguments before a request is sent. API errors and unknown outcomes after sending keep their existing retry rules. The pedigree tools also reject zero and negative horse IDs before sending a request. The installation examples pin 0.1.4; update your configuration deliberately and restart your assistant.

The reference now includes results from classes that are still being entered and dated editions that contain at least one class. This covers competition search, edition and class lists, and horse, rider, class, studbook and offspring results. Response shapes and pagination stay the same; no schema changes are needed in existing integrations. See horse results.

The sandbox now reloads its fictional data every Monday at about 03:30 Brussels time, with the dates moved forward, so its last 30 days always hold results. IDs and names stay the same. A page token from before a refresh answers page_token_expired; start the list again. See the Sandbox guide.

Horse search results no longer include fei and ueln; the Hippomundo horse id is the only horse identifier returned. The exact fei and ueln filters still work as before. The partial filters fei_contains and ueln_contains were removed; a request that sends one now returns 422 validation_failed. Version 0.1.2 of the MCP server follows this change; update from 0.1.1, which expects both fields in horse search results.

The sandbox now charges production prices against free play credits instead of making every request free, so charging, idempotent retries, idempotency_conflict and insufficient_credits behave exactly as in production. Each sandbox workspace starts every UTC day with 50,000 play credits; the previous day's remainder expires, and play credits cannot be bought.

The FEI and UELN filters of horse search now ignore spaces, hyphens and other ASCII punctuation as well as case, so an identifier copied from a response works as a filter; such values used to return validation_failed. Other characters, such as accented letters, are still rejected. The reference now also states how horse and rider name search matches, the 30-day maximum range of the studbook and offspring result feeds and their default end date, that a parent_role that does not match returns an empty page, whether each operation costs credits under the current price list, how often usage activity is updated, and what the Hippomundo-Version header is for. A new Sandbox guide lists a demo request for every operation, and version 0.1.1 of the MCP server adds instructions for assistants, result schemas and the remaining rate limit.

A new guide, Use the API from AI assistants, explains how to let an AI assistant such as Claude Code, Claude Desktop or Cursor call the API through the local MCP server published on npm as @hippomundo/enterprise-mcp. The server runs on your own machine with your own API key, offers one tool per API operation, and each tool call costs the same credits as the matching API request. /llms.txt now points AI tools to the guide.

Every documentation page is now also available as Markdown by adding .md to its URL. /llms.txt lists the documentation for AI tools, and /llms-full.txt contains every page in one file. A new security page explains how to report a vulnerability, and /.well-known/security.txt publishes the security contact.

The compatibility policy now states the additive changes clients must tolerate and the existing contract that remains stable within /v1. It includes open response values, opaque pagination tokens and id-profile backfills. Every operation links to the policy, and this changelog is also available in the Customer portal.

The public reference now includes generated operation and schema pages, downloadable OpenAPI, and searchable integration guides. This entry describes documentation availability and does not announce production launch.