Matches API endpoints

The matches endpoints cover the full fixture lifecycle: browsing the match calendar, viewing match detail with events, casting prediction votes, and — for referees and admins — creating, locking, updating, and finishing matches.

GET /matches

Returns the match calendar for a season. Authentication is optional — when a valid token is provided, the response includes the authenticated user’s vote for each match.

season_id

number

Filter by season. When omitted, matches from the currently active season are returned.

Request
Response

cURL

curl http://localhost:3000/matches?season_id=3

[
  {
    "id": 42,
    "date": "2025-03-15T18:00:00",
    "homeTeam": {
      "id": 7,
      "name": "Rayo Vallecas FC",
      "logoUrl": "https://res.cloudinary.com/.../logo.webp"
    },
    "awayTeam": {
      "id": 12,
      "name": "Atlético Sur",
      "logoUrl": "https://res.cloudinary.com/.../logo.webp"
    },
    "homeTeamPlaceholder": null,
    "awayTeamPlaceholder": null,
    "homeGoals": null,
    "awayGoals": null,
    "homePenaltyGoals": null,
    "awayPenaltyGoals": null,
    "field": { "id": 2, "name": "Pabellón Municipal", "location": "Calle Olímpica 5" },
    "status": "pendiente",
    "phase": "fase_de_grupos",
    "groupName": "Grupo A",
    "dayOfWeek": "Sábado",
    "observations": null,
    "userVote": null,
    "votingStats": { "local": 14, "draw": 3, "away": 7, "total": 24 }
  }
]

Response fields

number

Match identifier.

date

string

ISO 8601 datetime of the match.

homeTeam

object | null

Home team object, or null if not yet assigned.

Show properties

number

Team identifier.

name

string

Team name.

logoUrl

string

Cloudinary logo URL. Falls back to a generic logo when none is set.

awayTeam

object | null

Away team object with the same shape as homeTeam, or null.

homeTeamPlaceholder

string | null

Label shown when the home team is not yet determined (e.g. “Winner Group A”).

awayTeamPlaceholder

string | null

Label shown when the away team is not yet determined.

homeGoals

number | null

Home team goals. null when the match has not started.

awayGoals

number | null

Away team goals. null when the match has not started.

homePenaltyGoals

number | null

Home team goals scored in a penalty shootout.

awayPenaltyGoals

number | null

Away team goals scored in a penalty shootout.

field

object

Playing field.

Show properties

number

Field identifier.

name

string

Field name.

location

string

Physical address or location description.

status

string

One of pendiente, en_curso, or finalizado.

phase

string

Competition phase, e.g. fase_de_grupos or eliminatorias.

groupName

string | null

Name of the group this match belongs to.

dayOfWeek

string | null

Localised weekday name in Spanish (e.g. Sábado).

observations

string | null

Referee notes added at the end of the match.

userVote

string | null

The authenticated user’s vote (local, empate, or visitante), or null when unauthenticated or not yet voted.

votingStats

object

Aggregated prediction votes for this match.

Show properties

local

number

Number of home-win predictions.

draw

number

Number of draw predictions.

away

number

Number of away-win predictions.

total

number

Total votes cast.

GET /matches/last-activity

Returns the Unix timestamp of the last global match update. Use this for long-polling to detect score or event changes without fetching the full match list.

Request
Response

cURL

curl http://localhost:3000/matches/last-activity

{ "timestamp": 1741034412345 }

timestamp

number | null

Unix millisecond timestamp of the most recent activity, or null when no activity has been recorded.

GET /matches/:id

Returns full detail for a single match, including the events array. Authentication is optional.

number

required

Match identifier.

Request
Response

cURL

curl http://localhost:3000/matches/42

{
  "id": 42,
  "date": "2025-03-15T18:00:00",
  "homeTeam": { "id": 7, "name": "Rayo Vallecas FC", "logoUrl": "..." },
  "awayTeam": { "id": 12, "name": "Atlético Sur", "logoUrl": "..." },
  "homeTeamPlaceholder": null,
  "awayTeamPlaceholder": null,
  "homeGoals": 3,
  "awayGoals": 1,
  "homePenaltyGoals": null,
  "awayPenaltyGoals": null,
  "field": { "id": 2, "name": "Pabellón Municipal", "location": "Calle Olímpica 5" },
  "status": "finalizado",
  "phase": "fase_de_grupos",
  "groupName": "Grupo A",
  "observations": "Good match.",
  "userVote": "local",
  "votingStats": { "local": 14, "draw": 3, "away": 7, "total": 24 },
  "events": [
    {
      "id": 101,
      "type": "goal",
      "player": { "id": 5, "name": "Luis García" },
      "team": "home"
    },
    {
      "id": 102,
      "type": "yellow_card",
      "player": { "id": 18, "name": "Pedro Ruiz" },
      "team": "away"
    }
  ]
}

All fields from GET /matches are included. The following field is added:

events

object[]

Ordered list of match events.

