App Integration Guide

Screen-by-screen mapping of every app page to its sTvOS backend API calls.

This document maps every screen in the app to the sTvOS backend API endpoints it should call. Use it as a reference when building or migrating an app on the platform.

Conventions

Headers required on every client-scoped request:

Header	Value
`X-API-Key`	Universal key or per-client `fytos_...` key
`Authorization`	`Bearer <accessToken>` (when noted as "bearer required")
`Content-Type`	`application/json`

Response envelope: All responses return { success: true, data: ... } on success and { error, code, details } on failure.

Feature gating: The enabledFeatures array from /auth/me or /app/config determines which sections of the app to show. Check with features.includes('feature_key').

Feature Key	Unlocks
`classes`	On-demand video classes, class browsing
`live_classes`	Scheduled live streaming classes
`workout_builder`	AI workout generation, workout player
`nutrition`	Nutrition tracking, food scanning, meal plans
`coach_connect`	Trainer browsing, booking sessions
`ai_coach`	AI coaching (Hume voice/chat)

1. Auth and Onboarding


Purpose	Email/password authentication
API Call	`POST /auth/login`
Body	`{ email, password }`
Auth	API key only (no bearer)
Response	`{ user, tokens: { accessToken, refreshToken, expiresIn }, client? }`
Notes	In universal key mode, response includes `client` object with branding. Store tokens securely (expo-secure-store). Navigate to main app on success, `register` or `forgot` on failure.

Register


Purpose	Create new account
API Call	`POST /auth/register`
Body	`{ email, password, name, voucherCode?, sessionId? }`
Auth	API key only
Response	`{ user, tokens }` (201)
Error Codes	`USER_EXISTS`, `VOUCHER_REQUIRED`, `INVALID_VOUCHER`, `NO_DEFAULT_CLIENT`
Notes	Pass `voucherCode` if user arrived via voucher/deep link. Pass `sessionId` from onboarding to link pending profile data. Show voucher branding from `validateVoucher` data if available.

ForgotPass


Purpose	Request password reset email
API Call	`POST /auth/forgot-password`
Body	`{ email }`
Auth	API key only
Status	NOT YET IMPLEMENTED -- needs backend endpoint

VoucherEntry


Purpose	Manually enter a voucher code
API Call	`GET /app/join/:code`
Auth	Public (no key needed)
Response	`{ valid, client: { id, name, logo, splashScreen, enabledFeatures }, error? }`
Notes	On success, navigate to JoinScreen passing the voucher code and client data.

JoinScreen


Purpose	Post-voucher welcome with client branding
API Call	`GET /app/join/:voucherCode` (on mount, to refresh/validate)
Auth	Public
Notes	Display `client.logo`, `client.splashScreen`, `client.name`. Route to `register` (pre-filling voucher code) or `login`.

ProfileSetup (Onboarding Wizard)


Purpose	Multi-step profile setup before/after registration
API Calls

Step	Endpoint	Details
Save profile data per step	`POST /onboarding/profile`	Body: `{ sessionId, step, data: { ... } }`. Returns `sessionId` on first call.
Get coach recommendations	`POST /onboarding/recommend-coaches`	Body: `{ sessionId }`. Returns ranked coaches.
Select a coach	`POST /onboarding/select-coach`	Body: `{ sessionId, coachId }`
Generate workout plan (final)	`POST /users/me/workout-plan`	Bearer required. After registration.


Auth	Onboarding endpoints: API key only. Workout plan: bearer required.
Notes	Steps cover: gender, weight/height, birthday, diet/meals (if `nutrition`), activity level (if `workout_builder`), workout days, training location, goal, preferred classes. On finish, call `POST /auth/register` with `sessionId` to link profile, then generate workout plan if `workout_builder` enabled.

2. Profile and Settings

Profile


Purpose	Profile hub with avatar, name, links to sub-pages
API Calls

Action	Endpoint	Details
Load profile	`GET /auth/me`	Bearer required. Returns user + client.
Upload photo	`POST /auth/profile-photo`	NOT YET IMPLEMENTED
Delete account	`DELETE /users/me`	Bearer required.
Logout	`POST /auth/logout`	Bearer required. Discard tokens client-side.

ManageProfile


Purpose	Edit fitness preferences
API Calls	`GET /auth/me` (load), `PUT /users/me` (save)
Auth	Bearer required
Editable Fields	`name`, `gender`, `birthday`, `weight`, `height`, `activityLevel`, `workoutDays`, `goal`, `diet`, `meals`, `preferredClasses`
Notes	After saving workout-related fields, offer "Rebuild Workout" which calls `POST /users/me/workout-plan`.

