Sessions, Profile & Limits
Chat sessions are persistent, named, durable records — messages survive restarts and can be reloaded any time. A session belongs to the authenticated user; other users cannot read, modify, or delete it.
Endpoints:
| Method | Path | Description |
GET | /api/trainer/history | Load a conversation's message history |
POST | /api/trainer/sessions | Create a named chat session ({ "title": "Leg day planning" }, max 255 chars). 201 with { "session_id", "title", "created_at" } |
GET | /api/trainer/sessions | List the user's sessions, most recently active first: { "sessions": [{ "session_id", "title", "last_message_at", "created_at" }] } |
PATCH | /api/trainer/sessions/:id | Rename a session |
DELETE | /api/trainer/sessions/:id | Delete a session (also clears its in-progress planning state) |
GET | /api/trainer/profile | Get the stored fitness profile (404 if none yet) |
PUT | /api/trainer/profile | Create or replace the fitness profile. Send the full object: omitted fields are cleared, except workout_days_per_week and workout_days, which keep their stored value. preferred_duration_minutes is learned from chat and is not changed by this call on an existing profile |
History (GET /api/trainer/history?session_id=…&limit=50, limit capped at 100): use it to restore chat UI state on app startup. Assistant messages carry metadata.intent, metadata.action, and, when the turn produced a plan, the full metadata.workout_plan, so you can re-render plans from history alone. Without session_id it loads the user's most recently active session. If the user has no sessions yet the response is { "messages": [] }; it never creates a session.
1{
2 "conversation_id": "9c1e37a2-…",
3 "title": "New Chat",
4 "messages": [
5 { "role": "user", "content": "make me a chest workout", "created_at": "2026-07-14T10:00:00Z" },
6 {
7 "role": "assistant",
8 "content": "Here's your chest workout! …",
9 "metadata": { "intent": "CREATE_WORKOUT", "action": "WORKOUT_UPDATED", "workout_plan": { } },
10 "created_at": "2026-07-14T10:00:05Z"
11 }
12 ]
13}Rate limits:
| Limit | Scope | On exceed |
| 50 workout generations / day | per user (resets at UTC midnight) | 429 |
| 50 refinements / workout | per workout plan | 429 — confirm the current plan or start a new workout |
| 50 chat sessions | per user | 400 on session create |
| Company-level daily quota | per company | 429 |
Undo/redo do not count against the refinement limit. Higher limits are available — contact KinesteX.