Show properties

number

Event identifier.

type

string

Event type. One of goal, yellow_card, red_card, penalty_shootout_goal, or penalty_shootout_miss.

player

object

Show properties

number

Player identifier.

name

string

Player name.

team

string

home or away.

POST /matches/:id/vote

Submits or updates the authenticated user’s pre-match prediction. Voting is only allowed while the match status is pendiente and both teams are assigned. Requires authentication.

number

required

Match identifier.

vote

string

required

The prediction. Must be one of local (home win), empate (draw), or visitante (away win).

Request
Response

cURL

curl -X POST http://localhost:3000/matches/42/vote \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"vote": "local"}'

{
  "message": "Voto registrado correctamente",
  "votingStats": { "local": 15, "draw": 3, "away": 7, "total": 25 }
}

message

string

Confirmation message.

votingStats

object

Updated vote counts after the submission.

Show properties

local

number

Home-win votes.

draw

number

Draw votes.

away

number

Away-win votes.

total

number

Total votes.

POST /matches

Creates a new match. Requires admin role.

date

string

required

ISO 8601 datetime of the match.

seasonId

number

required

Season the match belongs to.

fieldId

number

required

Playing field identifier.

groupId

number

Group identifier for group-stage matches.

homeTeamId

number

Home team identifier. Omit if the team is not yet determined.

awayTeamId

number

Away team identifier. Omit if the team is not yet determined.

homePlaceholder

string

Label to display when the home team is not yet set (e.g. “Winner Group A”).

awayPlaceholder

string

Label to display when the away team is not yet set.

phase

string

default:"fase_de_grupos"

Competition phase.

Request
Response

cURL

curl -X POST http://localhost:3000/matches \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2025-05-10T18:00:00",
    "seasonId": 3,
    "fieldId": 2,
    "groupId": 1,
    "homeTeamId": 7,
    "awayTeamId": 12,
    "phase": "fase_de_grupos"
  }'

{ "message": "Partido creado correctamente", "id": 43 }

DELETE /matches/:id

Soft-deletes (moves to trash) a match. Requires admin role.

number

required

Match identifier.

cURL

curl -X DELETE http://localhost:3000/matches/42 \
  -H "Authorization: Bearer <token>"

Returns { "message": "Partido enviado a la papelera correctamente" }.

POST /matches/:id/restore

Restores a trashed match. Requires admin role.

number

required

Match identifier.

cURL

curl -X POST http://localhost:3000/matches/42/restore \
  -H "Authorization: Bearer <token>"

DELETE /matches/:id/permanent

Permanently deletes a match from the database. Requires admin role. The match must already be in the trash (is_active = false).

number

required

Match identifier.

cURL

curl -X DELETE http://localhost:3000/matches/42/permanent \
  -H "Authorization: Bearer <token>"

This action is irreversible. All associated events are deleted in cascade.

GET /matches/admin/trash

Returns all soft-deleted matches. Requires admin role.

Request
Response

cURL

curl http://localhost:3000/matches/admin/trash \
  -H "Authorization: Bearer <token>"

[
  {
    "id": 42,
    "date": "2025-03-15T18:00:00",
    "home_team_name": "Rayo Vallecas FC",
    "away_team_name": "Atlético Sur",
    "home_team_placeholder": null,
    "away_team_placeholder": null,
    "season_name": "Liga 2024-25"
  }
]

number

Match identifier.

date

string

Match datetime.

home_team_name

string | null

Home team name.

away_team_name

string | null

Away team name.

home_team_placeholder

string | null

Home team placeholder label.

away_team_placeholder

string | null

Away team placeholder label.

season_name

string

Name of the season.

GET /matches/admin/report

Returns all finished matches with their events for the specified season. Requires admin role.

season_id

number

Season to report on. When omitted, all finished matches across all seasons are returned.

Request
Response

cURL

curl "http://localhost:3000/matches/admin/report?season_id=3" \
  -H "Authorization: Bearer <token>"

[
  {
    "id": 42,
    "date": "2025-03-15T18:00:00",
    "home_goals": 3,
    "away_goals": 1,
    "home_penalty_goals": null,
    "away_penalty_goals": null,
    "home_team_name": "Rayo Vallecas FC",
    "away_team_name": "Atlético Sur",
    "home_team_placeholder": null,
    "away_team_placeholder": null,
    "observations": "Incident-free match.",
    "events": [
      { "id": 101, "match_id": 42, "type": "gol", "player_name": "Luis García", "team": "home" }
    ]
  }
]

PUT /matches/:id/teams

Updates the teams assigned to a match. Used to fill in knockout-stage slots once qualifiers are known. Requires admin role.

number

required

Match identifier.

homeTeamId

number

Home team identifier. Pass null to clear.

awayTeamId

number

Away team identifier. Pass null to clear.

homePlaceholder

string

Home team placeholder label.

awayPlaceholder

string

Away team placeholder label.

cURL