Settings


Purpose	Language and theme toggle
API Calls	None -- local preferences only (`AsyncStorage` / context)

Terms (Privacy Policy)


Purpose	Render privacy policy HTML
API Call	`GET /app/strings`
Auth	API key required
Response	`{ data: [{ st_privacypolicy: "<html>..." }] }`
Notes	Render the `st_privacypolicy` value in a WebView or HTML renderer.

About


Purpose	Render about us HTML
API Call	`GET /app/strings`
Auth	API key required
Response	`{ data: [{ st_aboutus: "<html>..." }] }`
Notes	Render the `st_aboutus` value. Same endpoint as Terms -- fetch once and cache.

3. Workout System

Home


Purpose	Main dashboard with conditional sections
API Calls	Child components make their own calls (see below). Gate sections with `hasFeature()`.
Key Sections	Today's workout (workout_builder), latest classes (classes), goals, levels, exercises, diets (nutrition).

Section	Endpoint
Today's workout	`GET /users/me/daily-plan?date=YYYY-MM-DD` (bearer)
Latest classes	`GET /content/classes?limit=6&sort=newest` or `GET /classes?limit=6`
Discover/featured	`GET /content/discover` (bearer)

Workouts


Purpose	Paginated workout list
API Call	`GET /content/classes?page=1&limit=8&sort=newest` or `GET /classes?limit=8&page=1`
Auth	API key (+ bearer for content routes)
Notes	Navigate to `workoutdetails` on tap, `goals`/`levels`/`searchworkout` from header buttons.

WorkoutDetails


Purpose	Single workout with day schedule
API Calls

Action	Endpoint
Load workout	`GET /content/classes/:id` or `GET /classes/:id`
Load day detail	`GET /users/me/workout-plan/day/:dayId` (bearer)
Bookmark	Local only (AsyncStorage)
Add workout to plan	Navigate to `WorkoutLoading` with `{ workoutId }`

WorkoutLoading


Purpose	Loading screen during AI plan creation
API Call	`POST /users/me/workout-plan`
Body	`{ preferences?: { workoutDays?: ["mon","wed","fri"], intensity?, duration? }, overrides?: {...} }`
Auth	Bearer required
Fallback poll	`GET /sessions/history?active=true`
Notes	Navigate to `home` on success. Show error with retry on failure.

MyWorkouts (Progress Dashboard)


Purpose	Stats, charts, recent workout history
API Call	`GET /progress?period=week` or `GET /progress?period=month`
Auth	Bearer required
Notes	The `/progress` endpoint returns streak, charts, and recent workout logs. Period param: `day`, `week`, `month`, `year`.

SingleDay


Purpose	Single workout day with exercise list
API Calls

Action	Endpoint
Load day	`GET /users/me/workout-plan/day/:dayId` (bearer)
Update exercise status	`POST /progress/workout` (bearer)
Reset day	`DELETE /users/me/workout-plan` + recreate, or custom reset logic

Timer (Active Workout)


Purpose	Active workout execution with sets/reps
API Calls

Action	Endpoint
Load timer data	`GET /users/me/workout-plan/day/:dayId` (bearer)
Log set progress	`POST /progress/workout` (bearer)
Complete workout	`POST /progress/workout` with full exercise log (bearer)


Notes	Keep screen awake. Post workout log with exercises, sets, weights, reps, duration, perceived exertion.

Completed


Purpose	Post-workout summary
API Call	No new call needed -- use data from Timer completion response
Notes	Shows exercises completed, duration, calories. "Back to Home" button.

SearchWorkout


Purpose	Search workouts by query
API Call	`GET /content/search?q=<query>&page=1&limit=8` or `GET /classes?search=<query>&page=1&limit=8`
Auth	API key (+ bearer for content routes)

WorkoutsFav


Purpose	Favorited/bookmarked workouts
API Calls	Local only (AsyncStorage). Load IDs from storage, then fetch details per ID if needed via `GET /classes/:id`.

Player (Video)


Purpose	Full-screen video player
API Calls	`GET /video/access/:classId` (bearer) to get time-limited playback URLs. Use `streamUrl` (HLS) for native playback with `expo-video`, or `embedUrl` for web iframe.
Notes	Receives `{ classId }` from navigation params. The `streamUrl` expires naturally (check `streamExpiresAt`); request a fresh one if the user is still watching near expiry.

4. Exercises

Exercises


Purpose	Exercise library grouped by body part
API Call	`GET /classes/categories?type=bodypart`
Auth	API key

