# VitFit V2 — API Routes All routes prefixed `/api/v1/`. Auth header: `Authorization: Bearer `. Response envelopes: see `API_STANDARDS.md`. Dates: ISO 8601 UTC strings. Legend: `[T]` = requires authenticateToken `[O]` = Owner+ `[SA]` = SystemAdmin only `[F:x]` = requires feature flag --- ## Auth — /api/v1/auth ### POST /api/v1/auth/login No auth required. Request: ```json { "username": "coach1", "password": "secret", "rememberDevice": true, "deviceName": "Gym iPad", "deviceType": "kiosk" } ``` `rememberDevice`, `deviceName`, `deviceType` are optional (default: no device token). Response 200: ```json { "data": { "jwt": "eyJ...", "deviceToken": "a3f9...", "user": { "id": 1, "username": "coach1", "role": "Coach", "firstName": "Jason", "organizationId": 1 } } } ``` `deviceToken` only present when `rememberDevice: true`. Store in localStorage as `deviceToken`. Errors: `LOGIN_FAILED` (401), rate-limited after 10 attempts/15 min (429). Two independent rate limits apply: - **Per-IP** — `express-rate-limit` middleware, 10 req/15 min per source IP. - **Per-username** — tracked in process memory by auth service. 10 failed attempts for the same `username` string within 15 minutes triggers immediate `LOGIN_FAILED` regardless of IP. Resets automatically on success or after 15 minutes. Prevents targeted account brute-force from rotating IPs. --- ### POST /api/v1/auth/device-login No auth required. Used on page load to silently re-authenticate. Request: ```json { "deviceToken": "a3f9..." } ``` Response 200: ```json { "data": { "jwt": "eyJ...", "deviceToken": "b7e2...", "user": { "id": 1, "username": "coach1", "role": "Coach", "organizationId": 1 } } } ``` Old token is invalidated. New token replaces it in localStorage. Errors: `AUTH_DEVICE_TOKEN_INVALID` (401). Rate limited: same 10 req/15 min per-IP limiter as `/auth/login`. The token search space (32-byte random = 2²⁵⁶) makes brute force computationally infeasible; rate limiting prevents server load abuse and probing. --- ### POST /api/v1/auth/refresh-token `[T]` No request body. Called by `core.js` when token is within 1 hour of expiry. Response 200: ```json { "data": { "jwt": "eyJ..." } } ``` --- ### POST /api/v1/auth/logout `[T]` No request body. Logs audit event. JWT invalidation is client-side (delete from localStorage). Response 204. --- ## Users — /api/v1/users ### GET /api/v1/users `[T]` `[O]` Query: `?role=Coach&isActive=true&page=1&limit=50` Response 200 (collection): ```json { "data": [ { "id": 2, "username": "jsmith", "email": "j@gym.com", "firstName": "John", "lastName": "Smith", "role": "Coach", "isActive": true, "lastLoginAt": "2025-06-10T14:22:00.000Z" } ], "meta": { "total": 4, "page": 1, "limit": 50, "totalPages": 1 } } ``` --- ### POST /api/v1/users `[T]` `[O]` Request: ```json { "username": "newcoach", "email": "coach@gym.com", "firstName": "Mike", "lastName": "Jones", "password": "initialPass123", "role": "Coach" } ``` `email`, `firstName`, `lastName` optional. `role` must be `Owner`, `Coach`, or `Client`. Response 201: `{ "data": { ...user } }` Errors: `CONFLICT` (409 duplicate username), `VALIDATION_FAILED` (400). --- ### GET /api/v1/users/:id `[T]` `[O]` Response 200: `{ "data": { ...user, deviceTokens: [ { id, deviceName, deviceType, lastUsedAt, expiresAt } ] } }` Errors: `NOT_FOUND` (404). --- ### PATCH /api/v1/users/:id `[T]` Own profile only (any role) OR `[O]` for any user in org. Request (any subset): ```json { "firstName": "Jason", "lastName": "A", "email": "new@email.com" } ``` Response 200: `{ "data": { ...updatedUser } }` --- ### DELETE /api/v1/users/:id `[T]` `[O]` Soft deactivate. Not a true delete. Response 204. Errors: `LAST_OWNER_PROTECTED` (400), `NOT_FOUND` (404). --- ### PUT /api/v1/users/:id/role `[T]` `[O]` Request: `{ "role": "Owner" }` Response 200: `{ "data": { ...user } }` Errors: `LAST_OWNER_PROTECTED` (400), `AUTH_FORBIDDEN` (403 if Owner tries to self-change). --- ### PUT /api/v1/users/:id/password `[T]` `[O]` Request: `{ "newPassword": "newPass456" }` Response 204. --- ### GET /api/v1/users/:id/devices `[T]` Own devices (any role) OR `[O]` for any user in org. Response 200: ```json { "data": [ { "id": 3, "deviceName": "Gym iPad", "deviceType": "kiosk", "lastUsedAt": "2025-06-11T08:00:00.000Z", "expiresAt": "2025-09-09T08:00:00.000Z" } ] } ``` Token hash is never returned. --- ### DELETE /api/v1/users/:id/devices/:tokenId `[T]` Own devices (any role) OR `[O]`. Response 204. --- ## Organization — /api/v1/org ### GET /api/v1/org `[T]` Response 200: ```json { "data": { "id": 1, "name": "CrossFit Downtown", "slug": "crossfit-downtown", "timezone": "America/New_York", "features": ["client-management", "calendar"], "licenseOwner": "Jason A", "licenseEmail": "jason@gym.com" } } ``` --- ### PATCH /api/v1/org `[T]` `[O]` Request (any subset): `{ "name": "CrossFit Uptown", "timezone": "America/Chicago" }` Response 200: `{ "data": { ...org } }` Errors: `VALIDATION_FAILED` (400 invalid timezone). --- ### GET /api/v1/org/branding `[T]` Response 200: ```json { "data": { "appName": "CrossFit Downtown", "logoPath": "/api/v1/org/logo", "primaryColor": "#00FF88", "secondaryColor": "#4488FF", "workColor": "#00FF88", "restColor": "#4488FF", "moveColor": "#FF4444" } } ``` `logoPath` is `null` if no custom logo. --- ### PATCH /api/v1/org/branding `[T]` `[O]` Request (any subset): ```json { "appName": "My Gym", "primaryColor": "#FF0066", "workColor": "#FF0066" } ``` Response 200: `{ "data": { ...branding } }` Errors: `VALIDATION_FAILED` (400, lists each color that fails contrast check). --- ### POST /api/v1/org/logo `[T]` `[O]` Body: `multipart/form-data`, field `logo` (image file). Response 200: `{ "data": { "logoPath": "/api/v1/org/logo" } }` --- ### GET /api/v1/org/logo `[T]` Streams logo file. Returns 404 if no custom logo set. --- ## Videos — /api/v1/videos ### GET /api/v1/videos `[T]` Coaches and above. Query: `?category=Arm+Exercises&page=1&limit=50` Response 200 (collection): ```json { "data": [ { "id": 5, "filename": "1718000000_abc123.mp4", "description": "Barbell curl", "category": "Arm Exercises", "mimeType": "video/mp4", "fileSizeBytes": 45020000, "createdAt": "2025-06-01T12:00:00.000Z", "streamUrl": "/api/v1/videos/stream/1718000000_abc123.mp4" } ], "meta": { ... } } ``` `streamUrl` is included so the frontend doesn't need to construct URLs. --- ### POST /api/v1/videos `[T]` Coach+. Body: `multipart/form-data`. Fields: `video` (file), `description` (string), `category` (string). Pre-upload middleware: `checkUploadAllowed` (507 if disk low), multer file size limit. Response 201: `{ "data": { ...video, streamUrl } }` Errors: `UPLOAD_TYPE_INVALID` (400), `UPLOAD_SIZE_EXCEEDED` (400), `STORAGE_INSUFFICIENT` (507). --- ### DELETE /api/v1/videos/:id `[T]` Coach+. Response 204. Errors: `NOT_FOUND` (404). --- ### GET /api/v1/videos/stream/:filename `[T]` Streams video file. Supports `Range` header for seek (required by Safari). Response 200 (full) or 206 (partial/range). Headers include `Accept-Ranges: bytes`, `Content-Type` from stored mimeType. Errors: `NOT_FOUND` (404 — file not in DB for this org, or doesn't exist on disk). --- ### GET /api/v1/categories `[T]` Coach+. Response 200: `{ "data": [ { "id": 1, "name": "Arm Exercises" }, ... ] }` --- ### POST /api/v1/categories `[T]` Coach+. Request: `{ "name": "Mobility" }` Response 201: `{ "data": { "id": 7, "name": "Mobility" } }` Errors: `CONFLICT` (409). --- ### DELETE /api/v1/categories/:id `[T]` Coach+. Response 204. Errors: `CONFLICT` (409 if videos exist in this category), `NOT_FOUND` (404). --- ## Workouts (Group Display) — /api/v1/workouts ### GET /api/v1/workouts `[T]` Coach+. Query: `?page=1&limit=20` Response 200 (collection): ```json { "data": [ { "id": 10, "name": "Tuesday WOD", "workoutDate": "2025-06-11T00:00:00.000Z", "createdByUserId": 2, "videos": [ { "slot": 1, "video": { "id": 5, "description": "Barbell curl", "streamUrl": "..." }, "reps": 10 }, { "slot": 2, "video": null, "reps": null } ] } ], "meta": { ... } } ``` `video: null` when the referenced video has been deleted. --- ### POST /api/v1/workouts `[T]` Coach+. Request: ```json { "name": "Tuesday WOD", "workoutDate": "2025-06-11T00:00:00.000Z", "video1": 5, "number1": 10, "video2": 8, "number2": 12, "video3": null, "number3": null, "video4": null, "number4": null } ``` Response 201: `{ "data": { ...workout with videos } }` Errors: `VALIDATION_FAILED` (400, video IDs not in org). --- ### GET /api/v1/workouts/today `[T]` Coach+. No query params. Uses org timezone for "today" calculation. Response 200 (collection — same shape as GET /workouts). --- ### GET /api/v1/workouts/:id `[T]` Coach+. Response 200: `{ "data": { ...workout with videos } }` --- ### DELETE /api/v1/workouts/:id `[T]` Coach (own only) or Owner (any). Response 204. Errors: `AUTH_FORBIDDEN` (403 if Coach tries to delete another's workout), `NOT_FOUND` (404). --- ## Timers — /api/v1/timers ### GET /api/v1/timers `[T]` Coach+. Response 200 (collection): ```json { "data": [ { "id": 3, "name": "HIIT 30/10", "totalTime": 1800, "setTime": 30, "restTime": 10, "moveTime": 15, "setCount": 3, "exerciseCount": 5, "lapCount": 2 } ], "meta": { ... } } ``` --- ### POST /api/v1/timers `[T]` Coach+. Request: ```json { "name": "HIIT 30/10", "totalTime": 1800, "setTime": 30, "restTime": 10, "moveTime": 15, "setCount": 3, "exerciseCount": 5, "lapCount": 2 } ``` Response 201: `{ "data": { ...timer } }` --- ### GET /api/v1/timers/:id `[T]` Coach+. Response 200: `{ "data": { ...timer } }` --- ### DELETE /api/v1/timers/:id `[T]` Coach (own) or Owner. Response 204. --- ### POST /api/v1/timers/:id/launch `[T]` Coach+. No request body. Response 200: ```json { "data": { "sessionId": "timer_3_1718273400000" } } ``` Client uses `sessionId` to join the Socket.io room. --- ### DELETE /api/v1/timers/session `[T]` Coach+. Request: `{ "sessionId": "timer_3_1718273400000" }` Stops the active timer session. Response 204. --- ## CrossFit Workouts — /api/v1/crossfit-workouts ### GET /api/v1/crossfit-workouts `[T]` Coach+. Query: `?page=1&limit=20` Response 200 (collection): ```json { "data": [ { "id": 7, "name": "Hero WOD Murph", "workoutDate": "2025-06-11T00:00:00.000Z", "workoutItems": ["1 mile run", "100 pull-ups", "200 push-ups", "300 squats", "1 mile run"], "createdByUserId": 2 } ], "meta": { ... } } ``` --- ### POST /api/v1/crossfit-workouts `[T]` Coach+. Request: ```json { "name": "Hero WOD Murph", "workoutDate": "2025-06-11T00:00:00.000Z", "workoutItems": ["1 mile run", "100 pull-ups", "200 push-ups"] } ``` Response 201: `{ "data": { ...crossfitWorkout } }` --- ### GET /api/v1/crossfit-workouts/:id `[T]` Coach+. Response 200: `{ "data": { ...crossfitWorkout } }` --- ### DELETE /api/v1/crossfit-workouts/:id `[T]` `[O]` Response 204. --- ## Clients — /api/v1/clients `[F:client-management]` All client endpoints require this feature flag. ### GET /api/v1/clients `[T]` Coach (own clients) or Owner (all). Response 200 (collection): ```json { "data": [ { "id": 9, "username": "athlete1", "firstName": "Sara", "lastName": "Kim", "email": "sara@email.com", "isActive": true, "coach": { "id": 2, "firstName": "John", "lastName": "Smith" } } ], "meta": { ... } } ``` --- ### POST /api/v1/clients `[T]` `[O]` or Coach if org allows self-assign. Creates a new Client user and optionally assigns a coach. Request: ```json { "username": "athlete2", "firstName": "Tom", "lastName": "Brady", "email": "tom@email.com", "password": "initialPass", "coachId": 2 } ``` `coachId` optional. Response 201: `{ "data": { ...user, coachLink? } }` --- ### GET /api/v1/clients/:id `[T]` Coach (own clients only) or Owner. Response 200: ```json { "data": { "id": 9, "username": "athlete1", "firstName": "Sara", "lastName": "Kim", "coach": { "id": 2, "firstName": "John" }, "upcomingSessionsCount": 3, "pendingWorkoutsCount": 2 } } ``` --- ### POST /api/v1/clients/:id/assign `[T]` `[O]` Request: `{ "coachId": 3 }` Response 200: `{ "data": { "linkId": 14, "coachId": 3, "clientId": 9, "assignedAt": "..." } }` --- ### DELETE /api/v1/clients/:id/assign `[T]` `[O]` Request: `{ "linkId": 14 }` Response 204. --- ### GET /api/v1/clients/:id/workouts `[T]` Coach (own clients) or Client (own) or Owner. Query: `?page=1&limit=20&includeCompleted=false` Response 200 (collection): ```json { "data": [ { "id": 22, "name": "Monday Strength", "scheduledDate": "2025-06-12T00:00:00.000Z", "completedAt": null, "coachId": 2, "items": [ { "type": "video", "videoId": 5, "reps": 10, "sets": 3, "notes": "Full ROM", "streamUrl": "/api/v1/videos/stream/..." }, { "type": "text", "text": "Rest 2 min between sets" } ] } ], "meta": { ... } } ``` --- ### POST /api/v1/clients/:id/workouts `[T]` Coach (own clients only). Request: ```json { "name": "Monday Strength", "scheduledDate": "2025-06-12T00:00:00.000Z", "notes": "Focus on form today.", "items": [ { "type": "video", "videoId": 5, "reps": 10, "sets": 3, "notes": "Full ROM" }, { "type": "text", "text": "Rest 2 min" } ] } ``` Response 201: `{ "data": { ...clientWorkout } }` --- ### GET /api/v1/clients/:id/workouts/:workoutId `[T]` Coach (own clients) or Client (own) or Owner. Response 200: `{ "data": { ...clientWorkout with items } }` --- ### PATCH /api/v1/clients/:id/workouts/:workoutId `[T]` Coach (own clients only). Request: any subset of `{ name, scheduledDate, notes, items }`. Response 200: `{ "data": { ...updated } }` --- ### DELETE /api/v1/clients/:id/workouts/:workoutId `[T]` Coach (own clients only). Soft delete. Response 204. --- ### POST /api/v1/clients/:id/workouts/:workoutId/complete `[T]` Coach (own clients) or Client (own). No request body. Response 200: `{ "data": { "completedAt": "2025-06-12T09:30:00.000Z" } }` --- ### GET /api/v1/clients/:id/sessions `[T]` Coach (own clients) or Client (own) or Owner. Query: `?startAfter=2025-06-01&endBefore=2025-06-30&status=Scheduled&page=1&limit=20` Response 200 (collection): ```json { "data": [ { "id": 31, "title": "Weekly Check-in", "sessionType": "Personal", "startAt": "2025-06-12T09:00:00.000Z", "endAt": "2025-06-12T10:00:00.000Z", "status": "Scheduled", "locationNotes": "Gym Floor B", "sharedNotes": "Bring your training log", "linkedWorkoutId": 22 } ], "meta": { ... } } ``` `coachNotes` is stripped when requester is the Client. --- ### POST /api/v1/clients/:id/sessions `[T]` Coach (own clients). Request: ```json { "title": "Weekly Check-in", "sessionType": "personal", "startAt": "2025-06-12T09:00:00.000Z", "endAt": "2025-06-12T10:00:00.000Z", "locationNotes": "Gym Floor B", "coachNotes": "Client struggling with squat depth", "sharedNotes": "Bring your training log", "linkedWorkoutId": 22 } ``` Response 201: `{ "data": { ...session } }` --- ### PATCH /api/v1/clients/:id/sessions/:sessionId `[T]` Coach (own) or Client (limited fields only). Response 200: `{ "data": { ...updated } }` --- ### POST /api/v1/clients/:id/sessions/:sessionId/cancel `[T]` Coach or Client. Response 200: `{ "data": { "status": "Cancelled" } }` Errors: `CANCELLATION_TOO_LATE` (400) — Client attempting to cancel a session that starts in less than 24 hours. Coaches and Owners are not subject to this restriction. --- ## My (Client Self-Service) — /api/v1/my ### GET /api/v1/my/workouts `[T]` Client role only. Alias for `GET /api/v1/clients/:ownId/workouts` scoped to the requesting client. Response: same collection shape as client workouts. --- ### GET /api/v1/my/sessions `[T]` Client role only. Alias for `GET /api/v1/clients/:ownId/sessions`. --- ### GET /api/v1/my/profile `[T]` Any role. Returns own user record. Alias for `GET /api/v1/users/:ownId`. --- ### PUT /api/v1/my/password `[T]` Any role. Allows any authenticated user to change their own password after verifying the current one. Owner-managed `PUT /api/v1/users/:id/password` does not require the current password; this endpoint does. Request: ```json { "currentPassword": "oldPass123", "newPassword": "newPass456" } ``` Response 204. Errors: `AUTH_FORBIDDEN` (401 if `currentPassword` does not match stored hash), `VALIDATION_FAILED` (400). --- ## Calendar (Coach View) — /api/v1/calendar ### GET /api/v1/calendar `[T]` Coach+. `[F:calendar]` Query: `?startAfter=2025-06-01&endBefore=2025-06-30` Returns all sessions for the coach across all their clients, aggregated. Response 200 (collection of CalendarSession). **Phase 2 deferrals:** Conflict detection (overlapping sessions for same coach) and recurring sessions (RRULE / weekly repeat) are not implemented in V2 MVP. Every session is a standalone record. The API accepts overlapping bookings without error. --- ## Admin — /api/v1/admin ### GET /api/v1/admin/storage `[T]` `[O]` Response 200: ```json { "data": { "disk": { "total": 53687091200, "used": 21474836480, "free": 32212254720, "usedPercent": 40 }, "uploads": { "size": 4831838208, "fileCount": 47 }, "warning": false, "warnThresholdBytes": 5368709120 } } ``` --- ## Audit Logs — /api/v1/audit-logs ### GET /api/v1/audit-logs `[T]` `[O]` Query: `?action=video.upload&userId=2&entityType=video&from=2025-06-01&to=2025-06-30&page=1&limit=50` Response 200 (collection): ```json { "data": [ { "id": 204, "userId": 2, "userRole": "Coach", "action": "video.upload", "entityType": "video", "entityId": 15, "details": { "filename": "1718...", "category": "Arm Exercises", "fileSizeBytes": 45020000 }, "ipAddress": "192.168.1.5", "createdAt": "2025-06-11T14:23:00.000Z" } ], "meta": { ... } } ``` --- ### GET /api/v1/audit-logs/export `[T]` `[O]` Same query params as GET. Returns CSV stream. Response headers: ``` Content-Type: text/csv Content-Disposition: attachment; filename="audit-log-2025-06-11.csv" ``` --- ## System Admin — /api/v1/sysadmin ### GET /api/v1/sysadmin/orgs `[T]` `[SA]` Response 200: All organizations with user count summary. --- ### GET /api/v1/sysadmin/orgs/:id `[T]` `[SA]` Response 200: Full org detail, branding, user list. --- ### PATCH /api/v1/sysadmin/orgs/:id `[T]` `[SA]` Request: any subset of `{ name, timezone, features, isActive, licenseOwner, licenseEmail }`. Response 200: `{ "data": { ...org } }` --- ### GET /api/v1/sysadmin/health `[T]` `[SA]` Response 200: ```json { "data": { "status": "ok", "version": "1.0.0", "nodeVersion": "v20.11.0", "uptime": 86423, "db": { "status": "ok", "lastMigration": "005-add-video-mime-type" }, "disk": { "free": 32212254720, "usedPercent": 40 }, "activeTimerSessions": 0, "orgCount": 1 } } ``` --- ## Health (No Auth) ### GET /health Response 200: ```json { "status": "ok", "version": "1.0.0", "uptime": 86423, "db": "ok", "diskAvailableGB": 30.0, "diskWarnActive": false } ``` Returns `"status": "degraded"` (still HTTP 200) if DB unreachable or disk in warning state. --- ## OpenAPI Spec ### GET /api/v1/openapi.yaml No auth required. Returns the OpenAPI 3.0 spec for this API as a YAML file. Generated from code comments or a hand-maintained `openapi.yaml` in the project root. Response headers: ``` Content-Type: application/yaml ``` This endpoint is mentioned in `API_STANDARDS.md` as the authoritative spec location.