This is the mobile-app API (per-user Clerk session). The system-to-system integration API (API keys per organization,
/api/integration/v1) is a separate API: seeintegration-api/.
Base URL: https://<your-domain>/api/v1
Authentication
All endpoints require a Clerk JWT token sent as a Bearer token:
Authorization: Bearer <clerk-jwt-token>The token does not need an active organization: the account is resolved by its Clerk user id (User.clerkUserId is unique). Instructors never join the Clerk Organization — they link their Clerk account to their instructor profile with an invite code (POST /api/v1/me/claim).
Conventions
- Day of week:
0 = Monday, 1 = Tuesday, ..., 6 = Sunday - Time format:
"HH:MM"(24h) - Roles:
instructor,manager,owner,super_admin
Endpoints
GET /api/v1/me
Returns the authenticated user's profile and accessible clubs.
Response 200:
{
"user": {
"name": "Juan Garcia",
"email": "juan@gym.com",
"role": "instructor",
"instructorId": "cuid_xxx",
"imageUrl": "https://..."
},
"gym": { "name": "FitZone", "logo": null, "timezone": "Europe/Madrid" },
"clubs": [
{ "id": "cuid_xxx", "slug": "fitzoneretiro", "name": "FitZone Retiro" }
]
}| Field | Type | Notes |
|---|---|---|
user.name | string | The linked instructor profile's name when there is one (same name the rest of the app shows in schedules and team); otherwise the Clerk account's first + last name (may be empty) |
user.role | string | One of: instructor, manager, owner, super_admin |
user.instructorId | string | null | Only set if user is linked to an instructor profile |
clubs | array | Clubs the user has access to (owners see all clubs) |
Errors: 401 UNAUTHENTICATED (no session) · 403 NO_ACCOUNT (valid Clerk session with no active account yet — the app must ask for the invite code and call POST /api/v1/me/claim). A user whose gym has been deactivated by the platform admin also gets 403 NO_ACCOUNT: the app shows the same no-access screen.
POST /api/v1/me/claim
Links the current Clerk session (an account just created in the app) to the instructor profile the invite code was issued for. Creates the User (or reactivates a deactivated one) and its club membership. Idempotent: an already-linked active account gets its profile back regardless of the code. If the account's primary email equals the invited email and is still unverified, the code counts as verification and the address is marked verified in Clerk (best-effort).
Body: { "code": "ABCD-EFGH" } — 8 characters, case-insensitive, dashes/spaces ignored.
Response 200: same shape as GET /api/v1/me plus
{ "claimed": { "instructorName": "Juan Garcia", "clubName": "FitZone Retiro", "gymName": "FitZone" } }for the identity confirmation screen ("Eres Juan Garcia, monitor de FitZone Retiro").
Errors ({ "error", "code" }):
| Status | code | Cause |
|---|---|---|
| 401 | UNAUTHENTICATED | No Clerk session |
| 400 | INVALID_CODE | Malformed code |
| 404 | INVALID_CODE | No invite matches |
| 410 | CODE_EXPIRED / CODE_ALREADY_USED / CODE_REVOKED | Invite no longer valid (ask the manager to resend) |
| 409 | INSTRUCTOR_TAKEN | Another account claimed the profile first |
| 429 | RATE_LIMITED | 10 failed attempts in the last hour for this Clerk account |
DELETE /api/v1/me
"No soy yo": unlinks the instructor account that was just claimed — deactivates the User, revokes the invite it consumed and deletes its push tokens. Instructor accounts only (403 FORBIDDEN otherwise). The app signs out afterwards.
Response 200: { "ok": true }
GET /api/v1/clubs/{clubSlug}/schedule
Returns the weekly schedule for a club. Instructors only see their own assignments.
Query parameters:
| Param | Type | Default | Description |
|---|---|---|---|
week | string | Current week | ISO date of Monday (YYYY-MM-DD) |
Response 200:
{
"instructors": [
{
"id": "cuid_xxx",
"name": "Juan Garcia",
"color": "#3b82f6",
"contractHours": {
"reception": 10,
"class1h": 15,
"class30min": 5,
"manager": 0,
"reinforcement": 0
}
}
],
"assignments": [
{
"id": "cuid_xxx",
"instructorId": "cuid_xxx",
"instructorName": "Juan Garcia",
"classTypeId": "cuid_xxx",
"classTypeName": "Spinning",
"color": "#ef4444",
"dayOfWeek": 0,
"startTime": "09:00",
"endTime": "10:00",
"role": "class",
"durationMinutes": 60,
"roomName": "Sala Spinning",
"source": "template",
"type": "class",
"week": null,
"officialAssignmentId": null,
"status": "confirmed",
"needsReview": false
}
],
"activities": [
{
"id": "cuid_xxx",
"classTypeName": "Spinning",
"classTypeId": "cuid_xxx",
"color": "#ef4444",
"roomName": "Sala Spinning",
"roomId": "cuid_xxx",
"dayOfWeek": 0,
"startTime": "09:00",
"endTime": "10:00",
"durationMinutes": 60,
"instructorName": null
}
],
"dayStates": {
"0": {
"isClosed": false,
"hasSnapshot": false,
"isHoliday": false,
"gymHours": { "open": "07:00", "close": "22:00" }
}
},
"templateName": "Horario Oficial",
"absences": [
{ "instructorId": "cuid_xxx", "type": "vacation", "dayOfWeek": 2 }
]
}Assignment roles: class, reception, manager, training, other
Assignment sources: template (from official/active schedule), snapshot (week-specific override)
GET /api/v1/me/absences
Lists the instructor's own absences (last 365 days and future), including pending requests made from the app. Non-instructor accounts get an empty list.
Response 200:
{
"absences": [
{
"id": "cuid_xxx",
"type": "VACATION",
"status": "PENDING",
"startDate": "2026-08-10",
"endDate": "2026-08-14",
"notes": null,
"createdAt": "2026-07-01T10:00:00.000Z"
}
]
}| Field | Values |
|---|---|
type | VACATION, SICK_LEAVE, PERSONAL, OTHER |
status | PENDING (awaiting the manager), APPROVED, REJECTED |
POST /api/v1/me/absences
Creates a PENDING absence request. The manager approves or rejects it from the web (the instructor gets a push notification either way).
Body: { "type": "VACATION", "startDate": "2026-08-10", "endDate": "2026-08-14", "notes": "optional" }
Rules: dates YYYY-MM-DD, endDate >= startDate, at most 90 days, startDate not in the past (gym timezone), notes trimmed to 300 chars. Overlaps with a PENDING or APPROVED absence are rejected.
Response 201: { "absence": { ...same shape as the list items } }
Errors: 403 (not an instructor) · 400 (validation) · 409 (overlap)
DELETE /api/v1/me/absences/{id}
Cancels one of the instructor's own requests while it is still PENDING. Approved or rejected absences can only be changed by the manager.
Response 200: { "ok": true } · Errors: 403 (not an instructor) · 404 (not found or already resolved)
GET /api/v1/me/clock
Current clock-in state of the instructor (time tracking / registro de jornada). Timestamps are always set by the server; the app never sends a time.
Response 200:
{
"open": {
"id": "cuid_xxx",
"workDate": "2026-10-04",
"clockIn": "2026-10-04T07:02:11.000Z",
"clockOut": null,
"status": "OPEN"
},
"today": [ { "...": "entries whose workDate is today, ordered by clockIn" } ],
"workDate": "2026-10-04",
"serverTime": "2026-10-04T09:30:00.000Z"
}| Field | Notes |
|---|---|
open | The open entry, or null. It may belong to a previous workDate (night shift crossing midnight). |
today | Entries of the current work day. Several per day are allowed (split shifts). |
workDate | Current work day (YYYY-MM-DD) in the gym timezone. |
serverTime | Use the offset against the device clock to render the running timer. |
status | OPEN, CLOSED, or INCOMPLETE (forgotten clock-out: clockOut stays null; the manager fixes it from the web). |
source | APP (clocked from the app) or MANUAL (added by the manager). note/editedAt describe a manager correction. |
incident | null or { id, note, status: "PENDING" | "ACCEPTED" | "REJECTED", proposedClockIn, proposedClockOut, response, createdAt, resolvedAt }. |
Errors: 403 FORBIDDEN (not an instructor).
POST /api/v1/me/clock
Clocks in or out.
Body: { "action": "in" | "out", "incident": "optional text", "proposedTime": "HH:MM" }
proposedTime (optional, only with incident) is the real time the instructor claims, as wall-clock time of the gym on the entry's work day: on in it becomes proposedClockIn, on out proposedClockOut (a time earlier than the clock-in means the next day). It must not be in the future nor more than 16 h away. When the manager accepts the incident, the proposed time replaces the entry's clockIn/clockOut (recorded as a manager correction); rejecting leaves the entry untouched.
incident (3–500 chars, optional) attaches an incidencia to the entry being created (in) or closed (out): e.g. "Llegué 20 min tarde por una avería del tren". The manager accepts or rejects it from the web, optionally with a response, and the instructor gets a push notification. Each entry carries at most one incident: reporting again on out appends to the text and resets it to PENDING.
inwith anOPENentry from a previous work day marks that entryINCOMPLETEand opens a new one. AnOPENentry from today is a conflict.outcloses theOPENentry (even if it started yesterday).
Response 201: { "entry": { ...the created/closed entry }, "open": ..., "today": [...], "workDate": "...", "serverTime": "..." } (same state fields as GET).
Errors: 403 FORBIDDEN (not an instructor, or inactive profile) · 400 (invalid action) · 409 ALREADY_CLOCKED_IN / 409 NOT_CLOCKED_IN — the 409 body also carries the current state so the app can resync.
GET /api/v1/me/clock/history
Monthly time-tracking history of the instructor ("Mis fichajes" in the app): one row per day with worked vs. planned minutes, balance and state, plus the month totals. Same computation as the manager's monthly sheet in the web (Control horario → monitor), so both sides see the same figures.
Query: month=YYYY-MM (optional; defaults to the current month in the gym timezone).
Response 200:
{
"month": "2026-10",
"todayIso": "2026-10-26",
"serverTime": "2026-10-26T18:17:00.000Z",
"days": [
{
"date": "2026-10-23",
"state": "closed",
"plannedMinutes": 480,
"realMinutes": 337,
"balanceMinutes": -143,
"plannedStart": "09:00",
"plannedEnd": "17:00",
"absence": null,
"holidayName": null,
"isClosed": false,
"isFuture": false,
"alerts": [ { "kind": "late", "label": "Entrada 40 min tarde" } ],
"entries": [ { "...": "same shape as GET /api/v1/me/clock entries" } ]
}
],
"totals": {
"realMinutes": 7123,
"plannedMinutes": 7380,
"balanceMinutes": -257,
"overtimeMinutes": 95,
"daysWorked": 17,
"daysPlanned": 18,
"missingDays": 1,
"incompleteCount": 0,
"pendingIncidentCount": 1
}
}| Field | Notes |
|---|---|
days | Every day of the month, ascending. Future days come with isFuture: true and zeroes. |
state | no_shift (no shift, no entries) · missing (shift but no entries) · in_progress (open entry) · incomplete (an entry without clock-out) · closed. |
plannedMinutes | Minutes of the instructor's shifts in the resolved schedule (template + day snapshots). |
realMinutes | Clocked minutes; an open entry counts up to serverTime, an INCOMPLETE one counts 0. |
balanceMinutes | real − planned. null while the day is not over (today with an open entry or a shift still to come, or future). A day with an approved absence and no entries balances to 0. |
absence | Approved absence type for that day (VACATION, SICK_LEAVE, PERSONAL, OTHER) or null. |
alerts | kind is missing, incomplete, incident (pending), late or unplanned; label is a Spanish text ready to show. |
totals.plannedMinutes | Only days up to today. totals.balanceMinutes sums the balances of closed days (the month's hour bank). |
Errors: 400 (invalid month) · 403 FORBIDDEN (not an instructor).
GET /api/v1/me/documents
The employee's document folder (the same one managers maintain in the web under Equipo → member → Documentos): payslips, contracts, sick notes, documents to sign…
Response 200:
{
"enabled": true,
"folders": [
{ "id": "clx…", "parentId": null, "name": "Nóminas", "createdAt": "2026-10-01T10:00:00.000Z" }
],
"documents": [
{
"id": "clx…",
"folderId": "clx…",
"name": "nomina-septiembre.pdf",
"contentType": "application/pdf",
"size": 184320,
"source": "WEB",
"uploadedByName": "Ana López",
"isMine": false,
"createdAt": "2026-10-01T10:05:00.000Z"
}
]
}foldersis the whole tree (nest byparentId;null= root).documents[].folderIdnull= root.source:WEB(uploaded by a manager) ·APP(uploaded by the employee from the app).isMine= uploaded by the current user (only those can be deleted from the app).enabled: falsewhen file storage is not configured in that environment (listing works, uploads/downloads return503 NOT_CONFIGURED).- The app receives a push (
data.screen = "documents") when a manager leaves new documents.
POST /api/v1/me/documents
Uploads a file (sick note, signed document, photo…) to the employee's own folder.
Body: multipart/form-data with file (required), folderId (optional, a folder id from GET) and name (optional, overrides the file name). Max 25 MB; on Vercel the request body cannot exceed 4.5 MB, so compress photos before uploading. Allowed types: PDF, images (JPEG/PNG/WebP/HEIC), Office/OpenDocument, TXT/CSV, ZIP.
Response 201: { "document": { …same shape as in GET, "isMine": true } }
Errors: 400 (missing file, invalid name or type) · 413 (too large) · 404 NOT_FOUND (unknown folderId) · 503 NOT_CONFIGURED
GET /api/v1/me/documents/{id}
Downloads the file (binary stream with Content-Type, Content-Length and Content-Disposition: attachment). Add ?inline=1 to get inline (open PDFs/images in a viewer). Files are private: the Bearer token is required, the URL cannot be shared.
Errors: 404 NOT_FOUND · 503 NOT_CONFIGURED
DELETE /api/v1/me/documents/{id}
Deletes a document the employee uploaded from the app (isMine: true). Documents left by managers cannot be deleted from the app.
Response 204 · Errors: 400 (not uploaded by this user) · 404 NOT_FOUND
POST /api/v1/push-tokens · DELETE /api/v1/push-tokens
Registers (upsert) or removes an Expo push token for the current user. A token is unique per device: if another user signs in on the same device, the upsert reassigns it.
Body: { "token": "ExponentPushToken[...]", "platform": "ios" | "android" } (platform optional, ignored on DELETE)
Response 200: { "ok": true } · Errors: 400 (invalid token)
Error Responses
| Status | Body | Cause |
|---|---|---|
| 401 | { "error": "No autenticado", "code": "UNAUTHENTICATED" } | Missing or invalid Bearer token |
| 403 | { "error": "...", "code": "NO_ACCOUNT" } | Valid session, no active account (/me only) |
| 403 | { "error": "Sin acceso a este club" } | User doesn't have access to the requested club |
| 404 | { "error": "Club no encontrado" } | Invalid club slug |
| 400 | { "error": "Parámetro 'week' inválido..." } | Malformed week query parameter |
| 403 | { "error": "...", "code": "FORBIDDEN" } | Instructor-only endpoint called by a non-instructor account |
| 409 | { "error": "...", "code": "ALREADY_CLOCKED_IN" | "NOT_CLOCKED_IN", ...state } | Clock action conflicts with the current state |