Seasons, groups, and fields API reference

The competition structure is defined by three related resources. Seasons represent the competition year and carry an is_active flag to mark the running edition. Groups belong to a season and act as the pools teams are sorted into for the group stage. Fields are the physical venues where matches are played. Read endpoints for all three resources are public; write operations require an admin JWT.

Seasons

GET /seasons — list all seasons

Returns all seasons ordered by start date descending.Method: GET Path: /seasons Auth: None

Response — `200 OK`

An array of season objects:

number

Season ID.

name

string

Season name (e.g. "2024/2025").

start_date

string

Season start date.

end_date

string

Season end date.

is_active

boolean

true for the current active season.

Example

curl "https://api.futsalmanager.example/seasons"

Response

[
  { "id": 3, "name": "2024/2025", "start_date": "2024-09-01", "end_date": "2025-05-31", "is_active": true },
  { "id": 2, "name": "2023/2024", "start_date": "2023-09-01", "end_date": "2024-05-31", "is_active": false }
]

GET /seasons/active — retrieve the active season

Returns the single currently active season. Returns 404 if none exists.Method: GET Path: /seasons/active Auth: None

Response — `200 OK`

number

Season ID.

name

string

Season name.

start_date

string

Start date.

end_date

string

End date.

is_active

boolean

Always true.

Example

curl "https://api.futsalmanager.example/seasons/active"

POST /seasons — create a season (admin)

Creates a new season. If is_active is true, all other seasons are deactivated atomically in the same transaction.Optionally, pass import_from with the ID of an existing season to clone that season’s groups, team enrollments, and player rosters (with zeroed stats) into the new season in the same transaction.Method: POST Path: /seasons Auth: JWT + admin role required

Request body

name

string

required

Season name.

start_date

string

Start date in YYYY-MM-DD format.

end_date

string

End date in YYYY-MM-DD format.

is_active

boolean

default:"false"

When true, this season becomes the active one and all others are deactivated.

import_from

number

ID of a season to clone groups, team stats, and player rosters from. Performed atomically with season creation.

Response — `201 Created`

The created season record.

Example

curl -X POST "https://api.futsalmanager.example/seasons" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "2025/2026", "start_date": "2025-09-01", "end_date": "2026-05-31", "is_active": true, "import_from": 3}'

PUT /seasons/:id — update a season (admin)

Updates a season’s name, dates, or active status. Setting is_active to true deactivates all other seasons.Method: PUT Path: /seasons/:id Auth: JWT + admin role required

Path parameters

number

required

Season ID to update.

Request body

name

string

Season name.

start_date

string

Start date (YYYY-MM-DD).

end_date

string

End date (YYYY-MM-DD).

is_active

boolean

Set to true to make this the active season.

Response — `200 OK`

The updated season record.

Example

curl -X PUT "https://api.futsalmanager.example/seasons/3" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "2024/2025", "start_date": "2024-09-01", "end_date": "2025-06-30", "is_active": true}'

DELETE /seasons/:id — delete a season (admin)

Permanently deletes a season. Returns an error if the season has dependent records such as groups or matches.Method: DELETE Path: /seasons/:id Auth: JWT + admin role required

Path parameters

number

required

Season ID to delete.

Response — `200 OK`

message

string

Confirmation message.

Example

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

POST /seasons/:id/import-structure — clone structure from another season (admin)

Clones groups, team stats (zeroed), and player rosters from a source season into an existing target season. All operations are performed in a single database transaction.Method: POST Path: /seasons/:id/import-structure Auth: JWT + admin role required

Path parameters

number

required

ID of the target season to import structure into.

Request body

fromSeasonId

number

required

ID of the source season to clone structure from.

Response — `200 OK`

message

string

Confirmation message.

groupsImported

number

Number of groups cloned.

Example

curl -X POST "https://api.futsalmanager.example/seasons/4/import-structure" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"fromSeasonId": 3}'

Groups

GET /groups — list groups

Returns all groups joined with their season name, ordered by season start date descending and then by group name. Optionally filter by season.Method: GET Path: /groups Auth: None

Query parameters

season_id

number

Filter groups to a specific season.

Response — `200 OK`

An array of group objects:

number

Group ID.

name

string

Group name (e.g. "Grupo A").

season_id

number

Season this group belongs to.

season_name

string

Name of the parent season.

Example

curl "https://api.futsalmanager.example/groups?season_id=3"

Response

[
  { "id": 1, "name": "Grupo A", "season_id": 3, "season_name": "2024/2025" },
  { "id": 2, "name": "Grupo B", "season_id": 3, "season_name": "2024/2025" }
]

POST /groups — create a group (admin)

Creates a new group within a season.Method: POST Path: /groups Auth: JWT + admin role required

Request body

name

string

required

Group name.

season_id

number

required

Season the group belongs to.

Response — `201 Created`

The created group record.

Example

curl -X POST "https://api.futsalmanager.example/groups" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Grupo C", "season_id": 3}'

PUT /groups/:id — update a group (admin)

Updates a group’s name or season association.Method: PUT Path: /groups/:id Auth: JWT + admin role required

Path parameters

number

required

Group ID to update.

Request body

name

string

Updated group name.

season_id

number

Updated season ID.

Response — `200 OK`

The updated group record.

Example

curl -X PUT "https://api.futsalmanager.example/groups/1" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Grupo A", "season_id": 3}'

DELETE /groups/:id — delete a group (admin)

