# Use Cases

Real-world integration scenarios for sTvOS.

sTvOS is designed to power a range of fitness and wellness products. Below are common integration scenarios with the API endpoints you will need.

New to sTvOS?

Start with the Getting Started guide to set up authentication and make your first API call, then return here for real-world integration patterns.

# White-Label Fitness App

---
config:
  theme: base
  themeVariables:
    primaryColor: "#dbeafe"
    primaryTextColor: "#1e3a5f"
    primaryBorderColor: "#60a5fa"
    secondaryColor: "#f0fdf4"
    secondaryTextColor: "#166534"
    secondaryBorderColor: "#86efac"
    tertiaryColor: "#f8fafc"
    tertiaryTextColor: "#475569"
    tertiaryBorderColor: "#cbd5e1"
    lineColor: "#94a3b8"
    fontFamily: "Inter, system-ui, sans-serif"
    fontSize: "13px"
---
flowchart LR
    subgraph app["White-Label App"]
        direction TB
        AUTH["Register / Login"]
        HOME["Home Feed"]
        PLAYER["Video Player"]
        PLANS["AI Plans"]
        TRACK["Progress"]
    end

    AUTH -->|"token"| HOME
    HOME -->|"play"| PLAYER
    HOME -->|"generate"| PLANS
    PLAYER -->|"heartbeats"| TRACK
    PLANS -->|"daily view"| HOME

    subgraph api["sTvOS API"]
        direction TB
        A1["/auth/*"]
        A2["/content/discover"]
        A3["/sessions/*"]
        A4["/users/me/*-plan"]
        A5["/progress/*"]
    end

    AUTH -.-> A1
    HOME -.-> A2
    PLAYER -.-> A3
    PLANS -.-> A4
    TRACK -.-> A5

Build a branded mobile app for a studio or gym chain. Users register, browse on-demand classes, track viewing progress, and receive AI-generated plans.

Ideal for

Boutique studios, gym chains, and fitness brands that want a fully branded experience without building a backend from scratch.

Endpoints you will use:

Flow	Endpoints
App config & branding	`GET /app/config`
Registration & login	`POST /auth/register`, `POST /auth/login`, `POST /auth/refresh`
Content discovery	`GET /content/discover`, `GET /content/classes`, `GET /content/search`
Session tracking	`POST /sessions/start`, `POST /sessions/:id/progress`
AI plans	`POST /users/me/workout-plan`, `POST /users/me/nutrition-plan`
Daily view	`GET /users/me/daily-plan`
Progress logging	`POST /progress/workout`, `POST /progress/nutrition`, `POST /progress/water`

Integration steps:

During onboarding, your client is set up with branding (logo, colours, features) and a Client API Key is provisioned.

Implement registration and login screens. Store the access and refresh tokens securely. Call /auth/refresh when the access token expires.

Use /content/discover for the home screen, /content/classes with filters for the browse screen, and /content/search for the search bar. Start sessions when users play a class and send progress heartbeats.

Let users generate personalised workout and nutrition plans from their profile. Display the daily plan view that combines everything into a single agenda.

Log completed workouts, nutrition intake, and water consumption. Use /progress to retrieve progress history for dashboard visualisations.

# Trainer Marketplace Platform

---
config:
  theme: base
  themeVariables:
    primaryColor: "#dbeafe"
    primaryTextColor: "#1e3a5f"
    primaryBorderColor: "#60a5fa"
    secondaryColor: "#f0fdf4"
    secondaryTextColor: "#166534"
    secondaryBorderColor: "#86efac"
    tertiaryColor: "#f8fafc"
    tertiaryTextColor: "#475569"
    tertiaryBorderColor: "#cbd5e1"
    lineColor: "#94a3b8"
    fontFamily: "Inter, system-ui, sans-serif"
    fontSize: "13px"
---
flowchart TB
    subgraph user["User Journey"]
        DISC["Browse Trainers"] --> AVAIL["Check Availability"]
        AVAIL --> BOOK["Book Session"]
        BOOK --> JOIN["Join Video Call"]
    end

    subgraph trainer["Trainer Portal"]
        SCHED["Set Availability"] --> MANAGE["Manage Bookings"]
        MANAGE --> LAUNCH["Launch Session"]
        LAUNCH --> JOIN
    end

    subgraph services["Service Types"]
        direction LR
        S1["1-on-1 Sessions"]
        S2["Group Classes"]
        S3["Programmes"]
    end

    BOOK --- S1
    BOOK --- S2
    BOOK --- S3

