Trainee calendar

Trainees can book a training session or a conversation with their coach from the app. Slots are generated on request from the coach’s availability windows and existing calendar events. Nothing is pre-materialized. Mount: /v1/trainee/calendar, router traineeCalendarRouter in src/modules/trainee-calendar/trainee-calendar.routes.ts. Lane: trainee. Each route uses authenticateTrainee only, without the app access guard. Preview tokens can call the two GET routes. See Authentication.

Rules that apply to every endpoint

Feature switch. When the studio’s settings.calendarEnabled is explicitly false, every endpoint returns 403 calendar is disabled for this studio. The same flag is exposed to the app as studio.calendarEnabled on sign-in and me.
Which coach. Slots are for the trainee’s assigned coach (Client.coachId). A trainee with no assigned coach gets the studio’s oldest active HEAD_COACH, or failing that the oldest active coach.
Time zone. Availability windows are wall-clock minutes of the day. They are converted to UTC instants in the studio’s time zone (Studio.timezone, default Asia/Jerusalem). The trainee’s own zone is not used here.
Bookable types. TRAINING and CONVERSATION (BOOKABLE_SLOT_TYPES).

Endpoints

`GET /v1/trainee/calendar/slots`

Lists the free slots in a time range. Auth: trainee token.

string

required

ISO date or date-time. Start of the range.

string

required

ISO date or date-time. Must be after from.

string

TRAINING or CONVERSATION. Omit for both.

How slots are generated (generateSlots):

The coach’s active AvailabilityWindow rows are loaded. A window is either RECURRING on a weekday, or bound to one date. Each has startMinute, endMinute, durationMin and a slotType.
For each day in the range, each matching window is cut into back-to-back slots of durationMin. The walk covers at most 31 days from from (MAX_SLOT_RANGE_DAYS), whatever to says.
A slot is kept when it starts inside the range, starts in the future, and does not overlap any calendar event of that coach whose status is not CANCELLED.

Slots are sorted by start time. Response: 200.

{
  "ok": true,
  "data": {
    "items": [
      {
        "coachId": "cm1c5e7gh0002",
        "slotType": "CONVERSATION",
        "startsAt": "2026-10-08T07:00:00.000Z",
        "endsAt": "2026-10-08T07:30:00.000Z",
        "durationMin": 30
      },
      {
        "coachId": "cm1c5e7gh0002",
        "slotType": "CONVERSATION",
        "startsAt": "2026-10-08T07:30:00.000Z",
        "endsAt": "2026-10-08T08:00:00.000Z",
        "durationMin": 30
      }
    ]
  },
  "requestId": "01JB2M8Q4T6W9XK3C5V7N0PZRD"
}

When the studio has no active coach at all, items is empty. Errors:

Code	Status	When
`VALIDATION`	422	`from` or `to` missing or not a date, or `to must be after from`
`NOT_FOUND`	404	`client not found`
`FORBIDDEN`	403	`calendar is disabled for this studio`

`POST /v1/trainee/calendar/book`

Books one slot. Auth: trainee token. Refused for preview tokens.

string

required

The coach from the slot.

string

required

TRAINING or CONVERSATION.

string

required

The slot’s startsAt, exactly as returned.

string

required

The slot’s endsAt, exactly as returned. Must be after startsAt.

The server never trusts the times sent. It regenerates the slots for that coach, type and window and requires one whose start and end match to the millisecond. It then checks once more for an overlapping event before inserting. A trainee with an assigned coach can only book that coach. The booking is a CalendarEvent with title set to the trainee’s name, type set to the slot type and status CONFIRMED. The module sends no notification and writes no Google Calendar event. The availability check and the insert are separate queries, not one transaction. Two trainees booking the same slot at the same instant are not guarded by a database constraint. Response: 201. The created event.

