Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jaimegayo/KERNDOCUMENTATION/llms.txt

Use this file to discover all available pages before exploring further.

The KERN API uses two layers of data models: Pydantic models for request validation and response serialization (defined in app.py and models.py), and SQLAlchemy models for database persistence (defined in models.py).

​
Pydantic request models

These models validate inbound request bodies. Fields marked optional default to None unless a different default is specified.

​
UserCreate

Used by POST /register.
​
username
string
required
Unique display name. Stored in users.username (max 128 chars, unique index).
​
email
string
required
Email address. Stored in users.email (max 255 chars, unique index).
​
password
string
required
Plain-text password. Hashed with SHA-256 before storage. Never persisted in plain text.
​
full_name
string
User’s full name. Optional. Stored in users.full_name (max 100 chars).
​
phone
string
Phone number. Optional. Stored in users.phone (max 50 chars).

​
LoginRequest

Used by POST /login.
​
email
string
required
The registered email address.
​
password
string
required
Plain-text password. The API hashes it and compares with the stored hash.

​
QuizCompletion

Used by POST /users/complete-quiz.
​
assigned_routine
string
required
The training plan chosen by the user. One of: "Full Body", "PPL (Push Pull Leg)", "Torso-Pierna".

​
AvatarUpdate

Used by PUT /users/avatar.
​
avatar_url
string
required
Public URL of the new avatar image.

​
UsernameUpdate

Used by PUT /users/update_name.
​
username
string
required
The desired new username. Must not be taken by another account.

​
WorkoutSessionCreate

Used by POST /workouts/finish.
​
routine_name
string
required
Name of the routine that was performed.
​
duration_seconds
integer
required
Session duration in seconds.
​
total_volume
number
required
Total volume (kg) calculated as sum of kilos × reps for all sets.
​
steps
integer
default:"0"
Steps recorded during the session by the Android StepCounterService.
​
data_json
object[]
required
Full snapshot of all exercises and sets performed. Stored verbatim in the workout_sessions.data_json JSON column.

​
RoutineCreate

Used by POST /routines/create and PUT /routines/{routine_id}.
​
user_id
integer
required
ID of the authenticated user who owns the routine.
​
nombre
string
required
Routine display name.
​
ejercicios
object[]
required
List of exercises to include. Each item uses the RoutineExerciseCreate schema.

​
SerieCreate

Nested within RoutineCreate.ejercicios[].series.
​
numSerie
integer
required
Set number, starting at 1.
​
kilos
number
required
Weight in kilograms. Use 0 as the initial placeholder.
​
reps
integer
required
Target or actual repetitions.

​
Pydantic response models

These models shape the JSON returned by the API.

​
LoginResponse

Returned by POST /register, POST /login, and PUT /users/update_name.
​
accessToken
string
required
Signed JWT token (HS256). Valid for 30 minutes. Field name is accessToken (camelCase) due to a Pydantic Field(alias="accessToken") on the underlying access_token attribute.
​
token_type
string
required
Always "bearer".
​
user
object
required
The authenticated user’s data. See UserData below.

​
UserData

Returned as the user field in LoginResponse and directly by all /users/me, /users/avatar, and /users/complete-quiz endpoints.
​
id
integer
Auto-incremented user ID.
​
username
string
required
Display name.
​
email
string
Email address.
​
full_name
string
Full name. null if not set.
​
phone
string
Phone number. null if not set.
​
avatar_url
string
Avatar image URL. null if not set.
​
role
string
default:"user"
Account role.
​
bio
string
Short biography. null if not set.
​
has_completed_quiz
boolean
default:"false"
Whether the onboarding quiz has been completed.
​
assigned_routine
string
Routine type selected during the quiz. null until the quiz is completed.
​
created_at
string
ISO 8601 account creation timestamp.
​
disabled
boolean
Whether the account is disabled.

​
UserStats

