Seasons, groups, and fields API endpoints

The seasons, groups, and fields endpoints expose the structural layer of the competition. Public callers can list seasons and groups; admin-only endpoints handle creating, editing, and deleting all three resource types.

Seasons

GET /seasons

Returns all seasons ordered by start date, most recent first.

Request
Response

cURL

curl http://localhost:3000/seasons

[
  {
    "id": 3,
    "name": "Liga 2024-25",
    "start_date": "2024-09-01",
    "end_date": "2025-06-30",
    "is_active": true
  },
  {
    "id": 2,
    "name": "Liga 2023-24",
    "start_date": "2023-09-01",
    "end_date": "2024-06-30",
    "is_active": false
  }
]

number

Season identifier.

name

string

Season name.

start_date

string

Start date (ISO 8601).

end_date

string

End date (ISO 8601).

is_active

boolean

Whether this is the currently active season. Only one season is active at a time.

GET /seasons/active

Returns the single active season.

Request
Response

cURL

curl http://localhost:3000/seasons/active

{
  "id": 3,
  "name": "Liga 2024-25",
  "start_date": "2024-09-01",
  "end_date": "2025-06-30",
  "is_active": true
}

Returns 404 when no season has is_active = true.

POST /seasons

Creates a new season. When is_active is true, all other seasons are deactivated first. Optionally imports groups, team registrations, and squad rosters from an existing season in the same database transaction. Requires admin role.

name

string

required

Season name.

start_date

string

Start date (ISO 8601).

end_date

string

End date (ISO 8601).

is_active

boolean

default:"false"

Set to true to mark this as the active season.

import_from

number

ID of a season to import structure from. Copies groups, team registrations (with zeroed statistics), and player squad entries into the new season.

Request
Response

cURL

curl -X POST http://localhost:3000/seasons \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Liga 2025-26",
    "start_date": "2025-09-01",
    "end_date": "2026-06-30",
    "is_active": true,
    "import_from": 3
  }'

{
  "id": 4,
  "name": "Liga 2025-26",
  "start_date": "2025-09-01",
  "end_date": "2026-06-30",
  "is_active": true
}

PUT /seasons/:id

Updates an existing season. When is_active is set to true, all other seasons are deactivated. Requires admin role.

number

required

Season identifier.

name

string

Season name.

start_date

string

Start date (ISO 8601).

end_date

string

End date (ISO 8601).

is_active

boolean

Whether to make this the active season.

cURL

curl -X PUT http://localhost:3000/seasons/3 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Liga 2024-25 (revised)", "is_active": true}'

Returns the updated season object.

DELETE /seasons/:id

Permanently deletes a season. Fails if the season has dependant records (groups, matches) due to database foreign-key constraints. Requires admin role.

number

required

Season identifier.

cURL

curl -X DELETE http://localhost:3000/seasons/3 \
  -H "Authorization: Bearer <token>"

This is a hard delete. Remove all associated groups and matches before deleting a season.

POST /seasons/:id/import-structure

Copies the group structure, team registrations (with zeroed stats), and player squad entries from another season into an existing season. Runs in a single database transaction. Requires admin role.

number

required

The target season that will receive the imported data.

fromSeasonId

number

required

The source season to copy from.

Request
Response

cURL

curl -X POST http://localhost:3000/seasons/4/import-structure \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"fromSeasonId": 3}'

{
  "message": "Grupos y plantillas importados. Los equipos están listos para ser asignados a grupos.",
  "groupsImported": 4
}

message

string

Confirmation message.

groupsImported

number

Number of groups copied from the source season.

Groups

GET /groups

Returns all groups, optionally filtered by season. Results are ordered by season start date (newest first) and then group name alphabetically.

season_id

number

Filter to groups belonging to this season.

Request
Response

cURL

curl "http://localhost:3000/groups?season_id=3"

[
  { "id": 1, "name": "Grupo A", "season_id": 3, "season_name": "Liga 2024-25" },
  { "id": 2, "name": "Grupo B", "season_id": 3, "season_name": "Liga 2024-25" }
]

number

Group identifier.

name

string

Group name.

season_id

number

Season this group belongs to.

season_name

string

Season name.

GET /groups/:id/teams

Returns the teams assigned to a group, ordered by points then goals scored.

number

required

Group identifier.

cURL

curl http://localhost:3000/groups/1/teams

Each item contains id, name, logo_url, played, and points.

Admin group endpoints

The following endpoints require the admin role.

POST /groups

