Supernova

Workout Schema

API documentation for creating Supernova workouts

← Home

📦Workout Object

Overview

A Workout contains one or more ExerciseGroups. Each group can have one exercise (standard) or multiple exercises (superset). Exercises within a group are performed back-to-back before rest.

Workout Interface
interface Workout {
  uuid: string;              // auto-generated
  name: string;
  exerciseGroups: ExerciseGroup[];
  estimatedMinutes?: number;
  
  // Metadata
  description?: string;
  category?: WorkoutCategory;
  difficulty?: WorkoutDifficulty;
  equipment?: WorkoutEquipment[];
  focus?: WorkoutFocus[];
  tags?: string[];
  curator?: string;
  
  // Video-guided workouts
  videoUrl?: string;
  videoStartOffset?: number;
  guidanceType?: 'video' | 'audio' | 'none';
}
FieldTypeRequiredDescription
uuidstringYes*Unique identifier (auto-generated by API)
namestringYesWorkout name (e.g., "Push Day")
exerciseGroupsExerciseGroup[]YesOrdered list of exercise groups
descriptionstringNoWorkout description
categoryWorkoutCategoryNoPrimary category (strength, yoga, etc.)
difficultyWorkoutDifficultyNobeginner | intermediate | advanced
equipmentWorkoutEquipment[]NoEquipment required
focusWorkoutFocus[]NoTarget body areas
tagsstring[]NoSearchable tags
videoUrlstringNoYouTube URL for video-guided workouts
videoStartOffsetnumberNoSeconds to skip at video start
guidanceTypeGuidanceTypeNo'video' | 'audio' | 'none'

🏋️Exercise Object

Exercise Interface
interface Exercise {
  uuid: string;              // auto-generated (not provided by user)
  name: string;
  sets: number;
  restLength: number;        // seconds between sets
  reps?: number;             // reps per set
  weight?: number;           // lbs or kg
  duration?: number;         // seconds (for timed exercises)
  notes?: string;            // form cues, instructions
  link?: string;             // video demo URL
  tags?: string[];
  videoTimestamp?: number;   // for video-guided workouts
}
FieldTypeRequiredDescription
uuidstringYes*Unique identifier (auto-generated)
namestringYesExercise name (e.g., "Bench Press")
setsnumberYesNumber of sets
restLengthnumberYesRest between sets in seconds (default: 60)
repsnumberNo*Target reps per set (use for rep-based exercises like squats, curls)
durationnumberNo*Seconds per set (use for timed exercises like planks, stretches, holds)
weightnumberNoWeight in lbs/kg
notesstringNoBrief form cues (e.g., "squeeze at top", "control descent")
linkstringNoYouTube URL for exercise demonstration
tagsstring[]NoSearchable tags
videoTimestampnumberNoStart time in video (seconds) - for video workouts

Reps vs Duration

Use reps for rep-based exercises (bench press, squats, curls) andduration for timed exercises (planks, wall sits, stretches). Each exercise should have one or the other, not both.

🔗Exercise Groups (Supersets)

Supersets

An ExerciseGroup with 2+ exercises creates a superset. Exercises in a superset are performed consecutively without rest between them. Rest is taken after completing all exercises in the group.

ExerciseGroup Interface
interface ExerciseGroup {
  uuid: string;              // auto-generated
  exercises: Exercise[];     // 1 = single, 2+ = superset
  name?: string;             // optional group name
  restLength?: number;       // rest after completing group
}

📚Routine Object (Multi-Day Programs)

What is a Routine?

A Routine is a collection of multiple workouts designed to be cycled through over time (e.g., "Push/Pull/Legs", "5-Day Split", "12-Week Program"). When users complete a workout from a routine, the app automatically queues the next one.

Routine Interface
interface Routine {
  name: string;              // e.g., "Push/Pull/Legs"
  description?: string;      // program description
  workouts: Workout[];       // array of workouts in sequence
  sessionsPerWeek?: number;  // recommended frequency
}
FieldTypeRequiredDescription
namestringYesRoutine name (e.g., "Push/Pull/Legs")
descriptionstringNoDescription of the program
workoutsWorkout[]YesArray of workouts in the routine
sessionsPerWeeknumberNoRecommended sessions per week

When to use Routine vs Single Workout

Use a single Workout for standalone sessions. Use a Routine when creating multi-day programs where workouts are meant to be done in sequence. The AI should output a Routine when the user requests a "program", "split", "plan", or multi-day workout schedule.

📋Enum Values

WorkoutCategory

'stretch'Stretch
'yoga'Yoga
'pilates'Pilates
'meditation'Meditation
'warmup'Warm Up
'cooldown'Cool Down
'strength'Strength
'mobility'Mobility
'cardio-bike'Cardio (Bike)
'cardio-run'Cardio (Run)
'cardio-other'Cardio (Other)
'physiotherapy'Physiotherapy
'breathwork'Breathwork
'hiit'HIIT

WorkoutEquipment

