API reference

Base URL and response format

Every route is served under the /api prefix. Locally the base URL is http://localhost:8000/api. On a server it is your API's address followed by /api, the same value the dashboard reads from NEXT_PUBLIC_API_BASE_URL (Environment variables).

Members and staff use the same sign-in and the same token; the roles on the account decide which routes answer. Request bodies are JSON, except file uploads. Every answer comes in the same envelope:

{
  "success": true,
  "data": { },
  "message": ""
}

data holds the result. message is a short sentence some writes fill in, translated to the request's language, and empty otherwise.

The health check is the one route outside the envelope. It needs no token and is not rate limited:

curl http://localhost:8000/api/health

{"status":"ok"}

It answers 503 with {"status":"unavailable"} while the database cannot be reached or holds no tables, so a platform can use it as a readiness probe.

Errors

A failed request answers with the matching HTTP status and the same envelope, with success: false, data: null, and for validation the problems per field:

{
  "success": false,
  "data": null,
  "message": "<the first field's problem>",
  "errors": {
    "email": ["<the problem with email>"]
  }
}

Many errors carry a key the dashboard translates, such as member_not_found or event_full, in message.

Pagination

Lists take page, from 1, and page_count, the page size. A page holds at most 100 rows: a larger size is read as 100, a smaller one as 1, and a missing or unreadable one falls back to the list's default. A list answers in one shape:

{
  "success": true,
  "data": { "data": [ ], "page": 1, "limit": 15, "total": 35, "totalPages": 3 },
  "message": ""
}

The content lists sort by updated_at, newest first by default (order=asc or desc), with the id as a tiebreaker, and take search and their own filters.

Language

Send the reader's language in the Accept-Language header: en or ar as shipped. ar-SA counts as Arabic, and any language the API does not have is answered in English. Error messages and the message of a successful write are translated; content stored in both languages comes back as { "en": "...", "ar": "..." }.

Authentication

• Sign in at POST /api/auth/login. The answer holds access_token, a JWT signed with JWT_SECRET, and the account with its roles and permissions. Send it as Authorization: Bearer <token>.
• A token lasts for JWT_EXPIRATION, 7d by default. There is no refresh route: when a token expires, the next request answers 401 and the client signs in again.
• Sign-in, registration and account deletion accept 10 attempts a minute from one address, counted per route, then answer 429. The count is kept in the API's memory, so it starts again on a restart. Behind a proxy, see TRUST_PROXY (Troubleshooting).

1. 01

   Sign in as the seeded Head Coach

   TerminalCopy

   curl -X POST http://localhost:8000/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"headcoach@example.com","password":"Coach@123"}'

   ResponseCopy

   {
     "success": true,
     "data": {
       "access_token": "eyJhbGciOiJIUzI1NiIs...",
       "token_type": "Bearer",
       "expires_in": "7d",
       "account": { "email": "headcoach@example.com", "roles": [ ], "permissions": [ ] }
     },
     "message": "..."
   }
2. 02

   Call a protected route with the token

   TerminalCopy

   curl "http://localhost:8000/api/users?page=1&page_count=5" \
     -H "Authorization: Bearer <access_token>"

   Expected result: The first five members, in the list shape.

There is no password-reset route. The dashboard's forgot-password and reset-password pages are the screens only: no reset is sent. A staff account with members.update sets a member's password with PATCH /api/users/:username/change-password.

Permissions

A route checks the token first, then the permission it names. An account holds every permission of every role it has; where a route names several, any one is enough. In the tables below, a permission name in Who can call it means an account whose roles grant it.

• The roles and their permissions

Members

Coaches and roles

App settings

A member's own data

Every route here answers for the account on the token and nobody else. A staff token answers 403, because only the Member role holds fitness.view and fitness.edit. Each write answers with the whole refreshed page.

• Progress and logging
• Devices and ingest keys

Workouts, exercises and the session

Coaching

The roster routes answer for the coach making the request: another coach's client is a 404.

The content catalogues

Each catalogue answers the same five routes under /api/fitness/manage/<catalogue>, and every one needs fitness.manage. The catalogues are exercises, workouts, programs, dishes, groups, events, challenges, achievements and badges.

An unknown id is 404 record_not_found. Names and texts are sent as { "en": "…", "ar": "…" }; a dish's calories are never sent, they are worked out from its grams.

Ingest

The door for devices and aggregators. These routes take an ingest key in X-Api-Key, never a bearer token, and write for the key's account only.

• Devices and ingest keys

Search, uploads, notifications and countries

Two Socket.IO namespaces on the same server push live updates: /notifications delivers each new notification, and /auth tells a signed-in dashboard that its permissions changed. They accept the origins in FRONTEND_URL, or CORS_ORIGIN when it is unset.

• How search ranks its hits

AI assistant

MCP server

Demo mode routes