Creates a new group in a season.

name

string

required

Group name.

season_id

number

required

Season to create the group in.

cURL

curl -X POST http://localhost:3000/groups \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Grupo C", "season_id": 3}'

Returns the created group object with 201 Created.

PUT /groups/:id

Updates a group’s name or season assignment.

number

required

Group identifier.

name

string

New group name.

season_id

number

New season assignment.

DELETE /groups/:id

Permanently deletes a group. Fails if the group has associated matches.

number

required

Group identifier.

POST /groups/:id/teams

Assigns a team to a group by creating a team_stats entry for the given team, group, and season.

number

required

Group identifier.

team_id

number

required

Team identifier.

season_id

number

required

Season identifier.

DELETE /groups/:id/teams/:teamId

Removes a team from a group by deleting the corresponding team_stats row.

number

required

Group identifier.

teamId

number

required

Team identifier.

season_id

number

required

Season identifier (required query parameter).

Fields

GET /fields

Returns all active playing fields ordered by name.

Request
Response

cURL

curl http://localhost:3000/fields

[
  { "id": 1, "name": "Pabellón Norte", "location": "Av. del Deporte 1", "is_active": true },
  { "id": 2, "name": "Pabellón Sur", "location": "Calle Olímpica 5", "is_active": true }
]

number

Field identifier.

name

string

Field name.

location

string | null

Physical address or location description.

is_active

boolean

Always true in this response — inactive fields are excluded.

Admin field endpoints

The following endpoints require the admin role.

POST /fields

Creates a new field.

name

string

required

Field name.

location

string

Physical address or location description.

cURL

curl -X POST http://localhost:3000/fields \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Pabellón Central", "location": "Calle Mayor 10"}'

Returns the created field object with 201 Created.

PUT /fields/:id

Updates a field’s name or location.

number

required

Field identifier.

name

string

Field name.

location

string

Location description.

DELETE /fields/:id

Soft-deletes a field (sets is_active = false).

number

required

Field identifier.

POST /fields/:id/restore

Restores a soft-deleted field.

number

required

Field identifier.

DELETE /fields/:id/permanent

Permanently deletes a field. The field must already be in the trash (is_active = false). Returns 400 if the field has associated matches.

number

required

Field identifier.

Permanently deleted fields cannot be recovered.

GET /fields/admin/trash

Returns all soft-deleted fields, ordered by name.

cURL

curl http://localhost:3000/fields/admin/trash \
  -H "Authorization: Bearer <token>"

Overview

Endpoints

Seasons, groups, and fields API endpoints

Seasons

GET /seasons

GET /seasons/active

POST /seasons

PUT /seasons/:id

DELETE /seasons/:id

POST /seasons/:id/import-structure

Groups

GET /groups

GET /groups/:id/teams

Admin group endpoints

POST /groups

PUT /groups/:id

DELETE /groups/:id

POST /groups/:id/teams

DELETE /groups/:id/teams/:teamId

Fields

GET /fields

Admin field endpoints

POST /fields

PUT /fields/:id

DELETE /fields/:id

POST /fields/:id/restore

DELETE /fields/:id/permanent

GET /fields/admin/trash

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Seasons

​GET /seasons

​GET /seasons/active

​POST /seasons

​PUT /seasons/:id

​DELETE /seasons/:id

​POST /seasons/:id/import-structure

​Groups

​GET /groups

​GET /groups/:id/teams

​Admin group endpoints

​POST /groups

​PUT /groups/:id

​DELETE /groups/:id

​POST /groups/:id/teams

​DELETE /groups/:id/teams/:teamId

​Fields

​GET /fields

​Admin field endpoints

​POST /fields

​PUT /fields/:id

​DELETE /fields/:id

​POST /fields/:id/restore

​DELETE /fields/:id/permanent

​GET /fields/admin/trash

Build docs developers (and LLMs) love

Seasons

GET /seasons

GET /seasons/active

POST /seasons

PUT /seasons/:id

DELETE /seasons/:id

POST /seasons/:id/import-structure

Groups

GET /groups

GET /groups/:id/teams

Admin group endpoints

POST /groups

PUT /groups/:id

DELETE /groups/:id

POST /groups/:id/teams

DELETE /groups/:id/teams/:teamId

Fields

GET /fields

Admin field endpoints

POST /fields

PUT /fields/:id

DELETE /fields/:id

POST /fields/:id/restore

DELETE /fields/:id/permanent

GET /fields/admin/trash