API v2

Canonical football resources, signed cursor pagination, Problem Details, and authenticated account writes.

API v2 is the canonical StatsHub contract for new integrations. It groups data around domain resources, uses stable response envelopes, and documents every operation with closed OpenAPI schemas.

https://statshub.com/api/v2

The legacy /api contract remains available unchanged. V2 is intentionally not a drop-in URL replacement for old applications: migrate by resource and update response parsing against the endpoint reference.

Resource vocabulary

Legacy term	V2 resource
unique tournament	competition
event	fixture
category	region
tournament	season phase

Nested routes express ownership. Examples include /competitions/{competitionId}/seasons, /seasons/{seasonId}/standings, and /fixtures/{fixtureId}/incidents.

Response envelopes

A single resource is returned under data:

{
  "data": {
    "id": 17,
    "name": "Premier League"
  }
}

Cursor-paged collections add navigation state under page and resolvable URLs under links:

{
  "data": [],
  "page": {
    "limit": 25,
    "nextCursor": "eyJ2IjoxLCJrIjp...",
    "previousCursor": null,
    "hasNext": true,
    "hasPrevious": false
  },
  "links": {
    "self": "/api/v2/fixtures?limit=25",
    "next": "/api/v2/fixtures?after=eyJ2IjoxLCJrIjp...&limit=25",
    "previous": null
  }
}

Cursor pagination

Paged collections accept:

Parameter	Meaning
`limit`	Page size from 1 to 100.
`after`	Opaque cursor for the next page.
`before`	Opaque cursor for the previous page.

after and before are mutually exclusive. Cursors are signed and bound to the collection's filters and sort order; clients should store and replay them without decoding or editing them.

Ranked analytical read models expose conventional page and pageSize parameters when users need stable page numbers across arbitrary sort columns. They live under /rankings; their response schemas define the accompanying page metadata precisely.

Analytical resources

Prefix	Purpose
`/rankings`	Price outliers, prop trends, hit rates, referee performance, and substitute impact.
`/predictions`	Model-generated team statistic projections.
`/data-coverage`	Fixture-level ingestion coverage and aggregate coverage summaries.
`/lineup-projections`	Predicted or confirmed starters across upcoming fixtures.
`/matchday-fixtures`	The matchday board's fixture read model and competition facets.
`/value-bets`	Model-backed market selections whose offered prices exceed fair value.

Errors

V2 failures use RFC 9457 Problem Details with application/problem+json:

{
  "type": "https://statshub.com/problems/invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "limit must be between 1 and 100",
  "instance": "/api/v2/fixtures",
  "code": "INVALID_PAGINATION",
  "requestId": "2d8bd660f45b"
}

Treat type or code as the machine-readable error category and detail as diagnostic text. Do not branch on the prose in detail.

Authentication and writes

Public football data is readable without a session. /me and favorite resources require either a Supabase bearer token or the existing Supabase session cookie. Authenticated clients can create, read, update, and delete favorite teams and players with POST, GET, PATCH, and DELETE.

Send JSON writes with Content-Type: application/json. Unknown body fields are rejected, ownership is derived from the authenticated user, and a client cannot read or mutate another user's favorites.

OpenAPI

Use the focused document for SDK generation:

https://statshub.com/api/openapi-v2.json
https://docs.statshub.com/openapi-v2.json

The combined contract remains the right input for clients that call both legacy and v2 routes.