{
  "ok": true,
  "data": {
    "id": "cm3c5w8fg000zl908i3d6j0ea",
    "studioId": "cm1s7d2kq0000jx08b4n6h1ze",
    "coachId": "cm1c5e7gh0002",
    "clientId": "cm2k9x1ab0001l508u3f7q2wd",
    "title": "Noa Cohen",
    "type": "CONVERSATION",
    "status": "CONFIRMED",
    "startsAt": "2026-10-08T07:00:00.000Z",
    "endsAt": "2026-10-08T07:30:00.000Z",
    "location": null,
    "googleEventId": null,
    "createdAt": "2026-10-07T12:00:00.000Z",
    "updatedAt": "2026-10-07T12:00:00.000Z"
  },
  "requestId": "01JB2M8Q4T6W9XK3C5V7N0PZRD"
}

Errors:

Code	Status	When
`VALIDATION`	422	Body fails the schema, or `endsAt must be after startsAt`
`NOT_FOUND`	404	`client not found`
`FORBIDDEN`	403	`calendar is disabled for this studio`, or `cannot book with this coach` when the trainee is assigned to a different coach
`CONFLICT`	409	`slot is no longer available`: the times do not match a free slot, or another event now overlaps

`GET /v1/trainee/calendar/meetings`

Lists every calendar event linked to the trainee, past and future, including cancelled ones. Auth: trainee token. No parameters. Ordered by startsAt, newest first. This endpoint does not check the calendar feature switch. Response: 200.

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "cm3c5w8fg000zl908i3d6j0ea",
        "studioId": "cm1s7d2kq0000jx08b4n6h1ze",
        "coachId": "cm1c5e7gh0002",
        "clientId": "cm2k9x1ab0001l508u3f7q2wd",
        "title": "Noa Cohen",
        "type": "CONVERSATION",
        "status": "CONFIRMED",
        "startsAt": "2026-10-08T07:00:00.000Z",
        "endsAt": "2026-10-08T07:30:00.000Z",
        "location": null,
        "googleEventId": null,
        "createdAt": "2026-10-07T12:00:00.000Z",
        "updatedAt": "2026-10-07T12:00:00.000Z",
        "studio": { "timezone": "Asia/Jerusalem" }
      }
    ]
  },
  "requestId": "01JB2M8Q4T6W9XK3C5V7N0PZRD"
}

Events a coach created for the trainee from the web calendar appear here too, with whatever type the coach chose. studio.timezone is included so the app can show times in the studio’s zone. Errors: none beyond the lane errors.

`POST /v1/trainee/calendar/meetings/:id/cancel`

Cancels one of the trainee’s upcoming meetings. Auth: trainee token. Refused for preview tokens.

string

required

The calendar event id.

Sets the event’s status to CANCELLED. The slot becomes bookable again, because cancelled events are ignored when slots are generated. Cancelling an already cancelled meeting returns it unchanged. Like the meetings list, this endpoint does not check the calendar feature switch. Response: 200. The event row, same shape as a booking, with status CANCELLED. Errors:

Code	Status	When
`NOT_FOUND`	404	`meeting not found`: no such event for this trainee in this studio
`VALIDATION`	422	`cannot cancel a past meeting`: the meeting has already started

API basics

Trainees

Plans and libraries

Tracking

Imports

Forms

Tasks and automation

Communication

Studio and billing

Admin and internal services

Trainee app API

Partner and automation

Public, internal and auth

Trainee calendar

Rules that apply to every endpoint

Endpoints

`GET /v1/trainee/calendar/slots`

`POST /v1/trainee/calendar/book`

`GET /v1/trainee/calendar/meetings`

`POST /v1/trainee/calendar/meetings/:id/cancel`

​Rules that apply to every endpoint

​Endpoints

​GET /v1/trainee/calendar/slots

​POST /v1/trainee/calendar/book

​GET /v1/trainee/calendar/meetings

​POST /v1/trainee/calendar/meetings/:id/cancel

Rules that apply to every endpoint

Endpoints

`GET /v1/trainee/calendar/slots`

`POST /v1/trainee/calendar/book`

`GET /v1/trainee/calendar/meetings`

`POST /v1/trainee/calendar/meetings/:id/cancel`