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 Players API covers the full lifecycle of a player record in FutsalLeague Manager. Any visitor can view a player’s public profile alongside their statistics for the active season. Administrators access a paginated, searchable list of all players, manage the global player database through create/update/soft-delete operations, and handle squad registrations — enrolling players into teams for a season, transferring them, unregistering them from a team, or removing them from a season entirely.

​
Public endpoints

​
Get player profile

GET /players/:id Returns a player’s profile data plus their stats for the currently active season. The team_id, team_name, and team_logo fields reflect the team the player is linked to in the active season (via team_players).
​
id
number
required
Player ID.
Response
​
id
number
Player ID.
​
name
string
Full name.
​
photo_url
string | null
Cloudinary profile photo URL.
​
birth_date
string | null
Date of birth (YYYY-MM-DD).
​
is_active
boolean
Whether the player is active (not soft-deleted).
​
team_id
number | null
Current team ID in the active season.
​
team_name
string | null
Current team name.
Current team logo URL.
​
stats
object | null
Player stats for the active season. null if no stats exist yet.
Example curl 
curl https://api.example.com/players/15
Example response 
{
  "id": 15,
  "name": "Adrián López",
  "photo_url": "https://res.cloudinary.com/example/adrian.webp",
  "birth_date": "1998-03-22",
  "is_active": true,
  "team_id": 3,
  "team_name": "FC Rayo",
  "team_logo": "https://res.cloudinary.com/example/rayo.webp",
  "stats": {
    "player_id": 15,
    "season_id": 2,
    "goals": 8,
    "yellow_cards": 1,
    "red_cards": 0,
    "matches_played": 7
  }
}
Errors
StatusMeaning
404Player not found.

​
Admin endpoints

​
List players

GET /players Returns a paginated, searchable list of active players. Supports filtering to a specific season (showing only players enrolled that season) and exclusion of players already registered in a given season. Requires admin authentication.
​
season_id
number
When provided, returns only players enrolled in that season (via team_players).
​
exclude_season_id
number
Exclude players already registered in this season. Useful when adding unregistered players to a new season.
​
page
number
default:"1"
Page number (1-indexed).
​
limit
number
default:"10"
Results per page.
​
search
string
default:""
Accent-insensitive substring search on player name.
Response
​
players
array
Array of player objects. When season_id is provided, each object also includes team_name, jersey_number, and team_id. Without a season filter, includes last_team (most recent team name).
​
pagination
object
curl "https://api.example.com/players?season_id=2&page=1&search=adri" \
  -H "Authorization: Bearer <admin-token>"

{
  "players": [
    {
      "id": 15,
      "name": "Adrián López",
      "photo_url": null,
      "birth_date": "1998-03-22",
      "is_active": true,
      "team_name": "FC Rayo",
      "jersey_number": "7",
      "team_id": 3
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 10,
    "totalPages": 1
  }
}

​
Create player

POST /players Creates a new player record. Optionally enrolls the player in a season and assigns them to a team in the same request.
​
name
string
required
Player full name.
​
birth_date
string
Date of birth in YYYY-MM-DD format.
​
photo_url
string
Cloudinary image URL for the player photo.
​
season_id
number
If provided, the player is registered in this season immediately.
​
team_id
number
Team to assign the player to within the given season. Requires season_id.
Response 
{ "message": "Jugador creado correctamente", "player": { "id": 31, "name": "Carlos Vega", "..." : "..." } }
StatusMeaning
400name not provided.

​
Update player

PUT /players/:id Updates a player’s profile fields. When photo_url changes and the Cloudinary public IDs differ, the old image is deleted automatically.
​
id
number
required
Player ID.
​
name
string
Player full name.
​
birth_date
string
Date of birth (YYYY-MM-DD).
​
photo_url
string
New photo URL.
Response 
{ "message": "Jugador actualizado correctamente", "player": { "id": 15, "name": "Adrián López M.", "..." : "..." } }
StatusMeaning
404Player not found.

​
Season registration endpoints

​
Register player in a team for a season

POST /players/:id/register Enrolls a player in a team for a specific season and assigns a jersey number. If the player already has a registration for that season, it is replaced (transfer). Returns a 400 error if the jersey number is already taken by another player on the same team in the same season.
​
id
number
required
Player ID.
​
season_id
number
required
Season to register the player in.
​
team_id
number
Team to assign the player to. Omit to register the player in the season without a team assignment.
​
jersey_number
string
Jersey number (stored as a string to allow non-numeric values such as "00").
Response 
{ "message": "Jugador inscrito o traspasado correctamente" }
Errors
StatusMeaning
400season_id not provided.
400Jersey number already taken by another player in that team/season.
Submitting this endpoint for a player already registered in the same season acts as a transfer — the old registration is removed and the new one is created atomically.

​
Unregister player from a team

DELETE /players/:id/unregister Removes a player’s assignment to a specific team in a specific season. The player’s overall season enrollment is preserved — use DELETE /players/:id/season/:seasonId to remove them from the season entirely.
​
id
number
required
Player ID.
​
team_id
number
required
Team to unregister the player from.
​
season_id
number
required
Season ID.
Response 
{ "message": "Jugador dado de baja del equipo correctamente" }

​
Remove player from a season

DELETE /players/:id/season/:seasonId Completely removes a player from a season: deletes all team_players records and all player_stats for that season. The player’s global record is not affected.
​
id
number
required
Player ID.
​
seasonId
number
required
Season ID.
This deletes the player’s statistics for the season permanently. The operation cannot be undone from the API.

​
Trash management

​
Soft-delete player

DELETE /players/:id Moves a player to the trash (is_active = false). Soft-deleted players do not appear in public or admin listings but retain all historical match data and statistics.
​
id
number
required
Player ID.
StatusMeaning
404Player not found.

​
List trashed players

GET /players/admin/trash Returns all soft-deleted players ordered alphabetically. Response — array of full player objects with is_active: false.

​
Restore player from trash

POST /players/:id/restore Restores a soft-deleted player, setting is_active = true.
​
id
number
required
Player ID.
Response 
{ "message": "Jugador restaurado correctamente" }
StatusMeaning
404Player not found.
Permanent deletion of players is intentionally disabled to preserve match history and Cloudinary images.

Build docs developers (and LLMs) love

Get started for freeTalk to us