AI Racing Tip Explanations API

This endpoint exists for a very specific job: fetching the saved two-sentence explanation that belongs to a race tip. The contract is intentionally narrow. You get the stored explanation and its version, and that version matches the saved race selection rather than being recomputed at request time. If your interface needs concise editorial copy under a pick, this is the feed you build around.

Because the explanation is stored ahead of customer requests, the endpoint is suited to deterministic presentation. That matters if you have a card layout, a race detail page, or an automated content pipeline where the same tip needs to be shown consistently across browser refreshes, app sessions, and internal tooling. The content is not a free-form chat response; it is the exact saved text attached to that race tip version.

When no publishable selection exists, the response reflects that state by returning a null explanation. That keeps your integration honest: you are not forced to display placeholder reasoning where no supported tip was produced. It also means the endpoint can be used safely in templates, because you can branch on the presence of the explanation rather than trying to infer availability from the race alone.

The explanation endpoint is best understood as the presentation layer for a saved tip, not as the source of race facts. If you need runner names, bet type, odds, or settlement details, the contract directs you to the full race-tip endpoint. The explanation service simply reuses the stored editorial reasoning that was already prepared for that selection, so it avoids fragmenting the version relationship between the tip and its narrative.

That separation is valuable if you are building a comparison table, a premium race page, or a headless CMS-style display that mixes structured data with editorial copy. Your application can fetch the race tip for the core betting fields and then request the explanation endpoint to populate the “why this pick” block. Both endpoints stay aligned to the same raceId and date context, which keeps the UI coherent without requiring you to reconstruct text from separate sources.

If you already use racecards, race details, results, odds or profile feeds elsewhere in RacingAPI.net, the explanation endpoint drops into that same workflow. It does not replace race context feeds; it complements them. The practical result is a cleaner product architecture: one call for market and selection data, one call for the saved explanation, and no need to ask a model to rewrite the reasoning after the fact.

The normal workflow begins with identifying the correct raceId from a racecard or a saved tips response for the selected date. The endpoint expects that feed-generated ID, not a name-matching guess, so your application should carry the identifier forward from the original source record. You can pass the optional date parameter in YYYY-MM-DD format when you want to anchor the lookup to a specific saved analysis date; otherwise, it defaults to today.

From there, your client sends a GET request to /v1/races/{raceId}/tip/explanation with region=uk if you want the combined UK and Ireland scope explicitly declared. The response then gives you the explanation state for that race tip. If you are building a page, you can render the explanation only when the field is present; if you are building a service layer, you can cache the returned text alongside the version so your downstream app and your content store remain in sync.

This is a useful pattern for mixed editorial and commercial products. A front end can load the single-race tip first, then hydrate the explanation on the same view, or your back office can pre-fetch both and publish them together. Because the explanation is saved before the request arrives, the content is suitable for repeat display, moderation workflows, and templates where exact wording matters more than ad hoc generation.

The endpoint’s main value is not just that it returns a reason text, but that it returns the same explanation version as the race tip itself. That means the explanation is locked to the tip revision you are showing, which is important when a race page is updated, a selection changes, or your product uses saved content for auditability. Your display remains internally consistent rather than mixing a new explanation with an older pick.

For platform teams, this reduces the chance of confusing the user with mismatched editorial and structured data. If the tip version changes, the explanation version changes with it. If there is no publishable selection, the explanation is null instead of a substitute created on the spot. That makes the data contract predictable for UI teams, compliance review and internal QA.

It also makes the endpoint practical for reuse in more than one interface. You might surface the explanation in a public-facing tip page, then use the same response in a back-office moderation view or a customer dashboard. In each case, the wording is the stored explanation associated with that exact version, so the user sees the same reasoning wherever that race tip is displayed.

Because the explanation is saved as exactly two sentences, it works best when you treat it as a concise editorial block rather than a long article. That suits card layouts, summary panels and compact mobile screens. You can pair it with the main selection, the race time, and the minimal context from the race-tip endpoint, then style it as a human-readable reason field without trying to expand it into something it was never meant to be.

The wording is prepared beforehand, so there is no new AI generation happening during the customer request. That helps if you want consistent copy tone and want to avoid visible latency tied to on-demand model generation. It also keeps your integration simple: the front end receives stored text and can display it immediately in the same way each time for that race and version.

If your product includes save/share, email digests or editorial archives, this endpoint gives you a stable explanation string that can be reused without re-authoring the reasoning. That is particularly useful when the same pick must appear in multiple surfaces, such as a racecard preview, a premium subscription area and an internal operations tool. The explanation remains attached to the tip version rather than drifting across displays.

The service is limited to combined UK and Ireland racing via region=uk, and it uses the raceId from the feed rather than trying to infer identity from the horse or race name. That is an important operational detail if you are matching records across your own systems. It keeps the lookup anchored to the same source identifiers you already use in RacingAPI.net race and tips workflows.

This endpoint is not a general-purpose chatbot, not a free-form explanation generator and not a substitute for the full tip payload. It only returns the saved explanation and version. If you need runner details, odds or settlement information, use the full race-tip endpoint; if you need broader race context, combine it with the racecards or race details feeds. Keeping those functions separate helps your integration stay accurate and easier to maintain.

Access to this Enterprise AI endpoint is controlled through the Enterprise plan. It is read-only, and it shares Enterprise usage rather than operating as a separate free service. Clients can connect with explicit OAuth consent or supported API-key headers through compatible MCP clients when applicable, but the core HTTP endpoint is still the main way to retrieve the saved explanation in a normal application flow.

A media publisher can use the endpoint to show a short, consistent explanation under each tip on a race preview page. A subscription product can pair the stored explanation with the selection and price fields from the race-tip endpoint so members see both the pick and the reasoning together. A trading or editorial operations tool can use it to confirm that the published explanation matches the selected version before distribution.

It is also useful for systems that separate decisioning from presentation. Your internal workflow can prepare the tip and its explanation in advance, then the customer-facing app can fetch the final text only when it is time to display it. That reduces duplicated content logic and makes the explanation a reusable asset rather than a one-off response generated at page load.

For teams already working with RacingAPI.net racecards, odds or results, this endpoint can complete the user journey on the same race page. You can show the race, display the saved selection, and add the explanation as a compact summary that explains the decision in the same data context. The result is a clearer premium experience without asking the API to invent new reasoning for every request.

The request takes a path raceId and an optional date parameter in YYYY-MM-DD format. That date represents the saved analysis context, and if you omit it the service defaults to today. In practice, that means your application should store the raceId and selected date together wherever you persist tips, so lookups remain direct and do not rely on fragile text matching or search logic.

Handling the null case cleanly is part of the integration design. If the response contains no explanation because there was no publishable selection, your UI can hide the explanation block or replace it with a neutral state defined in your own product. The point is that the API is explicit about availability, so your front end can make a deliberate decision instead of displaying guessed wording.

The contract returns 200, 403 or 404, so your client should already have a straightforward response strategy in place. In a commercial app, that usually means showing a permission state for 403, a not-found state for missing race context, and a normal explanation panel when the tip version exists. Because the endpoint is narrow, it is easy to wire into the same error handling you already use for the rest of the RacingAPI.net feeds.