ExerciseDetails


Purpose	Single exercise with video, reps, sets, instructions
API Call	`GET /classes/:id`
Auth	API key

SingleMuscle


Purpose	Exercises filtered by muscle group
API Call	`GET /classes?muscle=<id>&page=1&limit=16`
Auth	API key

SingleEquipment


Purpose	Exercises filtered by equipment
API Call	`GET /classes?equipment=<id>&page=1&limit=16`
Auth	API key

Equipments


Purpose	Equipment list
API Call	`GET /classes/categories?type=equipment`
Auth	API key

5. Classes

Classes


Purpose	Paginated on-demand class list
API Call	`GET /content/classes?page=1&limit=20` or `GET /classes?page=1&limit=20`
Auth	API key (+ bearer for `/content` routes)

ClassDetails


Purpose	Class detail with preview video, description, coach info
API Call	`GET /content/classes/:id` or `GET /classes/:id`
Auth	API key
Notes	Can also use `route.params.class` if the full object was passed from the list. "Start Class" navigates to `classPlayer`.

ClassPlayer


Purpose	Full-screen class video player with session tracking
API Calls

Action	Endpoint
Get playback URLs	`GET /video/access/:classId` (bearer) -- returns `streamUrl` (HLS for expo-video) and `embedUrl` (web iframe)
Start session	`POST /sessions/start` -- Body: `{ classId, totalDurationSeconds }` (bearer)
Update progress	`POST /sessions/:id/progress` -- Body: `{ progressSeconds, completionPercentage }` (bearer)
Complete session	`POST /sessions/:id/complete` (bearer)


Notes	Lock to landscape. Track progress periodically (every 10-30s).

CategoryClasses


Purpose	Classes filtered by category
API Call	`GET /content/classes?category=<id>&page=1&limit=20` or `GET /classes?category=<id>&page=1`


Purpose	Class category list
API Call	`GET /content/categories` or `GET /classes/categories`

Coaches


Purpose	Coach/trainer list
API Call	`GET /trainers?page=1&limit=10`
Auth	Bearer required

CoachDetails


Purpose	Coach profile with their classes
API Calls	`GET /trainers/:id` and `GET /trainers/:id/classes`
Auth	Bearer required

6. Nutrition / Diets

Diets


Purpose	Paginated diet/nutrition content list
API Call	`GET /content/classes?type=nutrition&page=1&limit=6` or `GET /classes?type=nutrition&page=1&limit=6`
Auth	API key

DietDetails


Purpose	Diet detail with nutrition info, ingredients
API Call	`GET /content/classes/:id` or `GET /classes/:id`
Auth	API key
Notes	Bookmark via AsyncStorage (local).

DietsFav


Purpose	Favorited diets
API Calls	Local only (AsyncStorage). Fetch details per ID if needed.

CustomDiets


Purpose	User's AI-generated or assigned nutrition plans
API Call	`GET /users/me/nutrition-plan`
Auth	Bearer required
Notes	For week detail: `GET /users/me/nutrition-plan/week/:weekId`.

SingleCategory (Diets)


Purpose	Diets filtered by category
API Call	`GET /content/classes?type=nutrition&category=<id>&page=1&limit=6`

7. Blog / Posts

Blog


Purpose	Blog hub with featured posts and tags
API Calls	Child components make their own calls (see Posts, PostDetails).

Posts


Purpose	Paginated post list
API Call	`GET /content/classes?type=blog&page=1&limit=6` or `GET /classes?type=blog&page=1&limit=6`
Auth	API key

PostDetails


Purpose	Single blog post with HTML content
API Call	`GET /content/classes/:id` or `GET /classes/:id`
Auth	API key
Notes	Render HTML content in a WebView or HTML renderer.

SingleTag


Purpose	Posts filtered by tag
API Call	`GET /content/classes?type=blog&tag=<id>&page=1`

8. Store / Products

Products are affiliate items that partners create via the partner portal. Each product belongs to a single client and has a name, description, image, price, and an external buy link.

Store


Purpose	Store hub with featured products and product types
API Calls

Section	Endpoint
Featured products	`GET /products?featured=true&limit=6`
Product types	`GET /products/types`
Latest products	`GET /products?page=1&limit=8&sort=newest`


Auth	API key required

Products


Purpose	Paginated product list
API Call	`GET /products?page=1&limit=8&sort=newest`
Auth	API key required
Query Params	`page`, `limit`, `productType`, `featured`, `search`, `sort` (newest, oldest, price_asc, price_desc, sort_order)
Response	`{ products[], pagination: { page, limit, total, totalPages } }`

