API ReferenceSports
Read a fixture and each available main-line market.
const url = 'https://data.predictefy.com/v1/sports/fixtures/example';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://data.predictefy.com/v1/sports/fixtures/example \ --header 'Authorization: Bearer <token>'DARK by default. Requires READS_ENABLE_SPORTS to be the literal true and a configured sports Redis client; otherwise the route is unmounted (404). Identity retains market: null and adds markets: MarketBlock[] in header order. Missing or null block projections are omitted. meta.rev is the fixture-wide change stamp; asOf is the oldest served block clock. Serves owned Redis snapshots only, with no Core or venue request calls. Unknown query keys are ignored except the documented facets window rejection. Degraded responses preserve the last usable snapshot with honest stale flags. Catalog and stale cells are never best; unknown fees keep net null; edge is absent when fair is absent. final means keyed markets closed; fair, edge and hold are Predictefy calculations.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Canonical mirrored fixture ID. Invalid characters or more than 128 characters return VALIDATION_ERROR.
Header Parameters
Section titled “Header Parameters”Send the exact returned ETag when repeating the same query. An exact match returns 304 only while healthy; degraded responses remain 200.
Responses
Section titled “Responses”Successful snapshot response.
object
Fixture identity plus every available advertised block at its main line. Missing or null projections are omitted; no empty block is invented. markets follows the header block order.
object
object
object
object
object
object
object
Predictefy computes average, normalized fair probability, edge, and hold. Edge is null whenever fair is null. Best is an eligible live, non-stale quote or null; unknown fees can select best on gross with edgeOnGross=true and net=null. Best does not promise a verified all-in execution cost.
object
One venue quote. Catalog and stale cells cannot be best. feeUnknown=true always has net=null. grossReason explains a null gross price; asOf is the source quote clock, not a freshness confirmation.
object
One venue quote. Catalog and stale cells cannot be best. feeUnknown=true always has net=null. grossReason explains a null gross price; asOf is the source quote clock, not a freshness confirmation.
object
Counts of unplaced markets by reason. Reasons absent from the source are omitted.
object
Single-fixture and compare metadata. rev is the fixture-wide change stamp. Repeated concurrent revision changes return retryable SPORTS_SCREEN_UNAVAILABLE rather than mismatched headers and prices.
object
Missing or unrepresentable heartbeat clocks produce null heartbeatAt/lagMs and zero engine counts.
object
object
Quote age thresholds in milliseconds. These are applied before projection while engine or Redis liveness is degraded.
object
Counts of unplaced markets by reason. Reasons absent from the source are omitted.
object
Example
{ "success": true, "data": { "fixtureId": "f2", "sport": "soccer", "competition": { "id": "c", "name": "Cup", "timeZone": "UTC" }, "home": { "id": "b", "name": "Beta" }, "away": { "id": "a", "name": "Alpha" }, "teams": [ { "id": "a", "name": "Alpha" }, { "id": "b", "name": "Beta" } ], "kickoffAt": "2026-09-19T12:00:00.000Z", "kickoffPrecision": "exact", "eventDate": "2026-09-19", "status": "scheduled", "venues": [ "a", "b" ], "market": null, "markets": [ { "marketType": "total", "period": "full", "line": 2.5, "lineTeam": null, "lines": [ { "line": 2.5, "venues": [ "a" ] }, { "line": 3.5, "venues": [ "b" ] } ], "selections": [ { "selection": { "key": "over", "kind": "over", "side": null, "team": null }, "cells": [ { "venue": "a", "marketId": "m-a", "outcomeId": "a-over", "selection": "over", "gross": { "probability": 0.5, "american": 100, "decimal": 2 }, "grossReason": null, "net": { "probability": 0.5, "american": 100, "decimal": 2 }, "feeBps": 0, "feeUnknown": false, "sizeAtPrice": 100, "asOf": "2026-09-19T12:00:00.000Z", "stale": false, "source": "live" } ], "best": { "venue": "a", "marketId": "m-a", "outcomeId": "a-over", "selection": "over", "gross": { "probability": 0.5, "american": 100, "decimal": 2 }, "grossReason": null, "net": { "probability": 0.5, "american": 100, "decimal": 2 }, "feeBps": 0, "feeUnknown": false, "sizeAtPrice": 100, "asOf": "2026-09-19T12:00:00.000Z", "stale": false, "source": "live" }, "avg": { "probability": 0.5, "american": 100, "decimal": 2 }, "fair": { "probability": 0.5, "american": 100, "decimal": 2 }, "edge": 0, "edgeOnGross": false }, { "selection": { "key": "under", "kind": "under", "side": null, "team": null }, "cells": [ { "venue": "a", "marketId": "m-a", "outcomeId": "a-under", "selection": "under", "gross": { "probability": 0.5, "american": 100, "decimal": 2 }, "grossReason": null, "net": { "probability": 0.5, "american": 100, "decimal": 2 }, "feeBps": 0, "feeUnknown": false, "sizeAtPrice": 100, "asOf": "2026-09-19T12:00:00.000Z", "stale": false, "source": "live" } ], "best": { "venue": "a", "marketId": "m-a", "outcomeId": "a-under", "selection": "under", "gross": { "probability": 0.5, "american": 100, "decimal": 2 }, "grossReason": null, "net": { "probability": 0.5, "american": 100, "decimal": 2 }, "feeBps": 0, "feeUnknown": false, "sizeAtPrice": 100, "asOf": "2026-09-19T12:00:00.000Z", "stale": false, "source": "live" }, "avg": { "probability": 0.5, "american": 100, "decimal": 2 }, "fair": { "probability": 0.5, "american": 100, "decimal": 2 }, "edge": 0, "edgeOnGross": false } ], "hold": { "average": 0, "byVenue": { "a": 0 } } } ], "unplaced": { "line_missing": 2 } }, "meta": { "asOf": "2026-09-19T12:00:00.000Z", "degraded": false, "degradedReason": null, "engine": { "heartbeatAt": "2026-09-19T12:00:00.000Z", "lagMs": 17, "fixtures": 1, "blocks": 1 }, "index": { "refreshedAt": "2026-09-19T12:00:00.000Z", "fixtures": 1 }, "freshness": { "live": 30000, "day": 120000, "week": 1200000 }, "unplaced": { "line_missing": 2 }, "rev": 1789819200000 }}Headers
Section titled “Headers”Example
W/"pss1:f2:1789819200000"Weak snapshot validator. Screen/listing use the query fingerprint plus served fixture/revision pairs; fingerprintQuery excludes limit and cursor. Single-fixture and compare use W/"pss1:
Private response that requires revalidation before reuse.
No body. The exact weak ETag matches and the response is not degraded. Repeat the same query: fingerprintQuery excludes limit/cursor, and single-fixture/compare tags contain only fixture ID and revision. Degraded responses always return 200.
Headers
Section titled “Headers”Example
W/"pss1:f2:1789819200000"Weak snapshot validator. Screen/listing use the query fingerprint plus served fixture/revision pairs; fingerprintQuery excludes limit and cursor. Single-fixture and compare use W/"pss1:
Private response that requires revalidation before reuse.
Invalid query or fixture ID. Facets rejects from/to because its snapshot owns the window.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}Missing, invalid or revoked API key.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}The account's credit balance cannot cover this sports read's weight. Not retryable.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}The API key lacks the read scope this route requires. Not retryable.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}The fixture is absent from the mirror, or the family is unmounted.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}Request rate limit exceeded.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}Unexpected internal error; requestId identifies the failure.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}Retryable: the mirror has never loaded and cannot load, a single-fixture snapshot keeps changing across two read attempts, or authentication or metering storage is unavailable.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}