Admin API endpoints

All endpoints on this page require a valid JWT and the admin role. Requests that are unauthenticated or belong to a non-admin account receive 401 or 403 respectively.

GET /admin/summary

Returns headline counts for the admin dashboard and the five most recent audit log entries. Results can be scoped to a specific season.

season_id

number

When provided, totalTeams, totalPlayers, and pendingMatches are filtered to that season. totalUsers is always global. Audit logs are filtered to entries whose details reference the same season (entries with no season reference are included regardless).

Request
Response

cURL

curl "http://localhost:3000/admin/summary?season_id=3" \
  -H "Authorization: Bearer <token>"

{
  "stats": {
    "totalTeams": 8,
    "totalPlayers": 64,
    "pendingMatches": 12,
    "totalUsers": 150
  },
  "recentActivity": [
    {
      "id": 512,
      "user_id": 1,
      "action": "Finalización de partido",
      "entity": "match",
      "entity_id": 42,
      "details": { "home_goals": 3, "away_goals": 1, "season_id": "3" },
      "created_at": "2025-03-15T20:05:12.000Z",
      "username": "admin"
    }
  ]
}

Response fields

stats

object

Show properties

totalTeams

number

Number of teams active in the season (or globally when no season filter is applied).

totalPlayers

number

Number of distinct players registered in the season (or all active players globally).

pendingMatches

number

Number of matches with status pendiente.

totalUsers

number

Total registered user accounts (always global).

recentActivity

object[]

Five most recent audit log entries.

Show log entry properties

number

Log entry identifier.

user_id

number

Identifier of the user who performed the action.

username

string

Username of the actor.

action

string

Human-readable description of the action (e.g. Finalización de partido).

entity

string

Type of entity affected (e.g. match, team, player, season, user).

entity_id

number

Identifier of the affected entity.

details

object

Arbitrary JSON object with additional context for the action.

created_at

string

ISO 8601 timestamp of when the action was performed.

GET /admin/active-season

Returns the currently active season. Useful for initialising admin views that must always operate in the context of the live season.

Request
Response

cURL

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

{
  "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 /admin/upload

Uploads an image to Cloudinary. The server processes the file with Sharp before uploading. Send the image as a multipart/form-data request using the field name image.

folder

string

default:"general"

Cloudinary folder to upload the image into (e.g. teams, players).

filename

string

Custom public ID to use in Cloudinary. When omitted, a generated ID is used.

The request body must be multipart/form-data containing a field named image with the binary file data.

Request
Response

cURL

curl -X POST "http://localhost:3000/admin/upload?folder=teams&filename=rayo_vallecas_logo" \
  -H "Authorization: Bearer <token>" \
  -F "image=@/path/to/logo.png"

{ "url": "https://res.cloudinary.com/dyxl1d54d/image/upload/v1741034412/tfg_futsal/teams/rayo_vallecas_logo.webp" }

url

string

Public Cloudinary URL of the uploaded image.

The server converts images to WebP format via Sharp before uploading. The original file format does not affect the output URL extension.

GET /admin/users

Returns a paginated, searchable list of active user accounts.

string

Case-insensitive, accent-insensitive filter applied to both username and email.

page

number

default:"1"

Page number.

limit

number

default:"10"

Results per page.

Request
Response

cURL

curl "http://localhost:3000/admin/users?search=ana&page=1&limit=10" \
  -H "Authorization: Bearer <token>"

{
  "users": [
    {
      "id": 101,
      "username": "ana_garcia",
      "email": "[email protected]",
      "role": "user",
      "created_at": "2024-10-01T10:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 10
}

users

object[]

Show user properties

number

User identifier.

username

string

Username.

string

Email address.

role

string

Account role: user, referee, or admin.

created_at

string

Account creation timestamp (ISO 8601).

total

number

Total matching active accounts.

page

number

Current page.

limit

number

Results per page.

PUT /admin/users/:id

Changes the role of a user account.

number

required

User identifier.

role

string

required

New role. One of user, referee, or admin.

Request
Response

cURL

curl -X PUT http://localhost:3000/admin/users/101 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"role": "referee"}'

{
  "message": "Usuario actualizado correctamente",
  "user": { "id": 101, "username": "ana_garcia", "role": "referee" }
}

message

string

Confirmation message.

user

object

Show properties

number

User identifier.

username

string

Username.

role

string

Updated role.

DELETE /admin/users/:id

Deactivates a user account and anonymises its username and email by appending a deletion timestamp. The account is set to is_active = false and cannot be recovered through the API.

number

required

User identifier.

Request
Response

cURL

curl -X DELETE http://localhost:3000/admin/users/101 \
  -H "Authorization: Bearer <token>"

{ "message": "Usuario desactivado y anonimizado correctamente" }

This action anonymises the user’s personal data. It cannot be undone through the API.

GET /admin/logs

Returns paginated audit logs with optional filters. Logs record every significant admin or referee action in the system.

page

number

default:"1"

Page number.

limit

number

default:"20"

Results per page.

season_id

number

Filter to logs referencing this season (entries with no season in their details are still included).

username

string

Filter by actor username (accent-insensitive partial match).

date

string

Filter to logs created on a specific date (ISO 8601 date, e.g. 2025-03-15).

Request
Response

cURL

curl "http://localhost:3000/admin/logs?season_id=3&page=1&limit=20" \
  -H "Authorization: Bearer <token>"

{
  "logs": [
    {
      "id": 512,
      "user_id": 1,
      "username": "admin",
      "action": "Finalización de partido",
      "entity": "match",
      "entity_id": 42,
      "details": { "home_goals": 3, "away_goals": 1, "season_id": "3" },
      "created_at": "2025-03-15T20:05:12.000Z"
    }
  ],
  "total": 148,
  "page": 1,
  "limit": 20
}

logs

object[]

Show log entry properties

number

Log entry identifier.

user_id

number

Identifier of the acting user.

username

string

Username of the actor.

action

string

Description of the action performed.

entity

string

Type of entity affected (match, team, player, season, group, field, user).

entity_id

number

Identifier of the affected entity.

details

object

Arbitrary JSON with additional context (e.g. goal counts, season references).

created_at

string

ISO 8601 timestamp.

total

number

Total matching log entries.

page

number

Current page.

limit

number

Results per page.

Overview

Endpoints

GET /admin/summary

Response fields

GET /admin/active-season

POST /admin/upload

GET /admin/users

PUT /admin/users/:id

DELETE /admin/users/:id

GET /admin/logs

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /admin/summary

​Response fields

​GET /admin/active-season

​POST /admin/upload

​GET /admin/users

​PUT /admin/users/:id

​DELETE /admin/users/:id

​GET /admin/logs

Build docs developers (and LLMs) love

GET /admin/summary

Response fields

GET /admin/active-season

POST /admin/upload

GET /admin/users

PUT /admin/users/:id

DELETE /admin/users/:id

GET /admin/logs