ProductDetails


Purpose	Product detail with buy button
API Call	`GET /products/:id`
Auth	API key required
Response	Full product object with `externalUrl`
Notes	"Buy Now" opens `externalUrl` in an external browser. No payment processing in-app.

SingleType


Purpose	Products filtered by type
API Call	`GET /products?productType=<type>&page=1&limit=8`
Auth	API key required

9. Lookup / Filters

Goals


Purpose	Workout goal list
API Call	`GET /classes/categories?type=goal`
Auth	API key

Levels


Purpose	Intensity level list
API Call	`GET /classes/categories?type=level`
Auth	API key

SingleGoal


Purpose	Workouts filtered by goal
API Call	`GET /classes?goal=<id>&page=1` or `GET /content/classes?goal=<id>&page=1`

SingleLevel


Purpose	Workouts filtered by level
API Call	`GET /classes?intensity=<level>&page=1` or `GET /content/classes?intensity=<level>&page=1`

10. Favorites

Favorites (Tab)


Purpose	Tabbed container for WorkoutsFav and DietsFav
API Calls	None directly -- delegates to child components.

Missing Features (Backend Work Needed)

The following features are referenced by app screens but do not yet have backend endpoints:

1. Forgot Password


Screen	ForgotPass
Needed Endpoint	`POST /auth/forgot-password`
Body	`{ email }`
Behaviour	Send password reset email with token link.

2. Profile Photo Upload


Screen	Profile
Needed Endpoint	`POST /auth/profile-photo` or `POST /users/me/photo`
Body	Multipart form with image file
Behaviour	Upload and store avatar URL on user record.

3. Store / Products -- IMPLEMENTED

Products are now available via /products endpoints (API key required) and managed by partners through GET/POST/PUT/DELETE /partner/products in the partner portal.

API Call Quick Reference

A flat reference of every backend call used across all screens:

Public (no auth)

Method	Path	Used By
`GET`	`/app/config`	App launch
`GET`	`/app/join/:code`	VoucherEntry, JoinScreen

API Key Only

Method	Path	Used By
`POST`	`/auth/register`	Register
`POST`	`/auth/login`	Login
`POST`	`/auth/refresh`	Token refresh (auto)
`GET`	`/app/strings`	Terms, About
`POST`	`/onboarding/profile`	ProfileSetup
`POST`	`/onboarding/recommend-coaches`	ProfileSetup
`POST`	`/onboarding/select-coach`	ProfileSetup
`GET`	`/classes`	Workouts, Exercises, Diets, Posts
`GET`	`/classes/:id`	WorkoutDetails, ExerciseDetails, DietDetails, PostDetails
`GET`	`/classes/categories`	Exercises, Equipments, Goals, Levels, Categories
`GET`	`/products`	Store, Products
`GET`	`/products/:id`	ProductDetails
`GET`	`/products/types`	Store (product types)

Bearer Token Required

