Teams API — create, manage, and search teams

The Teams API is the core of Gestor Deportivo’s tournament management system. It lets authenticated users create and configure teams within their subscription plan limits, build rosters by assigning players to positions, transfer players between teams, and expose public search and listing endpoints for tournament brackets and standings pages.

Every request that requires authentication must include the header access-token: <jwt_token>. There is no Authorization: Bearer header on this API.

Team CRUD

Register a Team

POST /api/team/register-team Creates a new team under the authenticated user’s account. The nameTeam value is automatically formatted to Title Case before being stored. Team creation is gated by the user’s subscription plan — see the Memberships guide for per-plan limits. Auth required: Yes

Plan limits: Plan Gratis = 1 team · Plan Básico = 3 teams · Plan Premium = 10 teams. Admin accounts bypass all limits.

nameTeam

string

required

Display name for the team. Automatically converted to Title Case (e.g. "real madrid cf" → "Real Madrid Cf").

description

string

required

Short description of the team.

teamImg

file

Team crest / logo image (multipart/form-data). Optional.

bannerImg

file

Banner image displayed on the team profile (multipart/form-data). Optional.

curl -X POST https://api.example.com/api/team/register-team \
  -H "access-token: <jwt_token>" \
  -F "nameTeam=Los Halcones" \
  -F "description=Club de fútbol amateur de la ciudad" \
  -F "teamImg=@/path/to/crest.png" \
  -F "bannerImg=@/path/to/banner.jpg"

Show 200 — Team created

msj

string

Human-readable confirmation message.

status

boolean

true on success.

Team

object

Show Team fields

_id

string

MongoDB ObjectId of the new team.

nameTeam

string

Title-cased team name.

description

string

Team description.

teamImg

array

Array of uploaded crest image metadata objects.

bannerImg

array

Array of uploaded banner image metadata objects.

user

string

ObjectId of the owning user.

players

array

Roster array — empty on creation.

Show Error responses

Status	Cause
`400`	`nameTeam` or `description` missing
`400`	A team with the same name already exists for this user
`403`	Plan limit reached

Update Team Info

POST /api/team/updating/:teamId/team Updates the name, description, and/or images of an existing team. Only the team owner can call this endpoint. All fields are optional — send only what needs to change. Auth required: Yes (owner only)

teamId

string

required

MongoDB ObjectId of the team to update.

nameTeam

string

New team name. Converted to Title Case automatically.

description

string

Updated team description.

teamImg

file

Replacement crest image (multipart/form-data).

bannerImg

file

Replacement banner image (multipart/form-data).

curl -X POST https://api.example.com/api/team/updating/64a1f2c3e4b0d5f6a7890123/team \
  -H "access-token: <jwt_token>" \
  -F "description=Campeones regionales 2024" \
  -F "bannerImg=@/path/to/new-banner.jpg"

Show 200 — Team updated

msj

string

Confirmation message.

status

boolean

true on success.

updatedTeam

object

Full updated team document.

Delete a Team

POST /api/team/remove/:teamId/team Permanently deletes a team and its associated data. Only the team owner can perform this action. Auth required: Yes (owner only)

teamId

string

required

MongoDB ObjectId of the team to delete.

curl -X POST https://api.example.com/api/team/remove/64a1f2c3e4b0d5f6a7890123/team \
  -H "access-token: <jwt_token>"

Show 200 — Team deleted

msj

string

Confirmation message.

status

boolean

true on success.

Roster Management

Update Team Roster (Assign Players)

POST /api/team/updating/:teamId/players Adds or updates players on a team’s roster, assigning each player a shirt number and a position code. If a player is already on the roster, their entry is updated; new players are appended. Auth required: Yes (owner only)

teamId

string

required

MongoDB ObjectId of the team.

players

array

required

Array of player assignment objects. Each object must include:

Field	Type	Description
`_id`	string	Player’s MongoDB ObjectId
`shirtNumber`	number	Jersey number
`position`	string	Position code (see table below)

Valid position codes

Code	Position
`GK`	Goalkeeper
`CB`	Centre-Back
`LB`	Left-Back
`RB`	Right-Back
`LWB`	Left Wing-Back
`RWB`	Right Wing-Back
`CDM`	Central Defensive Mid
`CM`	Central Midfielder
`CAM`	Central Attacking Mid
`LM`	Left Midfielder
`RM`	Right Midfielder
`LW`	Left Winger
`RW`	Right Winger
`CF`	Centre Forward
`ST`	Striker

curl -X POST https://api.example.com/api/team/updating/64a1f2c3e4b0d5f6a7890123/players \
  -H "access-token: <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "players": [
      { "_id": "64b2e3d4f5c6a7b8c9d01234", "shirtNumber": 1,  "position": "GK" },
      { "_id": "64b2e3d4f5c6a7b8c9d01235", "shirtNumber": 10, "position": "CAM" },
      { "_id": "64b2e3d4f5c6a7b8c9d01236", "shirtNumber": 9,  "position": "ST" }
    ]
  }'

Show 200 — Roster updated

msj

string

Confirmation message.

status

boolean

true on success.

teamX

object

Updated team document including the full players roster array.

Show Error responses

Status	Cause
`400`	`teamId` is not a valid ObjectId
`400`	One or more position codes are invalid
`403`	Authenticated user is not the team owner
`404`	Team or one of the players not found

Remove a Player from a Team

POST /api/team/remove/:teamId/-/:playerId/player Removes a single player from a team’s roster. The - segment is a literal path separator required by the route definition. Auth required: Yes (owner only)

teamId

string

required

MongoDB ObjectId of the team.

playerId

string

required

MongoDB ObjectId of the player to remove.

