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 Teams API provides public access to team listings and detailed profiles — including squad rosters, season statistics, and upcoming matches. Authenticated users can follow or unfollow any team. Administrators have full CRUD capabilities: creating teams, editing metadata, soft-deleting to a trash bin with restore support, registering existing teams in new seasons, and generating a detailed report of all teams and players for a given season.

​
Public endpoints

​
List teams

GET /teams Returns a paginated list of active teams. Filter by season to show only teams that participated in that season (have stats or players registered). Supports fuzzy, accent-insensitive name search.
​
season_id
number
When provided, returns only teams with stats or registered players in that season.
​
exclude_season_id
number
Exclude teams already registered in this season. Useful when assigning new teams to a season.
​
page
number
default:"1"
Page number (1-indexed).
​
limit
number
default:"10"
Results per page.
​
search
string
default:""
Accent-insensitive substring search on team name.
Response
​
teams
array
Array of team summary objects.
​
pagination
object
curl "https://api.example.com/teams?season_id=2&page=1&limit=10&search=rayo"

{
  "teams": [
    {
      "id": 3,
      "name": "FC Rayo",
      "logo_url": "https://res.cloudinary.com/example/rayo.webp",
      "kit_color": "#FFD700",
      "delegate": "Carlos Pérez",
      "coach": "José Martínez",
      "phone": "600123456"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 10,
    "totalPages": 1
  }
}

​
Get team detail

GET /teams/:id Returns the full team profile: basic info, season stats, full squad with per-player goal tallies, upcoming matches, and all matches for the season. Optionally filters data by season. When an authenticated user’s token is provided, the response also includes the isFollowing flag.
​
id
number
required
Team ID.
​
season_id
number
Season to use when fetching players, stats, and matches. Defaults to the active season.
Response 
{
  "id": 3,
  "name": "FC Rayo",
  "logo_url": "https://res.cloudinary.com/example/rayo.webp",
  "kit_color": "#FFD700",
  "delegate": "Carlos Pérez",
  "coach": "José Martínez",
  "phone": "600123456",
  "is_active": true,
  "isFollowing": false,
  "players": [
    {
      "id": 15,
      "name": "Adrián López",
      "photo_url": "https://res.cloudinary.com/example/adrian.webp",
      "jersey_number": "7",
      "goals": 8
    }
  ],
  "stats": {
    "team_id": 3,
    "group_id": 1,
    "season_id": 2,
    "group_name": "Grupo A",
    "points": 12,
    "played": 4,
    "won": 4,
    "drawn": 0,
    "lost": 0,
    "goals_for": 18,
    "goals_against": 5,
    "yellow_cards": 2,
    "red_cards": 0
  },
  "matches": [
    {
      "id": 42,
      "date": "2025-11-15T19:00:00",
      "status": "finalizado",
      "homeTeam": { "id": 3, "name": "FC Rayo", "logoUrl": null },
      "awayTeam": { "id": 7, "name": "Atlético Sur", "logoUrl": null },
      "homeTeamPlaceholder": null,
      "awayTeamPlaceholder": null,
      "homeGoals": 3,
      "awayGoals": 1,
      "field": { "id": 1, "name": "Pabellón Municipal", "location": "Calle Mayor 12" }
    }
  ],
  "upcomingMatches": []
}
Errors
StatusMeaning
404Team not found.

​
List players for a team in a season

GET /teams/:id/players Returns the squad registered for a specific team in a given season, ordered by jersey number.
​
id
number
required
Team ID.
​
season_id
number
required
Season ID. This parameter is required.
Response — array of player objects: 
[
  {
    "id": 15,
    "name": "Adrián López",
    "photo_url": "https://res.cloudinary.com/example/adrian.webp",
    "jersey_number": "7"
  }
]
StatusMeaning
400season_id not provided.

​
Follow / unfollow a team

POST /teams/:id/toggle-follow Toggles the follow relationship between the authenticated user and the team. If the user already follows the team, the endpoint unfollows. Authentication is required.
​
id
number
required
Team ID.
Response 
{ "message": "Ahora sigues al equipo", "isFollowing": true }
or 
{ "message": "Has dejado de seguir al equipo", "isFollowing": false }

​
Admin endpoints

​
Create team

POST /teams Creates a new team. Optionally registers the team in a season immediately by passing season_id.
​
name
string
required
Team name. Must be unique and non-empty.
​
kit_color
string
Primary kit colour.
​
logo_url
string
Cloudinary image URL for the team logo.
​
delegate
string
Delegate contact name.
​
coach
string
Head coach name.
​
phone
string
Contact phone number.
​
season_id
number
If provided, the team is registered in this season immediately after creation.
Response 
{ "message": "Equipo creado correctamente", "team": { "id": 14, "name": "Nuevo FC", "..." : "..." } }

​
Update team

PUT /teams/:id Updates team metadata. When logo_url changes and the public IDs differ, the previous image is deleted from Cloudinary automatically.
​
id
number
required
Team ID.
​
name
string
Team name.
​
kit_color
string
Kit colour.
​
logo_url
string
New logo URL.
​
delegate
string
Delegate name.
​
coach
string
Coach name.
​
phone
string
Phone number.

​
Soft-delete team

DELETE /teams/:id Moves the team to the trash (is_active = false). The team no longer appears in public listings but retains all historical data.
​
id
number
required
Team ID.

​
Restore team from trash

POST /teams/:id/restore Restores a soft-deleted team.
​
id
number
required
Team ID.

​
List trashed teams

GET /teams/admin/trash Returns all teams with is_active = false, ordered alphabetically.

​
Register team in a season

POST /teams/:id/register Registers an existing team in a season by creating a team_stats record. Any existing record for the same team/season combination is replaced to avoid duplicates.
​
id
number
required
Team ID.
​
season_id
number
required
Season to register the team in.
Response 
{ "message": "Equipo inscrito correctamente" }

​
Remove team from a season

DELETE /teams/:id/season/:seasonId Removes a team from a specific season. Deletes the team’s stats for that season and unlinks all players (players retain their records but are no longer assigned to the team for that season).
​
id
number
required
Team ID.
​
seasonId
number
required
Season ID.
This does not delete the team globally — only its participation in the specified season. Player records are unlinked, not deleted.

​
Teams and players report

GET /teams/admin/report Returns a list of all teams active in a season, each with their registered players. Intended for generating official squad sheets.
​
season_id
number
required
Season ID. Required — returns 400 if omitted.
Response — array of team objects, each with an embedded players array: 
[
  {
    "id": 3,
    "name": "FC Rayo",
    "delegate": "Carlos Pérez",
    "coach": "José Martínez",
    "phone": "600123456",
    "players": [
      {
        "id": 15,
        "name": "Adrián López",
        "jersey_number": "7",
        "birth_date": "1998-03-22",
        "team_id": 3
      }
    ]
  }
]

curl "https://api.example.com/teams/admin/report?season_id=2" \
  -H "Authorization: Bearer <admin-token>"

Build docs developers (and LLMs) love

Get started for freeTalk to us