Teams and players API endpoints

The teams and players endpoints provide public access to team and player profiles and support admin operations for creating, editing, enrolling, and soft-deleting teams and players across seasons.

Teams

GET /teams

Returns a paginated, searchable list of teams. Optionally scoped to a season.

season_id

number

Return only teams that have statistics or squad registrations for this season.

exclude_season_id

number

Exclude teams already registered in this season. Useful when adding teams to a new season.

string

default:""

Case-insensitive, accent-insensitive name filter.

page

number

default:"1"

Page number.

limit

number

default:"10"

Results per page.

Request
Response

cURL

curl "http://localhost:3000/teams?season_id=3&page=1&limit=10"

{
  "teams": [
    {
      "id": 7,
      "name": "Rayo Vallecas FC",
      "logo_url": "https://res.cloudinary.com/.../logo.webp",
      "kit_color": "#FF0000",
      "delegate": "María López",
      "coach": "Carlos Pérez",
      "phone": "+34 600 000 001"
    }
  ],
  "pagination": {
    "total": 8,
    "page": 1,
    "limit": 10,
    "totalPages": 1
  }
}

teams

object[]

Show team properties

number

Team identifier.

name

string

Team name.

logo_url

string | null

Cloudinary logo URL.

kit_color

string | null

Primary kit colour (hex or name).

delegate

string | null

Club delegate contact name.

coach

string | null

Head coach name.

phone

string | null

Contact phone number.

pagination

object

Show pagination properties

total

number

Total matching teams.

page

number

Current page.

limit

number

Results per page.

totalPages

number

Total pages.

GET /teams/:id

Returns full detail for a team, including the squad, season statistics, and match schedule. Authentication is optional — when a valid token is provided, isFollowing reflects whether the user follows this team.

number

required

Team identifier.

season_id

number

Season to use for squad and statistics. Defaults to the active season when omitted.

Request
Response

cURL

curl "http://localhost:3000/teams/7?season_id=3"

{
  "id": 7,
  "name": "Rayo Vallecas FC",
  "logo_url": "https://res.cloudinary.com/.../logo.webp",
  "kit_color": "#FF0000",
  "delegate": "María López",
  "coach": "Carlos Pérez",
  "phone": "+34 600 000 001",
  "is_active": true,
  "isFollowing": false,
  "players": [
    {
      "id": 5,
      "name": "Luis García",
      "photo_url": "https://res.cloudinary.com/.../photo.webp",
      "jersey_number": "10",
      "goals": 8
    }
  ],
  "stats": {
    "played": 6,
    "won": 4,
    "drawn": 1,
    "lost": 1,
    "goals_for": 18,
    "goals_against": 9,
    "points": 13,
    "yellow_cards": 3,
    "red_cards": 0,
    "group_name": "Grupo A"
  },
  "matches": [...],
  "upcomingMatches": [...]
}

number

Team identifier.

name

string

Team name.

logo_url

string | null

Logo URL.

kit_color

string | null

Primary kit colour.

delegate

string | null

Delegate name.

coach

string | null

Coach name.

phone

string | null

Contact phone.

is_active

boolean

Whether the team is active (not soft-deleted).

isFollowing

boolean

Whether the authenticated user follows this team. Always false for unauthenticated requests.

players

object[]

Squad registered for the requested season, ordered by jersey number.

Show player properties

number

Player identifier.

name

string

Player name.

photo_url

string | null

Player photo URL.

jersey_number

string | null

Jersey number.

goals

number

Goals scored in the requested season.

stats

object | null

Season statistics for the team. null if no stats exist for the requested season.

Show stat properties

played

number

Matches played.

won

number

Matches won.

drawn

number

Matches drawn.

lost

number

Matches lost.

goals_for

number

Goals scored.

goals_against

number

Goals conceded.

points

number

Points total.

yellow_cards

number

Yellow cards received.

red_cards

number

Red cards received.

group_name

string | null

Name of the group the team is assigned to.

matches

object[]

All matches involving this team in the season, formatted the same as the match list response.

