v1
Powered by

# Trainers & Bookings API

Trainer discovery, booking, group classes, programmes, and the trainer portal.

Discover trainers, book sessions, join group classes, subscribe to programmes, and manage bookings. All endpoints require X-API-Key and Authorization: Bearer <token>.

# Trainer Discovery

# List Trainers GET /trainers

List all trainers with pagination and search.

Parameter Type Description
page number Page number
limit number Results per page
search string Search by name
active boolean Filter active trainers

# Trainer Detail GET /trainers/:id

Get a trainer's full profile including services, classes, and programmes.

{
  "success": true,
  "data": {
    "trainer": {
      "id": 5,
      "name": "Coach Mike",
      "bio": "Certified personal trainer with 10 years experience...",
      "image": "https://...",
      "services": [
        { "id": 1, "name": "1-on-1 Training", "duration": 60, "price": 75 }
      ],
      "classes": [
        { "id": 10, "name": "Group HIIT", "scheduledDate": "2026-03-01" }
      ],
      "programmes": [
        { "id": 3, "name": "12-Week Transformation", "price": 299 }
      ]
    }
  }
}

# Trainer Services GET /trainers/:id/services

Get all services offered by a trainer.

{
  "success": true,
  "data": {
    "services": [
      {
        "id": 1,
        "name": "1-on-1 Training",
        "description": "Personalised training session",
        "duration": 60,
        "price": 75.00,
        "currency": "GBP"
      },
      {
        "id": 2,
        "name": "Online Coaching Call",
        "description": "30-minute video check-in",
        "duration": 30,
        "price": 35.00,
        "currency": "GBP"
      }
    ]
  }
}

# Trainer Classes GET /trainers/:id/classes

Get both recorded classes and upcoming group classes for a trainer.

{
  "success": true,
  "data": {
    "recordedClasses": [
      { "id": 42, "name": "HIIT Blast", "duration": 30, "intensity": "high" }
    ],
    "upcomingGroupClasses": [
      { "id": 10, "name": "Group HIIT", "scheduledDate": "2026-03-01", "spotsLeft": 8 }
    ]
  }
}

# Trainer Availability GET /trainers/:id/availability

Get the trainer's weekly availability and bookable time slots.

Parameter Type Required Description
startDate string Yes Start date (YYYY-MM-DD)
endDate string No End date
serviceId number No Filter slots for a specific service

# Booking

# Book 1-on-1 Session POST /trainers/:id/book

Book a one-on-one training session with a trainer.

{
  "serviceId": 1,
  "slotId": 42,
  "notes": "Focus on upper body"
}
 
{
  "success": true,
  "data": {
    "booking": {
      "id": 1,
      "trainerId": 5,
      "userId": 1,
      "status": "confirmed",
      "scheduledDate": "2026-03-05",
      "scheduledTime": "10:00",
      "service": { "name": "1-on-1 Training" }
    }
  }
}

# Join Group Class POST /trainers/classes/:classId/join

Join a scheduled group training class.

{
  "paymentAmount": 15.00
}

# Subscribe to Programme POST /trainers/:id/programmes/subscribe

Subscribe to a multi-week structured programme.

{
  "programmeId": 3,
  "startDate": "2026-03-01",
  "paymentAmount": 299.00
}

# My Bookings with Trainer GET /trainers/:id/my-bookings Bearer

Get the current user's bookings with a specific trainer.

{
  "success": true,
  "data": {
    "sessions": [
      {
        "id": 1,
        "status": "confirmed",
        "scheduledDate": "2026-03-05",
        "scheduledTime": "10:00",
        "service": { "name": "1-on-1 Training" }
      }
    ],
    "groupClasses": [],
    "programmes": []
  }
}

# My Bookings

A unified view of all the user's bookings across sessions, group classes, and programmes.

# Summary GET /my-bookings/summary

Get counts and the next upcoming booking.

{
  "success": true,
  "data": {
    "upcomingSessions": 2,
    "upcomingGroupClasses": 1,
    "activeProgrammes": 1,
    "nextBooking": {
      "type": "session",
      "trainerName": "Coach Mike",
      "date": "2026-03-05",
      "time": "10:00"
    }
  }
}

# 1-on-1 Sessions

Method Path Description
GET /my-bookings/sessions List all bookings (status, trainerId, startDate, endDate, page, limit)
GET /my-bookings/sessions/upcoming Upcoming confirmed sessions
GET /my-bookings/sessions/:id Booking details
POST /my-bookings/sessions/:id/cancel Cancel a booking

# Group Classes

Method Path Description
GET /my-bookings/group-classes All participations
GET /my-bookings/group-classes/upcoming Upcoming classes
POST /my-bookings/group-classes/:classId/cancel Cancel participation

# Programmes

Method Path Description
GET /my-bookings/programmes All subscriptions (status filter)
GET /my-bookings/programmes/:id Subscription details
POST /my-bookings/programmes/:id/pause Pause subscription
POST /my-bookings/programmes/:id/resume Resume subscription
POST /my-bookings/programmes/:id/cancel Cancel subscription

# Trainer Portal

Self-service endpoints for trainers to manage their business. Requires X-API-Key + Bearer token + trainer role.

# Profile

Method Path Description
GET /trainer-portal/profile Profile with statistics
PUT /trainer-portal/profile Update profile

# Availability

Method Path Description
GET /trainer-portal/availability Weekly availability
POST /trainer-portal/availability Set recurring availability
DELETE /trainer-portal/availability/:id Delete a slot
POST /trainer-portal/time-slots Create a specific bookable time slot

# Bookings

Method Path Description
GET /trainer-portal/bookings List bookings (status, startDate, endDate)
PUT /trainer-portal/bookings/:id Update status, add notes or meeting link
POST /trainer-portal/bookings/:id/launch Launch 1-on-1 video session (returns meeting link)

# Group Classes

Method Path Description
POST /trainer-portal/group-classes Create a group class
GET /trainer-portal/group-classes List group classes
POST /trainer-portal/group-classes/:id/launch Launch video session

# Programmes

Method Path Description
POST /trainer-portal/programmes Create a programme
GET /trainer-portal/programmes List programmes with subscriber counts
PUT /trainer-portal/programmes/:id Update a programme

# Client Management

Method Path Description
GET /trainer-portal/clients List clients (status filter)
PUT /trainer-portal/clients/:userId Update client notes and tags

# Dashboard GET /trainer-portal/dashboard

Get dashboard statistics: today's bookings, weekly summary, revenue, and upcoming sessions.

# Booking Flow

Browse trainers with GET /trainers or find a specific one with GET /trainers/:id. View their services, classes, and programmes.

Call GET /trainers/:id/availability to see available time slots for the desired date range and service.

Select a time slot and book with POST /trainers/:id/book. The user receives a confirmed booking.

When it is time, the trainer launches the session from the trainer portal (POST /trainer-portal/bookings/:id/launch). Both parties join the LiveKit video room.

Users can view and cancel bookings through /my-bookings. Trainers manage bookings through /trainer-portal/bookings.

# Invite Codes

# Check Invite POST /invite/check Public

Validate a trainer invite code. No authentication required.

{
  "code": "COACH-MIKE-2026"
}

© Copyright 2026. sTvOS -- Multi-tenant fitness operating system.