Sessions¶

Endpoints for scheduling, managing, and joining video sessions within a mentorship.

Base path: /api/sessions

Authentication: All endpoints require a valid session and an organization context.

Endpoints¶

Method	Path	Min Role	Description
`GET`	`/api/sessions`	`Teacher`	List sessions
`POST`	`/api/sessions`	`Coach`	Schedule a new session
`GET`	`/api/sessions/:id`	`Teacher`	Get session details
`PATCH`	`/api/sessions/:id`	`Teacher`	Update session
`DELETE`	`/api/sessions/:id`	`Coach`	Cancel a session
`GET`	`/api/sessions/:id/agora-token`	`Teacher`	Get Agora RTC token for video call
`POST`	`/api/sessions/:id/reactions`	`Teacher`	Send an in-call emoji reaction

Data Model¶

A session represents a single scheduled video call within a mentorship.

Field	Type	Description
`id`	string	UUID
`mentorshipId`	string	Parent mentorship UUID
`scheduledAt`	string	ISO 8601 timestamp for the scheduled start
`durationMinutes`	integer	Planned duration in minutes
`timezone`	string	IANA timezone string (e.g. `America/Panama`)
`notes`	string \| null	Optional coach notes
`status`	string	See status lifecycle below
`agoraChannel`	string \| null	Agora channel name for the video call
`cancelledAt`	string \| null	When the session was cancelled
`cancelledBy`	string \| null	User CUID who cancelled
`completedAt`	string \| null	When the session was marked completed
`createdAt`	string	ISO 8601 timestamp
`updatedAt`	string	ISO 8601 timestamp

Status Lifecycle¶

scheduled → confirmed → completed
                     ↘ missed
         ↘ cancelled

Status	Description
`scheduled`	Created by the coach; awaiting teacher confirmation
`confirmed`	Accepted by the teacher
`completed`	Call ended and marked complete
`cancelled`	Cancelled by the coach, manager, or admin
`missed`	Session time passed without completion

GET /api/sessions¶

List sessions visible to the caller.

Access rules:

Coach: only sees sessions from their own mentorships.
Teacher: only sees sessions from their own mentorships.
Manager, OrganizationAdmin, PlatformAdmin: see all sessions in the org.

Query parameters:

Parameter	Type	Description
`limit`	integer	Max records (default: `50`, max: `200`)
`offset`	integer	Records to skip (default: `0`)
`status`	string	Filter by status: `scheduled`, `confirmed`, `completed`, `cancelled`, or `missed`
`mentorshipId`	string	Filter by parent mentorship UUID
`from`	string	Filter sessions at or after this ISO 8601 datetime
`to`	string	Filter sessions at or before this ISO 8601 datetime

Response 200:

{
  "data": [
    {
      "id": "session-uuid",
      "mentorshipId": "mentorship-uuid",
      "scheduledAt": "2025-05-01T14:00:00.000Z",
      "durationMinutes": 60,
      "timezone": "America/Panama",
      "notes": "Discuss Q2 objectives",
      "status": "confirmed",
      "agoraChannel": "ms_abc123_1714560000000",
      "cancelledAt": null,
      "cancelledBy": null,
      "completedAt": null,
      "createdAt": "2025-04-01T12:00:00.000Z",
      "updatedAt": "2025-04-02T08:00:00.000Z",
      "mentorship": { ... },
      "coach": {
        "id": "coach-cuid",
        "email": "coach@example.com",
        "firstName": "Alice",
        "lastName": "Johnson",
        "avatarUrl": null
      },
      "teacher": {
        "id": "teacher-cuid",
        "email": "teacher@example.com",
        "firstName": "Bob",
        "lastName": "Williams",
        "avatarUrl": null
      }
    }
  ],
  "meta": {
    "total_count": 15
  }
}

Error responses:

Code	Condition
`400`	No organization context

POST /api/sessions¶

Schedule a new session for a mentorship. Both coach and teacher receive a confirmation email and a push notification (if they have a registered push token).

Min role: Coach

Access rules:

Coach can only create sessions for their own mentorships.
The mentorship must have status = 'active'.
No two sessions may be scheduled within 15 minutes of each other in the same mentorship.

Request body:

{
  "mentorshipId": "mentorship-uuid",
  "scheduledAt": "2025-05-01T14:00:00.000Z",
  "durationMinutes": 60,
  "timezone": "America/Panama",
  "notes": "Discuss Q2 objectives"
}

Field	Type	Required	Constraints
`mentorshipId`	string	Yes	Must be a valid UUID
`scheduledAt`	string	Yes	ISO 8601 datetime; must be in the future
`durationMinutes`	integer	No	15–480 (default: `60`)
`timezone`	string	No	IANA timezone string (default: `UTC`)
`notes`	string	No	Maximum 2000 characters

Response 201:

{
  "data": {
    "id": "session-uuid",
    "mentorshipId": "mentorship-uuid",
    "scheduledAt": "2025-05-01T14:00:00.000Z",
    "durationMinutes": 60,
    "timezone": "America/Panama",
    "notes": "Discuss Q2 objectives",
    "status": "scheduled",
    "agoraChannel": "ms_abc123_1714560000000",
    ...
  }
}

Error responses:

Code	Condition
`403`	`Coach` scheduling for another coach's mentorship
`404`	Mentorship not found
`409`	A session already exists within 15 minutes of this time
`422`	Mentorship is not in `active` status

GET /api/sessions/:id¶

Get full details of a single session.

Access rules:

Coach: can only view sessions from their own mentorships.
Teacher: can only view sessions from their own mentorships.

Path parameters:

Parameter	Type	Description
`id`	string	Session UUID

Response 200:

{
  "data": {
    "id": "session-uuid",
    "mentorshipId": "mentorship-uuid",
    "scheduledAt": "2025-05-01T14:00:00.000Z",
    "durationMinutes": 60,
    "timezone": "America/Panama",
    "notes": "Discuss Q2 objectives",
    "status": "confirmed",
    "agoraChannel": "ms_abc123_1714560000000",
    "cancelledAt": null,
    "cancelledBy": null,
    "completedAt": null,
    "createdAt": "2025-04-01T12:00:00.000Z",
    "updatedAt": "2025-04-02T08:00:00.000Z",
    "mentorship": { ... },
    "coach": { ... },
    "teacher": { ... }
  }
}

Error responses:

Code	Condition
`403`	`Coach` or `Teacher` viewing a session from a mentorship they are not part of
`404`	Session not found

PATCH /api/sessions/:id¶

Update session details or transition its status. Cancellation emails and push notifications are sent automatically when status transitions to cancelled.

Access rules:

Coach: can update scheduledAt, durationMinutes, timezone, notes, and status (all values except confirmed) for their own sessions.
Teacher: can only set status = 'confirmed'; cannot change time or notes.
Manager, OrganizationAdmin, PlatformAdmin: can update all fields.

Path parameters:

Parameter	Type	Description
`id`	string	Session UUID

Request body (all fields optional):

{
  "scheduledAt": "2025-05-02T15:00:00.000Z",
  "durationMinutes": 90,
  "timezone": "America/New_York",
  "notes": "Rescheduled to Thursday",
  "status": "confirmed"
}

Field	Type	Constraints
`scheduledAt`	string	ISO 8601 datetime; must be in the future; coach/admin only
`durationMinutes`	integer	15–480; coach/admin only
`timezone`	string	IANA timezone string; coach/admin only
`notes`	string	Maximum 2000 characters; coach/admin only
`status`	string	`scheduled`, `confirmed`, `completed`, `cancelled`, or `missed`; teacher can only set `confirmed`

Response 200:

{
  "data": {
    "id": "session-uuid",
    "status": "confirmed",
    ...
  }
}

Error responses:

Code	Condition
`403`	Role restriction on update fields
`404`	Session not found

DELETE /api/sessions/:id¶

Cancel a session. Sets status = 'cancelled'. Cancellation emails and push notifications are sent to both participants.

Completed or missed sessions cannot be deleted.

Min role: Coach

Path parameters:

Parameter	Type	Description
`id`	string	Session UUID

Response 200:

{
  "data": {
    "id": "session-uuid",
    "status": "cancelled",
    "cancelledAt": "2025-04-09T10:00:00.000Z",
    "cancelledBy": "coach-cuid",
    ...
  }
}

Error responses:

Code	Condition
`403`	`Coach` cancelling a session from another coach's mentorship
`404`	Session not found
`422`	Session is `completed` or `missed` and cannot be deleted

GET /api/sessions/:id/agora-token¶

Get a short-lived Agora RTC token for joining a video call session. The token is valid for 1 hour.

Access rules:

Only the coach and teacher assigned to the session's mentorship may request a token.
OrganizationAdmin, Manager, and PlatformAdmin may also request tokens (for monitoring).

Path parameters:

Parameter	Type	Description
`id`	string	Session UUID

Response 200:

{
  "data": {
    "token": "<agora-rtc-token>",
    "channel": "ms_abc123_1714560000000",
    "appId": "<agora-app-id>",
    "uid": 12345,
    "expiresAt": "2025-05-01T15:00:00.000Z"
  }
}

Response fields:

Field	Type	Description
`token`	string	Agora RTC token signed by the backend
`channel`	string	Channel name to join (pass to `client.join()`)
`appId`	string	Agora App ID (use this, not an env var)
`uid`	integer	Numeric UID assigned to this participant
`expiresAt`	string	ISO 8601 timestamp when the token expires

Use appId from the response

Always use the appId field from this response when initializing the Agora client. Do not use environment variables — they are not reliably available in browser bundles.

Error responses:

Code	Condition
`403`	Caller is not a participant of this session's mentorship
`404`	Session not found
`422`	Session has no Agora channel assigned

POST /api/sessions/:id/reactions¶

Send an emoji reaction during a live video call. The reaction is broadcast to all SSE subscribers watching the mentorship in real time.

Min role: Teacher

Path parameters:

Parameter	Type	Description
`id`	string	Session UUID

Request body:

{
  "emoji": "🎉"
}

Field	Type	Required	Constraints
`emoji`	string	Yes	Must be one of: `👍`, `❤️`, `😂`, `🎉`, `👏`, `🙌`

Response 200:

{
  "success": true
}

The reaction is also published as a call-reaction SSE event to all connected clients watching this mentorship. See Events for the event payload format.

Error responses:

Code	Condition
`400`	Invalid or unsupported emoji
`404`	Session not found