Returned by GET /users/stats.
​
total_workouts
integer
required
Total number of completed workout sessions.
​
total_steps
integer
required
Sum of all steps across all sessions.
​
training_days
string[]
required
Unique calendar dates ("YYYY-MM-DD") with at least one recorded session.

​
Exercise

Returned by all /exercises/* endpoints. Defined in app.py (not models.py) as a Pydantic model that validates data loaded from JSON files.
​
id
integer
required
Unique exercise ID within its JSON catalog file.
​
name
string
required
Exercise name. This is the canonical key used to match exercises between the routine and workout session data.
​
primary_muscle
string
required
Primary muscle group (e.g., "Pecho", "Espalda", "Cuádriceps").
​
movement_pattern
string
required
Movement category (e.g., "Empuje horizontal", "Tracción vertical"). Used by the auto-routine generator.
​
equipment
string
required
Equipment required.
​
instructions
string
required
Full execution instructions.
​
pro_tips
string[]
required
Coaching cues.
​
common_mistakes
string[]
required
Common errors to avoid.
​
video_url
string
Optional demonstration video URL. null if unavailable.

​
SQLAlchemy database models

These are the ORM classes in models.py that map to database tables. The database is managed by SQLAlchemy with async support via AsyncSession.

​
User — table: users

​
id
Integer
required
Primary key. Auto-incremented.
​
username
String(128)
required
Unique, indexed. The JWT sub claim is set to this value.
​
email
String(255)
required
Unique, indexed.
​
hashed_password
String(256)
required
SHA-256 hex digest. Never returned by any API endpoint.
​
full_name
String(100)
Nullable.
​
phone
String(50)
Nullable.
​
avatar_url
String(255)
Nullable.
​
role
String(50)
default:"user"
Account role.
​
bio
String(500)
Nullable.
​
has_completed_quiz
Boolean
default:"false"
Set to true by POST /users/complete-quiz.
​
assigned_routine
String(100)
Nullable. Set by POST /users/complete-quiz.
​
disabled
Boolean
default:"false"
When true, all authenticated requests return 400 Usuario inactivo.
​
created_at
DateTime(timezone=True)
Server-side default via func.now().

​
Routine — table: routines

​
id
Integer
required
Primary key. Auto-incremented.
​
user_id
Integer
required
Foreign key → users.id. Not nullable.
​
name
String(255)
required
Routine display name. Not nullable.
​
created_at
DateTime(timezone=True)
Server-side default via func.now().
Relationships:
  • owner → User (many-to-one)
  • exercises → RoutineExercise[] (one-to-many, cascade="all, delete-orphan")

​
RoutineExercise — table: routine_exercises

​
id
Integer
required
Primary key. Auto-incremented.
​
routine_id
Integer
required
Foreign key → routines.id.
​
exercise_name
String(255)
required
Exercise name as a denormalized string. Must match the catalog name for instruction lookups.
​
series
JSON
required
Array of set objects ([{numSerie, kilos, reps}]) stored as a JSON column. Not nullable.
Relationships:
  • routine → Routine (many-to-one)

​
WorkoutSession — table: workout_sessions

​
id
Integer
required
Primary key. Auto-incremented.
​
user_id
Integer
required
Foreign key → users.id. Not nullable.
​
routine_name
String(255)
required
Name of the routine performed. Used for case-insensitive matching in the progression query.
​
duration_seconds
Integer
required
Session duration. Not nullable.
​
total_volume
Float
default:"0.0"
Total training volume in kg.
​
steps
Integer
default:"0"
Steps recorded during the session.
​
data_json
JSON
required
Full exercise + series snapshot. Read back by GET /routines/{id} to populate progression fields.
​
created_at
DateTime(timezone=True)
Server-side default via func.now(). Used for ordering history and deduplicating training_days.
Relationships:
  • owner → User (many-to-one)

Build docs developers (and LLMs) love

Get started for freeTalk to us