Build a platform where users can discover trainers, book 1-on-1 sessions, join group classes, and subscribe to structured programmes.

Ideal for

Platforms connecting independent trainers with clients, PT studios offering online booking, and hybrid in-person/virtual training businesses.

Endpoints you will use:

Flow	Endpoints
Trainer discovery	`GET /trainers`, `GET /trainers/:id`
Services & availability	`GET /trainers/:id/services`, `GET /trainers/:id/availability`
Booking	`POST /trainers/:id/book`, `POST /trainers/classes/:id/join`
Programmes	`POST /trainers/:id/programmes/subscribe`
Booking management	`GET /my-bookings/summary`, `GET /my-bookings/sessions`
Video sessions	`POST /trainer-portal/bookings/:id/launch`

Integration steps:

Fetch trainer details with /trainers/:id which returns services, classes, and programmes. Show availability with /trainers/:id/availability.

Let users book 1-on-1 sessions by selecting a time slot. For group classes, use the join endpoint. For multi-week programmes, use the subscribe endpoint.

Build a "My Bookings" screen using /my-bookings/summary for counts and /my-bookings/sessions for the detailed list. Support cancel, pause, and resume actions.

When it is time for a session, trainers hit the launch endpoint which creates a LiveKit room and returns a meeting link. Both trainer and client join the same room.

# Partner-Managed Corporate Wellness

---
config:
  theme: base
  themeVariables:
    primaryColor: "#dbeafe"
    primaryTextColor: "#1e3a5f"
    primaryBorderColor: "#60a5fa"
    actorBkg: "#f8fafc"
    actorBorder: "#94a3b8"
    actorTextColor: "#1e293b"
    signalColor: "#475569"
    signalTextColor: "#475569"
    labelBoxBkgColor: "#f8fafc"
    labelBoxBorderColor: "#e2e8f0"
    loopTextColor: "#475569"
    activationBorderColor: "#94a3b8"
    activationBkgColor: "#f1f5f9"
    noteBkgColor: "#f0f9ff"
    noteBorderColor: "#bae6fd"
    noteTextColor: "#0c4a6e"
    fontFamily: "Inter, system-ui, sans-serif"
    fontSize: "13px"
---
sequenceDiagram
    participant Partner as Partner Staff
    participant Employee as Employee
    participant API as sTvOS

    Note over Partner: Onboarded with portal credentials

    Partner->>API: POST /partner/vouchers
    Note right of Partner: Generate 500 codes
    API-->>Partner: Voucher codes

    Partner-->>Employee: Distribute codes

    Employee->>API: POST /auth/voucher/validate
    API-->>Employee: Valid, partner info

    Employee->>API: POST /auth/register + voucherCode
    API-->>Employee: Account created

    loop Monthly
        Partner->>API: GET /partner/analytics
        Partner->>API: GET /partner/billing
        API-->>Partner: Usage + billing data
    end

A corporate partner distributes voucher codes to employees, who register and access the fitness platform. The partner tracks usage, manages members, and receives billing reports.

Ideal for

Corporate wellness programs, health insurance member benefits, hotel/resort fitness amenities, and reseller distribution models.

The partner uses:

Flow	Endpoints
Voucher management	`POST /partner/vouchers`, `GET /partner/vouchers`, `DELETE /partner/vouchers/:id`
Member oversight	`GET /partner/members`, `GET /partner/members/:id`
Analytics	`GET /partner/analytics`
Billing	`GET /partner/billing`, `GET /partner/billing/export`

The end user uses:

Flow	Endpoints
Voucher validation	`POST /auth/voucher/validate`
Registration	`POST /auth/register` (with `voucherCode`)
All client endpoints	Content, plans, trainers, progress

How it works:

During partner onboarding, a client is created with branding and features, API keys are provisioned, and partner staff accounts are set up.

Partner staff log in to the partner portal and generate voucher codes (POST /partner/vouchers). Codes can have custom prefixes and expiry dates. Up to 500 codes per request.

Each employee receives a voucher code. The mobile app validates the code and registers the user. The user is automatically mapped to the partner's client.

The partner portal shows member activity, watch time analytics, popular content, and monthly billing reports. All data is exportable as CSV.

