Teams API — list, detail, and management endpoints

GET /teams — list teams

Returns a paginated list of all teams. When season_id is provided, only teams that have stats or players registered for that season are returned.Method: GET
Path: /teams
Auth: None

Query parameters

page

number

default:"1"

Page number to retrieve.

limit

number

default:"10"

Number of teams per page.

string

default:""

Case-insensitive substring filter applied to the team name.

season_id

number

When provided, restricts results to teams active in that season (present in team_stats or team_players for the given season ID).

Response

teams

object[]

Array of team objects.

Show team properties

number

Team ID.

name

string

Team name.

logo_url

string

URL of the team logo.

kit_color

string

Primary kit colour (hex or name).

delegate

string

Name of the team delegate.

coach

string

Name of the head coach.

phone

string

Contact phone number.

pagination

object

Pagination metadata.

Show properties

total

number

Total number of matching teams.

page

number

Current page number.

limit

number

Items per page.

totalPages

number

Total number of pages.

Example

curl "https://api.futsalmanager.example/teams?page=1&limit=5&search=atletico&season_id=3"

Response

{
  "teams": [
    {
      "id": 7,
      "name": "Atlético Norte",
      "logo_url": "https://res.cloudinary.com/example/image/upload/teams/atletico.png",
      "kit_color": "#e63946",
      "delegate": "Carlos Pérez",
      "coach": "Juan Martínez",
      "phone": "600123456"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 5,
    "totalPages": 1
  }
}

GET /teams/:id — team detail

Returns the full profile of a single team, including its current-season players, statistics, full fixture list, and upcoming matches. If no season_id is supplied the active season is used.Method: GET
Path: /teams/:id
Auth: Optional (JWT). When authenticated, the isFollowing field reflects whether the current user follows this team.

Path parameters

number

required

Team ID.

Query parameters

season_id

number

Season to load stats and players for. Defaults to the active season.

Response

number

Team ID.

name

string

Team name.

logo_url

string

Logo URL.

kit_color

string

Primary kit colour.

delegate

string

Delegate name.

coach

string

Coach name.

phone

string

Contact phone.

isFollowing

boolean

Whether the authenticated user follows this team (false for anonymous requests).

players

object[]

Players registered to the team in the requested season, ordered by jersey number.

Show player properties

number

Player ID.

name

string

Player name.

photo_url

string

Player photo URL.

jersey_number

string

Jersey number.

goals

number

Goals scored this season.

stats

object | null

Team stats for the requested season, or null if none exist.

Show stats properties

points

number

Total points.

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.

yellow_cards

number

Total yellow cards.

red_cards

number

Total red cards.

group_name

string

Name of the group the team belongs to.

matches

object[]

All matches in the season (home and away), ordered by date.

Show match properties

number

Match ID.

date

string

ISO 8601 date-time string.

status

string

Match status: pendiente, finalizado, or similar.

homeTeam

object | null

Home team summary (id, name, logoUrl).

awayTeam

object | null

Away team summary (id, name, logoUrl).

homeGoals

number | null

Goals scored by the home team.

awayGoals

number | null

Goals scored by the away team.

field

object | null

Field summary (id, name, location).

upcomingMatches

object[]

Subset of matches where status is pendiente or unset.

POST /teams — create team (admin)

Creates a new team. Optionally registers it in a season by creating a team_stats row for that season.Method: POST
Path: /teams
Auth: JWT + admin role required

Request body

name

string

required

Team name. Must be unique.

kit_color

string

Primary kit colour (e.g. "#e63946").

logo_url

string

Full URL to the team logo image.

delegate

string

Name of the team delegate.

coach

string

Name of the head coach.

phone

string

Contact phone number.

season_id

number

If provided, the team is immediately enrolled in this season with zeroed stats.

Response — `201 Created`

message

string

Confirmation message.

team

object

Full team record as stored in the database.

PUT /teams/:id — update team (admin)

Updates an existing team’s profile fields.Method: PUT
Path: /teams/:id
Auth: JWT + admin role required

Path parameters

number

required

Team ID to update.

Request body

name

string

Team name.

kit_color

string

Primary kit colour.

logo_url

string

Logo URL.

delegate

string

Delegate name.

coach

string

Coach name.

phone

string

Contact phone.

Response — `200 OK`

message

string

Confirmation message.

team

object

Updated team record.

Example

curl -X PUT "https://api.futsalmanager.example/teams/7" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Atlético Norte", "kit_color": "#e63946", "coach": "Carlos López", "delegate": "Pedro Ruiz", "phone": "600123456"}'

DELETE /teams/:id — delete team (admin)

Permanently deletes a team. Returns 500 if the team has associated players or matches; remove those dependencies first.Method: DELETE
Path: /teams/:id
Auth: JWT + admin role required

Path parameters

number

required

Team ID to delete.

Response — `200 OK`

message

string

Confirmation message.

Example

curl -X DELETE "https://api.futsalmanager.example/teams/7" \
  -H "Authorization: Bearer <token>"

POST /teams/:id/toggle-follow — follow or unfollow (auth required)

Toggles the follow relationship between the authenticated user and a team. Calling the endpoint when already following will unfollow, and vice versa.Method: POST
Path: /teams/:id/toggle-follow
Auth: JWT required

Path parameters

number

required

Team ID to follow or unfollow.

Response — `200 OK`

message

string

Human-readable confirmation.

isFollowing

boolean

true if the user is now following the team, false if unfollowed.

Example

curl -X POST "https://api.futsalmanager.example/teams/7/toggle-follow" \
  -H "Authorization: Bearer <token>"

Response

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

GET /teams/:id/players — team roster for a season

Returns the list of players registered to a team for a specific season, ordered by jersey number.Method: GET
Path: /teams/:id/players
Auth: None

Path parameters

number

required

Team ID.

Query parameters

season_id

number

required

Season ID. This parameter is mandatory; the server returns 400 if it is omitted.

Response — `200 OK`

An array of player objects:

number

Player ID.

name

string

Player name.

photo_url

string

Player photo URL.

jersey_number

string

Jersey number for this team and season.

Example

curl "https://api.futsalmanager.example/teams/7/players?season_id=3"

Response

[
  { "id": 42, "name": "Marcos Ruiz", "photo_url": "https://cdn.example/players/42.jpg", "jersey_number": "10" },
  { "id": 15, "name": "Laura Gil",   "photo_url": null, "jersey_number": "4" }
]

Authentication

Matches

Teams & Players

Standings & Statistics

Admin

Teams API — list, detail, and management endpoints

Query parameters

Response

Example

Path parameters

Query parameters

Response

Request body

Response — `201 Created`

Path parameters

Request body

Response — `200 OK`

Example

Path parameters

Response — `200 OK`

Example

Path parameters

Response — `200 OK`

Example

Path parameters

Query parameters

Response — `200 OK`

Example

Build docs developers (and LLMs) love

Authentication

Matches

Teams & Players

Standings & Statistics

Admin

Documentation Index

​Query parameters

​Response

​Example

​Path parameters

​Query parameters

​Response

​Request body

​Response — 201 Created

​Path parameters

​Request body

​Response — 200 OK

​Example

​Path parameters

​Response — 200 OK

​Example

​Path parameters

​Response — 200 OK

​Example

​Path parameters

​Query parameters

​Response — 200 OK

​Example

Build docs developers (and LLMs) love

Query parameters

Response

Example

Path parameters

Query parameters

Response

Request body

Response — `201 Created`

Path parameters

Request body

Response — `200 OK`

Example

Path parameters

Response — `200 OK`

Example

Path parameters

Response — `200 OK`

Example

Path parameters

Query parameters

Response — `200 OK`

Example