upcomingMatches

object[]

Subset of matches filtered to status pendiente.

GET /teams/:id/players

Returns the squad for a team in a specific season, ordered by jersey number.

number

required

Team identifier.

season_id

number

required

Season identifier.

Request
Response

cURL

curl "http://localhost:3000/teams/7/players?season_id=3"

[
  {
    "id": 5,
    "name": "Luis García",
    "photo_url": "https://res.cloudinary.com/.../photo.webp",
    "jersey_number": "10"
  }
]

POST /teams/:id/toggle-follow

Toggles the follow state between the authenticated user and a team. If the user already follows the team, the call unfollows it, and vice versa. Requires authentication.

number

required

Team identifier.

Request
Response — now following
Response — unfollowed

cURL

curl -X POST http://localhost:3000/teams/7/toggle-follow \
  -H "Authorization: Bearer <token>"

{ "message": "Ahora sigues al equipo", "isFollowing": true }

{ "message": "Has dejado de seguir al equipo", "isFollowing": false }

Admin team endpoints

The following endpoints require the admin role.

POST /teams

Creates a new team and optionally registers it for a season.

name

string

required

Team name.

kit_color

string

Primary kit colour.

logo_url

string

Cloudinary logo URL.

delegate

string

Delegate contact name.

coach

string

Head coach name.

phone

string

Contact phone number.

season_id

number

When provided, the team is immediately registered for this season with zeroed statistics.

cURL

curl -X POST http://localhost:3000/teams \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Nuevo Club", "kit_color": "#0000FF", "season_id": 3}'

PUT /teams/:id

Updates an existing team. If logo_url changes, the old Cloudinary asset is deleted unless it shares the same public ID.

number

required

Team identifier.

name

string

Team name.

kit_color

string

Primary kit colour.

logo_url

string

New Cloudinary logo URL.

delegate

string

Delegate name.

coach

string

Coach name.

phone

string

Contact phone.

DELETE /teams/:id

Soft-deletes a team (sets is_active = false). The team’s history is preserved.

number

required

Team identifier.

POST /teams/:id/restore

Restores a soft-deleted team.

number

required

Team identifier.

GET /teams/admin/trash

Returns all soft-deleted teams.

GET /teams/admin/report

Returns all active teams for a season together with their full player rosters.

season_id

number

required

Season identifier.

POST /teams/:id/register

Registers an existing team for a season by creating a zeroed team_stats entry.

number

required

Team identifier.

season_id

number

required

Season to register the team for.

DELETE /teams/:id/season/:seasonId

Removes a team from a specific season. Deletes the team’s statistics for that season and dissociates its players from the team (players remain registered to the season).

number

required

Team identifier.

seasonId

number

required

Season identifier.

Players

GET /players/:id

Returns full detail for a player, including their current team and active-season statistics.

number

required

Player identifier.

Request
Response

cURL

curl http://localhost:3000/players/5

{
  "id": 5,
  "name": "Luis García",
  "birth_date": "1998-06-15",
  "photo_url": "https://res.cloudinary.com/.../photo.webp",
  "is_active": true,
  "team_id": 7,
  "team_name": "Rayo Vallecas FC",
  "team_logo": "https://res.cloudinary.com/.../logo.webp",
  "stats": {
    "player_id": 5,
    "season_id": 3,
    "goals": 8,
    "yellow_cards": 1,
    "red_cards": 0,
    "matches_played": 6
  }
}

number

Player identifier.

name

string

Player name.

birth_date

string | null

Date of birth (ISO 8601 date).

photo_url

string | null

Player photo URL.

is_active

boolean

Whether the player is active.

team_id

number | null

Identifier of the team in the active season.

team_name

string | null

Team name in the active season.

team_logo

string | null

Team logo URL in the active season.

stats

object | null

Statistics for the active season. null if the player has no stats record yet.

Show stat properties

player_id

number

Player identifier.

season_id

number

Season identifier.

goals

number

Goals scored.

yellow_cards

number

Yellow cards received.

red_cards

number