# Voice AI Onboarding

---
config:
  theme: base
  themeVariables:
    primaryColor: "#dbeafe"
    primaryTextColor: "#1e3a5f"
    primaryBorderColor: "#60a5fa"
    secondaryColor: "#f0fdf4"
    secondaryTextColor: "#166534"
    secondaryBorderColor: "#86efac"
    tertiaryColor: "#f8fafc"
    tertiaryTextColor: "#475569"
    tertiaryBorderColor: "#cbd5e1"
    lineColor: "#94a3b8"
    fontFamily: "Inter, system-ui, sans-serif"
    fontSize: "13px"
---
flowchart TB
    subgraph voice["Voice Session (LiveKit + Hume EVI)"]
        direction LR
        TOKEN["Generate LiveKit Token"] --> ROOM["Join Voice Room"]
        ROOM --> CONV["AI Conversation"]
    end

    subgraph data["Profile Data (API)"]
        direction LR
        SAVE["Save Profile"] --> COACH["Recommend Coaches"]
        COACH --> SELECT["Select Coach"]
    end

    subgraph result["Account Creation"]
        REG["POST /auth/register"]
        REG --> READY(("Account\nReady"))
    end

    CONV -->|"saves responses"| SAVE
    CONV -->|"coach preference"| COACH
    data --> REG

Use Hume's Empathic Voice Interface to create a conversational onboarding experience. A voice AI coach guides users through profile setup, recommends a human coach, and gets them started with their first plan.

Ideal for

Apps targeting less tech-savvy users, premium onboarding experiences, and brands that want to differentiate with AI-powered personalisation.

Endpoints you will use:

Flow	Endpoints
Onboarding profile	`POST /onboarding/profile`
Coach recommendations	`POST /onboarding/recommend-coaches`
Voice session	`POST /livekit/token`
Hume config	`GET /hume-config`
Registration	`POST /auth/register`

How it works:

Generate a LiveKit token without a bearer token (anonymous session). The Hume EVI agent joins the room and begins the conversation.

During the conversation, the voice agent asks about fitness goals, experience level, schedule, and preferences. The app calls /onboarding/profile to save responses as the conversation progresses.

When the conversation ends, the app has all the data needed for registration. Call /auth/register with the session ID and coach ID to create the account with the full profile already attached.

# AI Food Scanning & Nutrition Tracking

Add food photo analysis to your app. Users snap a photo of their meal and get instant nutritional breakdown powered by Google Vertex AI Gemini.

Ideal for

Nutrition-focused apps, diet tracking features, calorie counting tools, and health coaching platforms.

Endpoints you will use:

Flow	Endpoints
Food scanning	`POST /food-scanner/scan-food`
Supported formats	`GET /food-scanner/supported-formats`
Nutrition logging	`POST /progress/nutrition`
Nutrition plans	`POST /users/me/nutrition-plan`

Integration example:

curl -X POST https://api.studiostv.net/api/v1/food-scanner/scan-food \
  -H "X-API-Key: your-api-key" \
  -F "image=@meal-photo.jpg"

curl -X POST https://api.studiostv.net/api/v1/food-scanner/scan-food \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "image": "data:image/jpeg;base64,/9j/4AAQ..." }'

The response includes identified foods, portion estimates, and a complete nutritional breakdown (calories, protein, carbs, fat, fiber, sugar, sodium, cholesterol) per portion and per 100g.

# Trainer Portal (Self-Service)

Trainers manage their own business through a dedicated portal: set availability, handle bookings, create group classes, build programmes, and track client relationships.

Ideal for

Independent trainers who need a self-service tool, PT businesses, and studios that want trainers to manage their own schedules.

Endpoints trainers use:

Flow	Endpoints
Profile	`GET/PUT /trainer-portal/profile`
Availability	`GET/POST/DELETE /trainer-portal/availability`
Bookings	`GET/PUT /trainer-portal/bookings`
Video sessions	`POST /trainer-portal/bookings/:id/launch`
Group classes	`POST/GET /trainer-portal/group-classes`
Programmes	`POST/GET/PUT /trainer-portal/programmes`
Clients	`GET/PUT /trainer-portal/clients`
Dashboard	`GET /trainer-portal/dashboard`

Trainer role required

Trainer portal endpoints require the user to have the trainer role. Trainers are created during onboarding, then register as users via /trainer-auth/register.