'none'None (Bodyweight)
'dumbbells'Dumbbells
'kettlebell'Kettlebell
'resistance-bands'Resistance Bands
'bench'Bench
'barbell'Barbell
'pull-up-bar'Pull-up Bar
'gym'Gym

WorkoutFocus

'full-body'Full Body
'upper-body'Upper Body
'lower-body'Lower Body
'core'Core
'back'Back
'chest'Chest
'arms'Arms
'shoulders'Shoulders
'legs'Legs
'glutes'Glutes
'cardio'Cardio
'posture'Posture
'other'Other

WorkoutDifficulty

'beginner'Beginner
'intermediate'Intermediate
'advanced'Advanced

💡Examples

Simple Workout (3 exercises)
{
  "name": "Quick Upper Body",
  "category": "strength",
  "difficulty": "intermediate",
  "equipment": ["dumbbells"],
  "focus": ["upper-body", "chest", "arms"],
  "exerciseGroups": [
    {
      "exercises": [{
        "name": "Dumbbell Bench Press",
        "sets": 3,
        "reps": 10,
        "restLength": 90,
        "weight": 40,
        "notes": "Control descent, pause at chest",
        "link": "https://youtube.com/watch?v=VmB1G1K7v94"
      }]
    },
    {
      "exercises": [{
        "name": "Bent Over Rows",
        "sets": 3,
        "reps": 12,
        "restLength": 60,
        "weight": 35,
        "notes": "Squeeze shoulder blades together"
      }]
    },
    {
      "exercises": [{
        "name": "Plank",
        "sets": 3,
        "duration": 45,
        "restLength": 30,
        "notes": "Keep hips level, engage core"
      }]
    }
  ]
}
Workout with Superset
{
  "name": "Push Day with Supersets",
  "category": "strength",
  "difficulty": "advanced",
  "equipment": ["dumbbells", "bench"],
  "focus": ["chest", "shoulders", "arms"],
  "exerciseGroups": [
    {
      "name": "Chest Superset",
      "exercises": [
        {
          "name": "Incline Dumbbell Press",
          "sets": 4,
          "reps": 10,
          "restLength": 0,
          "weight": 45,
          "notes": "30-45 degree angle, full ROM"
        },
        {
          "name": "Dumbbell Flyes",
          "sets": 4,
          "reps": 12,
          "restLength": 90,
          "notes": "Slight bend in elbows, stretch at bottom"
        }
      ]
    },
    {
      "exercises": [{
        "name": "Overhead Press",
        "sets": 4,
        "reps": 8,
        "restLength": 120,
        "weight": 40,
        "notes": "Brace core, press straight up",
        "link": "https://youtube.com/watch?v=qEwKCR5JCog"
      }]
    }
  ]
}
Video-Guided Workout
{
  "name": "30-Min HIIT Cardio",
  "category": "hiit",
  "difficulty": "intermediate",
  "equipment": ["none"],
  "focus": ["full-body", "cardio"],
  "guidanceType": "video",
  "videoUrl": "https://www.youtube.com/watch?v=example",
  "videoStartOffset": 45,
  "exerciseGroups": [
    {
      "exercises": [{
        "name": "Jumping Jacks",
        "sets": 1,
        "duration": 45,
        "restLength": 15,
        "videoTimestamp": 45
      }]
    },
    {
      "exercises": [{
        "name": "High Knees",
        "sets": 1,
        "duration": 45,
        "restLength": 15,
        "videoTimestamp": 105
      }]
    }
  ]
}
Multi-Day Routine (Push/Pull/Legs)
{
  "name": "Push/Pull/Legs",
  "description": "Classic 3-day split for building muscle. Cycle through these workouts, training 3-6 days per week.",
  "sessionsPerWeek": 6,
  "workouts": [
    {
      "name": "Push Day",
      "category": "strength",
      "difficulty": "intermediate",
      "equipment": ["dumbbells", "bench"],
      "focus": ["chest", "shoulders", "arms"],
      "exerciseGroups": [
        {
          "exercises": [{
            "name": "Dumbbell Bench Press",
            "sets": 4,
            "reps": 10,
            "restLength": 90
          }]
        },
        {
          "exercises": [{
            "name": "Overhead Press",
            "sets": 3,
            "reps": 10,
            "restLength": 60
          }]
        },
        {
          "exercises": [{
            "name": "Tricep Dips",
            "sets": 3,
            "reps": 12,
            "restLength": 60
          }]
        }
      ]
    },
    {
      "name": "Pull Day",
      "category": "strength",
      "difficulty": "intermediate",
      "equipment": ["dumbbells", "pull-up-bar"],
      "focus": ["back", "arms"],
      "exerciseGroups": [
        {
          "exercises": [{
            "name": "Pull-ups",
            "sets": 4,
            "reps": 8,
            "restLength": 90
          }]
        },
        {
          "exercises": [{
            "name": "Dumbbell Rows",
            "sets": 3,
            "reps": 10,
            "restLength": 60
          }]
        },
        {
          "exercises": [{
            "name": "Bicep Curls",
            "sets": 3,
            "reps": 12,
            "restLength": 45
          }]
        }
      ]
    },
    {
      "name": "Leg Day",
      "category": "strength",
      "difficulty": "intermediate",
      "equipment": ["dumbbells"],
      "focus": ["legs", "glutes"],
      "exerciseGroups": [
        {
          "exercises": [{
            "name": "Goblet Squats",
            "sets": 4,
            "reps": 12,
            "restLength": 90
          }]
        },
        {
          "exercises": [{
            "name": "Romanian Deadlifts",
            "sets": 3,
            "reps": 10,
            "restLength": 60
          }]
        },
        {
          "exercises": [{
            "name": "Walking Lunges",
            "sets": 3,
            "reps": 12,
            "restLength": 60,
            "notes": "12 reps per leg"
          }]
        }
      ]
    }
  ]
}

