IDs, Assets & Availability

Canonical IDs

Discover IDs from the API and reuse them in follow-up paths. IDs are opaque; do not derive one from a name, abbreviation, upstream number, or documentation example. Records can carry id, canonical_id, and external_ids, a map from source key to source-owned identifier. Baseball uses canonical IDs for lookups; other sport projections commonly use id. Use the returned identifier for that sport.

Resource	Discovery and follow-up
League	`/v1/leagues` → row `id` → `{league}`.
Game/match	`/v1/{league}/games` → `data.items` → `/games/{id}` and related routes.
Team	`/v1/{league}/teams` → directory items → `/teams/{id}`.
Player	Roster, lineup, or box score → `/players/{id}`.
Venue	Fixture venue reference → `/venues/{id}`.

External-ID lookup uses the exact stored source key:

curl "https://api.sportquanta.com/v1/mlb/games/by-external-id/SOURCE/EXTERNAL_ID" \
  -H "Authorization: Bearer $SPORTQUANTA_API_TOKEN"

The generic game external-ID route supports baseball, NFL, and NHL. Soccer uses /v1/{league}/matches/by-external-id/{source}/{externalId}. These are not name searches. URL-encode path values. Soccer teams and players can recur across competitions and national-team contexts. Store identity separately from league membership and season stats. Proto returns mapped canonical fixtures; its detail ID is a canonical game/match ID, not an upstream Proto row ID.

Images and localized text

Entity projections can materialize logo_url, headshot_url, or official_logo_url when an asset exists. Use a UI fallback when absent. Use the returned URL rather than reconstructing storage paths. Mirrored assets and official/provider URLs can be separate fields. Names, abbreviations, injury text, and descriptions may include localized fields. Preserve raw/provider values alongside display text. Standings support lang for supported display labels; there is no API-wide parameter that translates every field.

Provenance

On supported single-resource reads, ?provenance=true (or 1) exposes the source selected for each field:

{
  "_meta": {
    "provenance": {
      "status": {
        "source": "SOURCE_ADAPTER_ID",
        "run_id": "INGESTION_RUN_ID",
        "ingested_at": "2026-10-13T00:00:00Z"
      }
    }
  }
}

This is a field-level map. Supported game/match, team, player, and venue reads attach it only when stored provenance exists. Lists and most composites accept the flag without exposing a provenance map per nested entity. Provenance reads can bypass the normal detail cache.

Freshness and completeness

Signal	Interpretation
`created_at`, `updated_at`	Canonical document write times when present.
`_meta.provenance.*.ingested_at`	Ingestion time of that particular field.
Odds `updated_at`, `snapshot_at`, history `changed_at`	Quote or response timing; these are not interchangeable.
Soccer `context.asOf`, `sampleSize`, `scopeApplied`, `staleness`	Scope and age of contributing matches.
`_meta.cache_ttl_seconds`	Response cache lifetime, independent of source age.
`availability`, `available`, `reason`, `found`	Endpoint-specific evidence about missing data.
Current odds/props `truncated`	Snapshot exceeded its read cap; omitted when false.

Typical response cache classes are 5 seconds for live state, 10 seconds for current fixture odds, 30 seconds for props, 60 seconds for pregame detail, and 5 minutes for schedules/season aggregates/history. Complete final detail can be cached for 24 hours. Handlers can bypass or shorten caching while enrichment is pending. Live detail can return 404 data_not_yet_available for a missing or stale record while the schedule still exists. Final status alone does not guarantee a complete box score, recap, lineup, or shot chart. Treat missing metrics as unavailable. Check lineup confirmation/projection markers, report dates, sample sizes, bookmaker counts, and truncation before presenting a result as complete.

Get Started

Core Concepts

Data & Integration

Agents

IDs, Assets & Availability

Canonical IDs

Images and localized text

Provenance

Freshness and completeness

​Canonical IDs

​Images and localized text

​Provenance

​Freshness and completeness

Canonical IDs

Images and localized text

Provenance

Freshness and completeness