# API Reference

Complete endpoint documentation for the sTvOS v1 API.

The sTvOS v1 API is a RESTful JSON API organised around multi-tenant client scoping. All endpoints are prefixed with /api/v1.


Base URL	`https://api.studiostv.net/api/v1`
Protocol	HTTPS
Format	JSON request and response bodies
Version	`v1` (current, stable)

# Client-Facing APIs

These APIs are used by mobile apps, web frontends, and third-party integrators building on sTvOS.

API Reference

Authentication API

sTvOS supports multiple authentication flows for end users, trainers, and partner staff.

API Reference

Content & Classes API

Browse and discover fitness content, manage live class schedules, and track user viewing sessions. All endpoints require the X-API-Key header. Endpoints marked with also require Authorization: Bearer <token>.

API Reference

User Management & Plans API

Manage user profiles, generate AI-powered fitness plans, view combined daily schedules, and track progress. All endpoints require X-API-Key and Authorization: Bearer <token>.

API Reference

Trainers & Bookings API

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

API Reference

AI Services API

Standalone AI generation, food image scanning with Google Vertex AI, and voice AI coaching with Hume's Empathic Voice Interface. All endpoints require X-API-Key.

# Portal APIs

Dedicated APIs for partner staff and trainer self-service.

API Reference

Partner Portal API

Partner staff manage member access through voucher codes, track usage, and review billing. Most endpoints use Partner JWT authentication (no client API key needed). Voucher management endpoints require the client API key.

# Authentication Overview

Most endpoints require one or more authentication layers:

Method	Header	When to Use
Client API Key	`X-API-Key: <key>`	Every client-scoped request
Bearer Token	`Authorization: Bearer <jwt>`	User-specific operations
Partner JWT	`Authorization: Bearer <jwt>`	Partner portal (no API key needed)

Quick test

Verify your API key works:

curl -H "X-API-Key: your-client-api-key" https://api.studiostv.net/api/v1/health

# Public Endpoints

These endpoints require no authentication:

Method	Path	Description
`GET`	`/health`	Health check with uptime and version
`GET`	`/health/detailed`	Includes memory, platform, Node.js version
`GET`	`/app/config`	Default app configuration and branding
`GET`	`/app/join/:code`	Deep link voucher validation
`POST`	`/invite/check`	Trainer invite code validation
`POST`	`/partner-auth/login`	Partner staff login
`POST`	`/partner-auth/refresh`	Partner token refresh

# Response Envelope

{
  "success": true,
  "data": { ... }
}

{
  "error": "Human-readable description",
  "code": "MACHINE_READABLE_CODE",
  "details": "Additional context"
}

{
  "success": true,
  "data": {
    "items": [ ... ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  }
}

# HTTP Status Codes

Status	Meaning
`200`	Success
`201`	Created
`400`	Bad request -- invalid parameters or body
`401`	Unauthorized -- missing or invalid API key / token
`403`	Forbidden -- insufficient permissions
`404`	Resource not found
`429`	Rate limit exceeded
`500`	Internal server error