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 Seasons API governs the full lifecycle of a competition season, from initial creation through to deletion. Public endpoints let any client list seasons or resolve the currently active one. Admin endpoints allow creating, editing, and deleting seasons, along with a structure import feature that clones groups, team registrations, and player squads from an existing season — saving significant setup time at the start of a new campaign.

​
Public endpoints

These routes do not require authentication and are safe to call from the frontend without a token.

​
GET /seasons

Returns all seasons ordered by start_date descending. Response — array
​
id
number
Unique season identifier.
​
name
string
Season name (e.g. "2025/26").
​
start_date
string
ISO 8601 start date.
​
end_date
string
ISO 8601 end date.
​
is_active
boolean
Whether this is the currently active season.
cURL
curl https://api.example.com/seasons
Example response
[
  {
    "id": 5,
    "name": "2026/27",
    "start_date": "2026-09-01",
    "end_date": "2027-06-30",
    "is_active": true
  },
  {
    "id": 4,
    "name": "2025/26",
    "start_date": "2025-09-01",
    "end_date": "2026-06-30",
    "is_active": false
  }
]

​
GET /seasons/active

Returns the single season currently marked as active. Useful for defaulting the UI to the current competition without requiring the caller to filter the full list. Responses
StatusDescription
200Active season object
404No season is currently marked active
cURL
curl https://api.example.com/seasons/active

​
Admin endpoints

All routes below require Authorization: Bearer <token> with role: "admin" in the JWT payload.

​
POST /seasons

Creates a new season. When import_from is provided, the server atomically clones groups, team stats (reset to zero), and player-team assignments from the source season within a single database transaction. If any part of the import fails the entire operation rolls back and no records are created.
Pass import_from with the ID of your previous season when setting up a new campaign. This pre-populates all groups, team registrations, and player squads so you only need to adjust what has changed rather than re-entering every team and player from scratch.
Request body
​
name
string
required
Human-readable season name (e.g. "2026/27").
​
start_date
string
ISO 8601 date the season begins.
​
end_date
string
ISO 8601 date the season ends.
​
is_active
boolean
default:"false"
Set to true to make this the active season. All other seasons will be automatically deactivated within the same transaction.
​
import_from
number
ID of an existing season to clone structure from. When provided, groups, team stats (zeroed), and player-team assignments are copied atomically.
Response — 201 Created Returns the newly created season object.
cURL
curl --request POST \
  "https://api.example.com/seasons" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "2026/27",
    "start_date": "2026-09-01",
    "end_date": "2027-06-30",
    "is_active": true,
    "import_from": 4
  }'
Example response
{
  "id": 5,
  "name": "2026/27",
  "start_date": "2026-09-01",
  "end_date": "2027-06-30",
  "is_active": true
}

​
PUT /seasons/:id

Updates the fields of an existing season. Setting is_active: true automatically sets all other seasons to is_active = false before the update is applied, guaranteeing at most one active season at any time. Path parameters
​
id
number
required
ID of the season to update.
Request body
​
name
string
New season name.
​
start_date
string
New start date (ISO 8601).
​
end_date
string
New end date (ISO 8601).
​
is_active
boolean
When true, deactivates all other seasons before marking this one active.
Response — Updated season object.
cURL
curl --request PUT \
  "https://api.example.com/seasons/5" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{ "name": "2026/27 Revised", "is_active": true }'

​
DELETE /seasons/:id

Permanently deletes a season record from the database.
Season deletion is permanent and irreversible. If the season has dependent records — such as matches or groups — the database will return a constraint error and the endpoint responds with 500 and a message instructing you to remove all dependencies first. Always delete or reassign matches and groups before deleting a season.
Path parameters
​
id
number
required
ID of the season to delete.
Response
​
message
string
Confirmation of deletion.
cURL
curl --request DELETE \
  "https://api.example.com/seasons/5" \
  --header "Authorization: Bearer <token>"

​
POST /seasons/:id/import-structure

Clones the structure of another season into an existing target season. The operation copies groups (by name), initializes team stats at zero for each team from the source season, and re-enrolls players with their jersey numbers — all within a single atomic transaction. This endpoint is useful when a season already exists and you want to pull structure from a different source season after creation, as opposed to using the import_from field on POST /seasons. Path parameters
​
id
number
required
ID of the target season that will receive the imported structure.
Request body
​
fromSeasonId
number
required
ID of the source season to clone groups, team stats, and player squads from.
Response
​
message
string
Confirmation message noting that groups and player squads have been imported and teams are ready to be assigned to groups.
​
groupsImported
number
Number of groups copied from the source season.
cURL
curl --request POST \
  "https://api.example.com/seasons/5/import-structure" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{ "fromSeasonId": 4 }'
Example response
{
  "message": "Grupos y plantillas importados. Los equipos están listos para ser asignados a grupos.",
  "groupsImported": 6
}

​
Group management

Groups represent competition divisions within a season (e.g. “Group A”, “Group B”). The list endpoint is public; create, update, and delete require an admin JWT.

​
GET /groups

Returns all groups, each joined with its parent season name. Ordered by season start date descending, then group name ascending. Query parameters
​
season_id
number
Filter results to groups belonging to a specific season.
Response — array
​
id
number
Group ID.
​
name
string
Group name.
​
season_id
number
ID of the parent season.
​
season_name
string
Name of the parent season (joined).
cURL
curl "https://api.example.com/groups?season_id=5"

​
POST /groups

Creates a new group within a season. Both name and season_id are required. Request body
​
name
string
required
Display name for the group (e.g. "Group A").
​
season_id
number
required
ID of the season this group belongs to.
Response — 201 Created. Returns the new group object.
cURL
curl --request POST \
  "https://api.example.com/groups" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{ "name": "Group A", "season_id": 5 }'

​
PUT /groups/:id

Updates the name (and optionally the parent season) of an existing group. Path parameters
​
id
number
required
ID of the group to update.
Request body
​
name
string
New group name.
​
season_id
number
Reassign to a different season.
Response — Updated group object.
cURL
curl --request PUT \
  "https://api.example.com/groups/12" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{ "name": "Group B", "season_id": 5 }'

​
DELETE /groups/:id

Permanently deletes a group. The operation will fail if the group has associated matches. Path parameters
​
id
number
required
ID of the group to delete.
Response
​
message
string
Confirmation of deletion.
cURL
curl --request DELETE \
  "https://api.example.com/groups/12" \
  --header "Authorization: Bearer <token>"

Build docs developers (and LLMs) love

Get started for freeTalk to us