Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/danielsl4/TFG_DAM_2526/llms.txt

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

The /matches endpoint returns an ordered list of match objects for a season. Results are sorted by date ascending, then by match ID. Authentication is optional. When a valid JWT is provided, each match object includes the userVote field showing the authenticated user’s current vote for that match. Without a token, userVote is null. Responses are cached in Redis per season and per user combination. The cache is invalidated automatically whenever match data changes (events added or removed, status updates, finalisation).

​
Request

Method: GET
Path: /matches

​
Query parameters

​
season_id
number
ID of the season to retrieve matches for. When omitted, the endpoint returns matches belonging to the currently active season.

​
Headers

​
Authorization
string
Optional. Bearer <token> — include to receive the authenticated user’s vote in each match object.

​
Response

​
200 OK

An array of match objects. Returns an empty array if no matches exist for the requested season.
​
id
number
Unique match identifier.
​
date
string
Match date and time in ISO 8601 format (YYYY-MM-DDTHH:MM:SS).
​
homeTeam
object | null
Null when the home team slot is not yet assigned (e.g. a bracket placeholder).
​
awayTeam
object | null
Null when the away team slot is not yet assigned.
​
homeTeamPlaceholder
string | null
Descriptive label used when the home team is not yet determined (e.g. "Winner Group A").
​
awayTeamPlaceholder
string | null
Descriptive label used when the away team is not yet determined.
​
homeGoals
number | null
Goals scored by the home team. Null before the match starts.
​
awayGoals
number | null
Goals scored by the away team. Null before the match starts.
​
homePenaltyGoals
number | null
Home team penalty shootout goals. Only relevant when the match is decided by penalties.
​
awayPenaltyGoals
number | null
Away team penalty shootout goals.
​
field
object
Venue where the match is played.
​
status
string
Current match status. One of "pendiente" (upcoming), "en_curso" (in progress), or "finalizado" (finished).
​
phase
string
Competition phase, e.g. "fase_de_grupos" or "eliminatoria".
​
groupName
string | null
Name of the group this match belongs to, or null for knockout stages.
​
dayOfWeek
string | null
Localised day name in Spanish (e.g. "Lunes", "Sábado"), derived from the match date.
​
observations
string | null
Free-text notes set by the referee, such as weather conditions or incidents.
​
userVote
string | null
The authenticated user’s current vote ("local", "empate", or "visitante"). Null when no token is provided or the user has not voted.
​
votingStats
object
Aggregate vote counts for the match.

​
Examples

curl --request GET \
  --url https://api.futsalmanager.example/matches
200 response (excerpt)
[
  {
    "id": 17,
    "date": "2026-05-15T19:00:00",
    "homeTeam": { "id": 4, "name": "Atlético Norte", "logoUrl": "https://..." },
    "awayTeam": { "id": 7, "name": "Real Sur FC", "logoUrl": "https://..." },
    "homeTeamPlaceholder": null,
    "awayTeamPlaceholder": null,
    "homeGoals": null,
    "awayGoals": null,
    "homePenaltyGoals": null,
    "awayPenaltyGoals": null,
    "field": { "id": 2, "name": "Pabellón Municipal", "location": "Calle Mayor 1" },
    "status": "pendiente",
    "phase": "fase_de_grupos",
    "groupName": "Grupo A",
    "dayOfWeek": "Viernes",
    "observations": null,
    "userVote": "local",
    "votingStats": { "local": 12, "draw": 4, "away": 8, "total": 24 }
  }
]

Build docs developers (and LLMs) love

Get started for freeTalk to us