Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Danielsl4/TFG_DAM_2526_Consulta2/llms.txt

Use this file to discover all available pages before exploring further.

Fetch the complete list of matches for a season, ordered by date. Without a season_id query parameter the API returns matches for the currently active season. Responses are served from Redis when available; the cache is segmented by season and by authenticated user so vote data remains accurate per caller.

​
Endpoint

GET /matches

​
Authentication

Optional. Supply a Bearer token in the Authorization header to receive the authenticated user’s vote (userVote) on each match. Unauthenticated requests return userVote: null.

​
Query parameters

​
season_id
integer
Filter matches by season ID. When omitted, the API returns matches belonging to the current active season.

​
Response

Returns an array of match objects. Each object contains:
​
id
integer
required
Unique match identifier.
​
date
string
required
Match date and time in ISO 8601 format (YYYY-MM-DDTHH:MM:SS).
​
homeTeam
object | null
Home team data. null when the team slot is still unassigned (e.g. knockout bracket placeholders).
​
awayTeam
object | null
Away team data. null when unassigned.
​
homeTeamPlaceholder
string | null
Descriptive label for an unresolved home-team slot (e.g. "Winner Group A").
​
awayTeamPlaceholder
string | null
Descriptive label for an unresolved away-team slot.
​
homeGoals
integer | null
Goals scored by the home team. null before the match begins.
​
awayGoals
integer | null
Goals scored by the away team. null before the match begins.
​
homePenaltyGoals
integer | null
Penalty shootout goals for the home team (knockout rounds only).
​
awayPenaltyGoals
integer | null
Penalty shootout goals for the away team (knockout rounds only).
​
field
object
Venue information.
​
status
string
required
Match status. One of: pendiente, en_curso, finalizado.
​
phase
string
required
Competition phase. One of: fase_de_grupos, octavos, cuartos, semis, final.
​
groupName
string | null
Name of the group this match belongs to. null for knockout-phase matches without a group.
​
dayOfWeek
string | null
Localised day name in Spanish (e.g. "Lunes", "Sábado").
​
observations
string | null
Free-text notes added by the referee.
​
userVote
string | null
The authenticated user’s current vote: local, empate, or visitante. null when the user has not voted or the request is unauthenticated.
​
votingStats
object
Aggregated vote counts for this match.

​
Caching

Responses are cached in Redis and keyed by both season and user identity:
ScenarioCache key
No auth, current seasonmatches:current
No auth, specific seasonmatches:season:{season_id}
Authenticated, current seasonmatches:current:user:{user_id}
Authenticated, specific seasonmatches:season:{season_id}:user:{user_id}
Cache entries are invalidated automatically when a match is created, updated, or finalized.

​
Examples

curl --request GET \
  --url 'https://api.example.com/matches'

[
  {
    "id": 42,
    "date": "2026-05-20T19:00:00",
    "homeTeam": {
      "id": 7,
      "name": "FC Rápidos",
      "logoUrl": "https://res.cloudinary.com/example/image/upload/logo.webp"
    },
    "awayTeam": {
      "id": 11,
      "name": "Atlético Sur",
      "logoUrl": "https://res.cloudinary.com/example/image/upload/logo2.webp"
    },
    "homeTeamPlaceholder": null,
    "awayTeamPlaceholder": null,
    "homeGoals": null,
    "awayGoals": null,
    "homePenaltyGoals": null,
    "awayPenaltyGoals": null,
    "field": {
      "id": 2,
      "name": "Pabellón Central",
      "location": "Calle Mayor 10, Valencia"
    },
    "status": "pendiente",
    "phase": "fase_de_grupos",
    "groupName": "Grupo A",
    "dayOfWeek": "Miércoles",
    "observations": null,
    "userVote": "local",
    "votingStats": {
      "local": 14,
      "draw": 5,
      "away": 3,
      "total": 22
    }
  }
]

Build docs developers (and LLMs) love

Get started for freeTalk to us