📲Importing into Supernova

Multiple Ways to Import

You can import workouts and routines directly into the Supernova app using JSON - no API required. This works completely offline!

1. Paste JSON Directly

In the app, tap Add Workout → Paste a workout and paste any valid workout or routine JSON from your clipboard. The app will parse it and create the workout(s) instantly.

2. Scan QR Codes

Generate a QR code from your workout JSON and scan it in the app via Add Workout → Scan a workout. Works offline - the workout data is embedded directly in the QR code.

QR Code Format

For smaller QR codes, Supernova uses gzip compression + base64 encoding. The QR content should be a URL like: supernova://workout/create?shared=COMPRESSED_DATA

For quick testing, you can also encode raw JSON directly as base64 in the QR code - the app will auto-detect the format.

3. Share Links

Share workout links that open directly in the app: https://supernova.training/w/ID or deep links: supernova://workout/create?shared=DATA

Supported Formats

Single Workout{ name, exerciseGroups }
Workout Array[{ ... }, { ... }]
Flat Routine{ name, workouts: [...] }
Shared Routine{ routine, workouts }

🔌API Endpoint

Coming Soon

Public API coming soon.

🤖AI Prompt Template

For ChatGPT, Claude, etc.

Copy this prompt template to generate valid Supernova workout JSON. The AI will output either a single workout or a multi-workout routine depending on what you request. Paste the JSON directly into the workout builder to import.

Prompt Template
You are generating workouts for the Supernova Training app.

## OUTPUT FORMAT

For a SINGLE WORKOUT, output:
{
  "name": "Workout Name",
  "category": "strength",
  "difficulty": "intermediate",
  "equipment": ["dumbbells"],
  "focus": ["upper-body"],
  "description": "Optional description",
  "exerciseGroups": [
    {
      "exercises": [{
        "name": "Dumbbell Bench Press",
        "sets": 3,
        "reps": 10,
        "restLength": 90,
        "notes": "Control the descent, pause at bottom",
        "link": "https://youtube.com/watch?v=example"
      }]
    },
    {
      "exercises": [{
        "name": "Plank",
        "sets": 3,
        "reps": null,
        "duration": 45,
        "restLength": 30,
        "notes": "Keep hips level, squeeze glutes"
      }]
    }
  ]
}

For a MULTI-DAY ROUTINE (program, split, plan), output:
{
  "name": "Routine Name",
  "description": "Program description",
  "sessionsPerWeek": 4,
  "workouts": [
    { /* First workout - same structure as single workout */ },
    { /* Second workout */ },
    { /* etc... */ }
  ]
}

## WHEN TO USE EACH FORMAT

- Single Workout: "Create a chest workout", "Give me a 20-min HIIT session"
- Routine (multiple workouts): "Create a PPL split", "Design a 4-day program", "Build me a weekly plan"

## ENUM VALUES

CATEGORY: stretch, yoga, pilates, meditation, warmup, cooldown, strength, mobility, cardio-bike, cardio-run, cardio-other, physiotherapy, breathwork, hiit

EQUIPMENT: none, dumbbells, kettlebell, resistance-bands, bench, barbell, pull-up-bar, gym

FOCUS: full-body, upper-body, lower-body, core, back, chest, arms, shoulders, legs, glutes, cardio, posture, other

DIFFICULTY: beginner, intermediate, advanced

## EXERCISE FIELDS

- name (required): Exercise name
- sets (required): Number of sets
- restLength (required): Rest in seconds between sets
- reps: Target reps per set (use for rep-based exercises)
- duration: Seconds per set (use for timed exercises like planks, stretches, holds)
- notes: Brief form cues or reminders (keep concise)
- link: YouTube video URL for exercise demo (include where helpful)
- weight: Suggested weight (optional)

IMPORTANT:
- Use EITHER reps OR duration, never both. Set the other to null.
- reps = rep-based exercises (bench press, squats, curls)
- duration = timed exercises (planks, wall sits, stretches, holds)

For SUPERSETS: Put multiple exercises in the same group's exercises array.

## RULES

- Output ONLY valid JSON, no markdown code blocks or explanation
- Every exercise needs: name, sets, restLength, and either reps or duration
- Include video links where helpful for form guidance
- Keep notes short and actionable (form cues, not full instructions)
- Use practical rest times (30-120s typical)
- Each workout in a routine should have its own category/equipment/focus