curl -X PUT http://localhost:3000/matches/42/teams \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"homeTeamId": 7, "awayTeamId": 12}'

POST /matches/:id/lock

Acquires an exclusive editing lock on a match. The lock is held for 2 minutes and must be renewed by repeated calls. Returns a conflict if another user holds an active lock. Requires referee or admin role.

number

required

Match identifier.

Request
Response — success
Response — conflict

cURL

curl -X POST http://localhost:3000/matches/42/lock \
  -H "Authorization: Bearer <token>"

{ "message": "Bloqueo obtenido/renovado", "success": true }

{
  "message": "El partido está siendo editado por árbitro2",
  "success": false,
  "owner": "árbitro2"
}

POST /matches/:id/unlock

Releases the editing lock on a match. A referee can only release a lock they own. Admins can force-release any lock. Requires referee or admin role.

number

required

Match identifier.

force

boolean

default:"false"

Set to true to force-release a lock owned by another user (admin only).

cURL

curl -X POST "http://localhost:3000/matches/42/unlock?force=true" \
  -H "Authorization: Bearer <token>"

PUT /matches/:id/status

Updates the match status. Requires referee or admin role and an active lock.

number

required

Match identifier.

status

string

required

New status. One of pendiente, en_curso, or finalizado.

cURL

curl -X PUT http://localhost:3000/matches/42/status \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"status": "en_curso"}'

PUT /matches/:id/observations

Sets or clears the referee observations for a match. Requires referee or admin role and an active lock.

number

required

Match identifier.

observations

string

Referee notes. Pass null or omit to clear.

cURL

curl -X PUT http://localhost:3000/matches/42/observations \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"observations": "Brief scuffle in the second half."}'

POST /matches/:id/events

Records a match event. Goals and penalty shootout goals automatically increment the corresponding goal counter on the match row. Goals and cards also update the player’s season statistics. Requires referee or admin role and an active lock.

number

required

Match identifier.

type

string

required

Event type. One of: gol, tarjeta_amarilla, tarjeta_roja, penalti_tanda_marcado, penalti_tanda_fallado.

playerId

number

required

Player who caused the event.

teamSide

string

required

home or away.

Request
Response

cURL

curl -X POST http://localhost:3000/matches/42/events \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"type": "gol", "playerId": 5, "teamSide": "home"}'

{ "message": "Evento registrado correctamente" }

DELETE /matches/:matchId/events/:eventId

Removes a match event and reverses its effect on goal counts and player statistics. Requires referee or admin role and an active lock.

matchId

number

required

Match identifier.

eventId

number

required

Event identifier.

cURL

curl -X DELETE http://localhost:3000/matches/42/events/101 \
  -H "Authorization: Bearer <token>"

PUT /matches/:id/finish

Finalises a match: sets status to finalizado, releases the lock, updates team standings, awards prediction points to users who voted correctly, and increments matches_played for all players who appeared in events. Requires referee or admin role and an active lock.

number

required

Match identifier.

observations

string

Optional final referee notes.

Request
Response

cURL

curl -X PUT http://localhost:3000/matches/42/finish \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"observations": "Clean game."}'

{ "message": "Partido finalizado, clasificación y porra actualizadas" }

Overview

Endpoints

GET /matches

Response fields

GET /matches/last-activity

GET /matches/:id

POST /matches/:id/vote

POST /matches

DELETE /matches/:id

POST /matches/:id/restore

DELETE /matches/:id/permanent

GET /matches/admin/trash

GET /matches/admin/report

PUT /matches/:id/teams

POST /matches/:id/lock

POST /matches/:id/unlock

PUT /matches/:id/status

PUT /matches/:id/observations

POST /matches/:id/events

DELETE /matches/:matchId/events/:eventId

PUT /matches/:id/finish

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /matches

​Response fields

​GET /matches/last-activity

​GET /matches/:id

​POST /matches/:id/vote

​POST /matches

​DELETE /matches/:id

​POST /matches/:id/restore

​DELETE /matches/:id/permanent

​GET /matches/admin/trash

​GET /matches/admin/report

​PUT /matches/:id/teams

​POST /matches/:id/lock

​POST /matches/:id/unlock

​PUT /matches/:id/status

​PUT /matches/:id/observations

​POST /matches/:id/events

​DELETE /matches/:matchId/events/:eventId

​PUT /matches/:id/finish

Build docs developers (and LLMs) love

GET /matches

Response fields

GET /matches/last-activity

GET /matches/:id

POST /matches/:id/vote

POST /matches

DELETE /matches/:id

POST /matches/:id/restore

DELETE /matches/:id/permanent

GET /matches/admin/trash

GET /matches/admin/report

PUT /matches/:id/teams

POST /matches/:id/lock

POST /matches/:id/unlock

PUT /matches/:id/status

PUT /matches/:id/observations

POST /matches/:id/events

DELETE /matches/:matchId/events/:eventId

PUT /matches/:id/finish