Red cards received.

matches_played

number

Matches in which the player had at least one event.

Admin player endpoints

The following endpoints require the admin role unless otherwise noted.

GET /players

Returns a paginated, searchable list of players. Requires admin role.

season_id

number

Filter to players registered in this season.

exclude_season_id

number

Exclude players already registered in this season.

string

default:""

Name filter (accent-insensitive).

page

number

default:"1"

Page number.

limit

number

default:"10"

Results per page.

POST /players

Creates a new player and optionally registers them to a team and season.

name

string

required

Player name.

birth_date

string

Date of birth (ISO 8601).

photo_url

string

Cloudinary photo URL.

season_id

number

Season to register the player in.

team_id

number

Team to register the player with (requires season_id).

PUT /players/:id

Updates a player’s profile. If photo_url changes, the old Cloudinary asset is deleted unless it shares the same public ID.

number

required

Player identifier.

name

string

Player name.

birth_date

string

Date of birth.

photo_url

string

New photo URL.

POST /players/:id/register

Registers or transfers a player to a team in a specific season. Any existing registration for the same season is replaced.

number

required

Player identifier.

season_id

number

required

Season identifier.

team_id

number

Team identifier. Omit to register without a team assignment.

jersey_number

string

Jersey number. Returns a 400 if already taken in that team and season.

DELETE /players/:id/unregister

Removes a player from a specific team in a specific season.

number

required

Player identifier.

team_id

number

required

Team identifier.

season_id

number

required

Season identifier.

DELETE /players/:id/season/:seasonId

Removes a player from an entire season: deletes their team registration and their season statistics.

number

required

Player identifier.

seasonId

number

required

Season identifier.

DELETE /players/:id

Soft-deletes a player globally (is_active = false). History is preserved.

number

required

Player identifier.

POST /players/:id/restore

Restores a soft-deleted player.

number

required

Player identifier.

GET /players/admin/trash

Returns all soft-deleted players.

Overview

Endpoints

Teams

GET /teams

GET /teams/:id

GET /teams/:id/players

POST /teams/:id/toggle-follow

Admin team endpoints

POST /teams

PUT /teams/:id

DELETE /teams/:id

POST /teams/:id/restore

GET /teams/admin/trash

GET /teams/admin/report

POST /teams/:id/register

DELETE /teams/:id/season/:seasonId

Players

GET /players/:id

Admin player endpoints

GET /players

POST /players

PUT /players/:id

POST /players/:id/register

DELETE /players/:id/unregister

DELETE /players/:id/season/:seasonId

DELETE /players/:id

POST /players/:id/restore

GET /players/admin/trash

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Teams

​GET /teams

​GET /teams/:id

​GET /teams/:id/players

​POST /teams/:id/toggle-follow

​Admin team endpoints

​POST /teams

​PUT /teams/:id

​DELETE /teams/:id

​POST /teams/:id/restore

​GET /teams/admin/trash

​GET /teams/admin/report

​POST /teams/:id/register

​DELETE /teams/:id/season/:seasonId

​Players

​GET /players/:id

​Admin player endpoints

​GET /players

​POST /players

​PUT /players/:id

​POST /players/:id/register

​DELETE /players/:id/unregister

​DELETE /players/:id/season/:seasonId

​DELETE /players/:id

​POST /players/:id/restore

​GET /players/admin/trash

Build docs developers (and LLMs) love

Teams

GET /teams

GET /teams/:id

GET /teams/:id/players

POST /teams/:id/toggle-follow

Admin team endpoints

POST /teams

PUT /teams/:id

DELETE /teams/:id

POST /teams/:id/restore

GET /teams/admin/trash

GET /teams/admin/report

POST /teams/:id/register

DELETE /teams/:id/season/:seasonId

Players

GET /players/:id

Admin player endpoints

GET /players

POST /players

PUT /players/:id

POST /players/:id/register

DELETE /players/:id/unregister

DELETE /players/:id/season/:seasonId

DELETE /players/:id

POST /players/:id/restore

GET /players/admin/trash