Method	Path	Used By
`GET`	`/auth/me`	Profile, ManageProfile
`POST`	`/auth/logout`	Profile
`PUT`	`/users/me`	ManageProfile
`DELETE`	`/users/me`	Profile (delete account)
`GET`	`/content/discover`	Home
`GET`	`/content/classes`	Classes, Workouts (alternative)
`GET`	`/content/classes/:id`	ClassDetails (alternative)
`GET`	`/content/search`	SearchWorkout
`GET`	`/content/categories`	Categories (alternative)
`GET`	`/users/me/daily-plan`	Home (today's workout)
`POST`	`/users/me/workout-plan`	WorkoutLoading
`GET`	`/users/me/workout-plan`	MyWorkouts
`GET`	`/users/me/workout-plan/day/:dayId`	SingleDay, Timer
`GET`	`/users/me/nutrition-plan`	CustomDiets
`GET`	`/progress`	MyWorkouts
`POST`	`/progress/workout`	SingleDay, Timer
`POST`	`/progress/nutrition`	Nutrition tracking
`POST`	`/progress/body-metrics`	Body metrics logging
`POST`	`/progress/water`	Water intake logging
`GET`	`/video/access/:classId`	Player, ClassPlayer
`POST`	`/sessions/start`	ClassPlayer
`POST`	`/sessions/:id/progress`	ClassPlayer
`POST`	`/sessions/:id/complete`	ClassPlayer
`GET`	`/sessions/history`	MyWorkouts
`GET`	`/trainers`	Coaches
`GET`	`/trainers/:id`	CoachDetails
`GET`	`/trainers/:id/classes`	CoachDetails
`GET`	`/trainers/:id/services`	CoachDetails
`GET`	`/trainers/:id/availability`	Booking
`POST`	`/trainers/:id/book`	Booking
`GET`	`/my-bookings/summary`	Bookings overview
`GET`	`/my-bookings/sessions`	Bookings list
`GET`	`/live/schedule`	Live classes
`GET`	`/live/my-schedule`	My live schedule
`POST`	`/live/schedule/:classId`	Add to schedule
`DELETE`	`/live/schedule/:classId`	Remove from schedule
`POST`	`/food-scanner/scan-food`	Food scanning
`POST`	`/ai/generate-workout-plan`	AI workout
`POST`	`/ai/generate-nutrition-plan`	AI nutrition
`POST`	`/ai/generate-class-plan`	AI class plan

Notes on `/content/` vs `/classes/`

The backend exposes two route groups that serve similar content:

Route Group	Auth	Scoping	Best For
`/content/*`	API key + bearer	Filtered by client's assigned categories	Authenticated browsing (home, discover)
`/classes/*`	API key only	Filtered by client's assigned categories	Pre-auth browsing, simpler calls

Both return client-scoped content. Use /content/* when the user is logged in (richer features like "continue watching"). Use /classes/* for simpler listing when bearer token is unavailable.

ImageKit URL Transformations

ImageKit provides real-time image transformations via URL parameters. The mobile app uses these to request properly sized and cropped images from the CDN, avoiding layout issues like cropped heads or poorly framed thumbnails.

URL Format

ImageKit URLs follow this pattern:

https://ik.imagekit.io/{imagekit_id}/path/to/image.jpg

Transformations are inserted as a path segment using tr: notation:

https://ik.imagekit.io/{imagekit_id}/tr:{transforms}/path/to/image.jpg

The image is transformed on-the-fly by ImageKit's CDN and cached automatically.

Transformation Parameters

Parameter	Description	Example
`w-{px}`	Width in pixels	`w-320`
`h-{px}`	Height in pixels	`h-400`
`fo-face`	Focus on detected face(s) when cropping	`fo-face`
`fo-auto`	Auto-detect the most important content area	`fo-auto`
`fo-center`	Focus on the center (default behaviour)	`fo-center`
`fo-top`	Focus on the top of the image	`fo-top`
`c-maintain_ratio`	Crop while maintaining aspect ratio (default)	`c-maintain_ratio`
`c-force`	Force exact dimensions, may distort	`c-force`
`c-at_least`	Output is at least the requested size	`c-at_least`
`c-at_max`	Output is at most the requested size	`c-at_max`
`q-{1-100}`	JPEG/WebP quality	`q-80`

Multiple parameters are comma-separated: tr:w-320,h-400,fo-face

Common Presets

Person-centric images where you want to preserve the trainer's face:

Original:  https://ik.imagekit.io/fitgram/fytos/classes/image.jpg
Thumbnail: https://ik.imagekit.io/fitgram/tr:w-320,h-400,fo-face/fytos/classes/image.jpg

Small circular avatars:

https://ik.imagekit.io/fitgram/tr:w-80,h-80,fo-face/fytos/trainers/image.png

Category thumbnails where the subject varies:

https://ik.imagekit.io/fitgram/tr:w-280,h-200,fo-auto/fytos/classes/image.jpg

Client-Side Usage

The app has a utility at src/utils/imagekit.js that appends transforms to ImageKit URLs automatically:

import { ikThumbnail, ikHero, ikAvatar } from '../utils/imagekit';

// Face-focused thumbnail (320x400, fo-face)
<Image source={{ ERROR }} />

// Hero banner (800x400, fo-auto)
<Image source={{ ERROR }} />

// Small avatar (80x80, fo-face)
<Image source={{ ERROR }} />

// Custom transform
import { ikImage } from '../utils/imagekit';
<Image source={{ ERROR }} />

Safe on any URL

Non-ImageKit URLs pass through unchanged, so it is safe to use these helpers on any image URL.

Backend Considerations

Client responsibility

The backend stores and returns original ImageKit URLs without transforms. The client is responsible for appending the transform parameters appropriate for each UI context.

If the backend needs to generate pre-transformed URLs (e.g. for push notifications or emails), use the same tr: path segment format described above.
ImageKit caches transformed images at the CDN edge. First request transforms on-the-fly; subsequent requests are served from cache.
There is no additional cost per unique transformation, but storage of cached variants counts toward the ImageKit plan.