Deletes a group. Returns an error if the group has associated matches.Method: DELETE Path: /groups/:id Auth: JWT + admin role required

Path parameters

number

required

Group ID to delete.

Response — `200 OK`

message

string

Confirmation message.

Example

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

GET /groups/:id/teams — list teams in a group

Returns all teams assigned to a group, ordered by points descending then goals scored.Method: GET Path: /groups/:id/teams Auth: None

Path parameters

number

required

Group ID.

Response — `200 OK`

An array of team summary objects:

number

Team ID.

name

string

Team name.

logo_url

string

Team logo URL.

played

number

Matches played.

points

number

Points accumulated.

Example

curl "https://api.futsalmanager.example/groups/1/teams"

POST /groups/:id/teams — assign a team to a group (admin)

Creates a team_stats row linking a team to a group and season. Returns 400 if the team is already in this group for the given season.Method: POST Path: /groups/:id/teams Auth: JWT + admin role required

Path parameters

number

required

Group ID.

Request body

team_id

number

required

Team to assign.

season_id

number

required

Season in which the assignment applies.

Response — `201 Created`

The created team_stats record.

Example

curl -X POST "https://api.futsalmanager.example/groups/1/teams" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"team_id": 7, "season_id": 3}'

DELETE /groups/:id/teams/:teamId — remove a team from a group (admin)

Removes a team’s assignment from a group in a given season by deleting the corresponding team_stats row.Method: DELETE Path: /groups/:id/teams/:teamId Auth: JWT + admin role required

Path parameters

number

required

Group ID.

teamId

number

required

Team ID to remove.

Query parameters

season_id

number

required

Season in which to remove the assignment. Required.

Response — `200 OK`

message

string

Confirmation message.

Example

curl -X DELETE "https://api.futsalmanager.example/groups/1/teams/7?season_id=3" \
  -H "Authorization: Bearer <token>"

Fields

GET /fields — list all fields

Returns all venue fields ordered alphabetically by name.Method: GET Path: /fields Auth: None

Response — `200 OK`

An array of field objects:

number

Field ID.

name

string

Field name.

location

string

Physical address or location description.

Example

curl "https://api.futsalmanager.example/fields"

Response

[
  { "id": 1, "name": "Pabellón Municipal Norte", "location": "Calle del Deporte 12, Madrid" },
  { "id": 2, "name": "Polideportivo Sur",        "location": "Avda. Olimpia 5, Madrid" }
]

POST /fields — create a field (admin)

Creates a new venue field.Method: POST Path: /fields Auth: JWT + admin role required

Request body

name

string

required

Field name.

location

string

Physical address or location description.

Response — `201 Created`

The created field record.

Example

curl -X POST "https://api.futsalmanager.example/fields" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Pabellón Este", "location": "Calle Deporte 3, Madrid"}'

PUT /fields/:id — update a field (admin)

Updates a field’s name or location.Method: PUT Path: /fields/:id Auth: JWT + admin role required

Path parameters

number

required

Field ID to update.

Request body

name

string

Updated field name.

location

string

Updated location.

Response — `200 OK`

The updated field record.

Example

curl -X PUT "https://api.futsalmanager.example/fields/1" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Pabellón Municipal Norte", "location": "Calle del Deporte 12, Madrid"}'

DELETE /fields/:id — delete a field (admin)

Permanently deletes a field. Returns an error if the field has associated matches.Method: DELETE Path: /fields/:id Auth: JWT + admin role required

Path parameters

number

required

Field ID to delete.

Response — `200 OK`

message

string

Confirmation message.

Example

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

Authentication

Matches

Teams & Players

Standings & Statistics

Admin

Documentation Index

​Seasons

​Response — 200 OK

​Example

​Response — 200 OK

​Example

​Request body

​Response — 201 Created

​Example

​Path parameters

​Request body

​Response — 200 OK

​Example

​Path parameters

​Response — 200 OK

​Example

​Path parameters

​Request body

​Response — 200 OK

​Example

​Groups

​Query parameters

​Response — 200 OK

​Example

​Request body

​Response — 201 Created

​Example

​Path parameters

​Request body

​Response — 200 OK

​Example

​Path parameters

​Response — 200 OK

​Example

​Path parameters

​Response — 200 OK

​Example

​Path parameters

​Request body

​Response — 201 Created

​Example

​Path parameters

​Query parameters

​Response — 200 OK

​Example

​Fields

​Response — 200 OK

​Example

​Request body

​Response — 201 Created

​Example

​Path parameters

​Request body

​Response — 200 OK

​Example

​Path parameters

​Response — 200 OK

​Example

Build docs developers (and LLMs) love

Seasons

Response — `200 OK`

Example

Response — `200 OK`

Example

Request body

Response — `201 Created`

Example

Path parameters

Request body

Response — `200 OK`

Example

Path parameters

Response — `200 OK`

Example

Path parameters

Request body

Response — `200 OK`

Example

Groups

Query parameters

Response — `200 OK`

Example

Request body

Response — `201 Created`

Example

Path parameters

Request body

Response — `200 OK`

Example

Path parameters

Response — `200 OK`

Example

Path parameters

Response — `200 OK`

Example

Path parameters

Request body

Response — `201 Created`

Example

Path parameters

Query parameters

Response — `200 OK`

Example

Fields

Response — `200 OK`

Example

Request body

Response — `201 Created`

Example

Path parameters

Request body

Response — `200 OK`

Example

Path parameters

Response — `200 OK`

Example