curl -X POST https://api.example.com/api/team/remove/64a1f2c3e4b0d5f6a7890123/-/64b2e3d4f5c6a7b8c9d01235/player \
  -H "access-token: <jwt_token>"

Show 200 — Player removed

msj

string

Confirmation message.

status

boolean

true on success.

Show Error responses

Status	Cause
`400`	`teamId` or `playerId` is not a valid ObjectId
`403`	Authenticated user is not the team owner
`404`	Team or player not found

Player Transfers

For a full walkthrough of the two-step transfer workflow, see the Player Transfers guide.

Transferring a player is a two-step process:

Initiate — The source team owner (or any authenticated user) calls the initiate endpoint, which creates a pending TransferPlayer record.
Accept — The destination team owner calls the accept endpoint to confirm the transfer and move the player to the new roster.

Initiate a Transfer

POST /api/team/transfer/:playerId/-/:sourceTeamId/player Opens a transfer request for a player from the source team to a destination team. A TransferPlayer record is created with a pending status. The - segment is a literal path separator. Auth required: Yes

playerId

string

required

MongoDB ObjectId of the player being transferred.

sourceTeamId

string

required

MongoDB ObjectId of the team the player is currently on.

destinationTeamId

string

required

MongoDB ObjectId of the team that should receive the player.

curl -X POST https://api.example.com/api/team/transfer/64b2e3d4f5c6a7b8c9d01235/-/64a1f2c3e4b0d5f6a7890123/player \
  -H "access-token: <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{ "destinationTeamId": "64c3f4e5a6b7c8d9e0f01234" }'

Show 200 — Transfer initiated

msj

string

Confirmation message.

status

boolean

true on success.

Show Error responses

Status	Cause
`203`	A duplicate transfer request for this player already exists
`400`	`playerId` or `sourceTeamId` path params are missing or invalid
`400`	`destinationTeamId` body field is missing
`404`	Player, source team, or destination team not found

Accept a Transfer

POST /api/team/accepts/:destinationTeamId/transfer Confirms a pending transfer request. The player is removed from the source team’s roster and added to the destination team’s roster. Only the owner of the destination team can call this endpoint. Auth required: Yes (destination team owner only)

destinationTeamId

string

required

MongoDB ObjectId of the destination team. The API resolves the pending transfer record automatically.

curl -X POST https://api.example.com/api/team/accepts/64c3f4e5a6b7c8d9e0f01234/transfer \
  -H "access-token: <jwt_token>"

Show 200 — Transfer accepted

msj

string

Confirmation message.

status

boolean

true on success.

saveTransfer

object

The completed TransferPlayer record with updated status.

Listing & Search

List All Teams (Paginated)

POST /api/team/to-list/:pag?/:perpage? Returns a lightweight paginated list of all teams. Each item contains only _id, nameTeam, description, and teamImg — suitable for dropdowns and index pages. Auth required: No

pag

number

Page number (1-based). Defaults to 1.

perpage

number

Results per page. Defaults to the server-configured value.

curl -X POST https://api.example.com/api/team/to-list/1/20

Show 200 — Team list

msj

string

Confirmation message.

status

boolean

true on success.

data

array

Array of lean team objects (_id, nameTeam, description, teamImg).

pagination

object

{ total, page, perPage, totalPages } pagination metadata.

Get Team Detail

POST /api/team/to/:teamId/list-team Returns the full team document including the populated players roster array. Auth required: No

teamId

string

required

MongoDB ObjectId of the team.

curl -X POST https://api.example.com/api/team/to/64a1f2c3e4b0d5f6a7890123/list-team

Show 200 — Team detail

msj

string

Confirmation message.

status

boolean

true on success.

teamX

object

Full team document with populated players array.

List My Teams

POST /api/team/to-list-own Returns all teams owned by the currently authenticated user. Auth required: Yes

curl -X POST https://api.example.com/api/team/to-list-own \
  -H "access-token: <jwt_token>"

Show 200 — Own teams

msj

string

Confirmation message.

status

boolean

true on success.

teams

array

Array of team documents owned by the authenticated user.

Search Teams

POST /api/team/search/-/team/:query/:pag?/:perpage? Full case-insensitive text search across nameTeam. The - segment is a literal path separator. Auth required: No

query

string

required

Search term matched against team names (case-insensitive regex).

pag

number

Page number (1-based). Defaults to 1.

perpage

number

Results per page.

curl -X POST https://api.example.com/api/team/search/-/team/halcones/1/10

Show 200 — Search results

msj

string

Confirmation message.

status

boolean

true on success.

data

array

Matching team documents.

pagination

object

{ total, page, perPage, totalPages } pagination metadata.

Authentication & Users

Teams & Players

Events & Matches

Content

Teams API — create, manage, and search teams

Team CRUD

Register a Team

Update Team Info

Delete a Team

Roster Management

Update Team Roster (Assign Players)

Remove a Player from a Team

Player Transfers

Initiate a Transfer

Accept a Transfer

Listing & Search

List All Teams (Paginated)

Get Team Detail

List My Teams

Search Teams

Build docs developers (and LLMs) love

Authentication & Users

Teams & Players

Events & Matches

Content

Documentation Index

​Team CRUD

​Register a Team

​Update Team Info

​Delete a Team

​Roster Management

​Update Team Roster (Assign Players)

​Remove a Player from a Team

​Player Transfers

​Initiate a Transfer

​Accept a Transfer

​Listing & Search

​List All Teams (Paginated)

​Get Team Detail

​List My Teams

​Search Teams

Build docs developers (and LLMs) love

Team CRUD

Register a Team

Update Team Info

Delete a Team

Roster Management

Update Team Roster (Assign Players)

Remove a Player from a Team

Player Transfers

Initiate a Transfer

Accept a Transfer

Listing & Search

List All Teams (Paginated)

Get Team Detail

List My Teams

Search Teams