Generate Your Training Session
Generating your personalized training session...
❌ Error
📡 API Documentation
▼Use these HTTP endpoints to integrate training session generation into your applications.
http://localhost:3000/api
Check if the API service is running and healthy.
Request:
curl -X GET http://localhost:3000/api/health
Response:
{
"status": "healthy",
"timestamp": "2024-01-15T14:30:00.000Z",
"service": "Training Session Generator API"
}
Generate a personalized football training session.
Required Query Parameters:
| Parameter | Type | Description | Valid Values |
|---|---|---|---|
user_id |
string | User identifier | Any numeric string |
focus_area |
string | Training focus area | "Shooting", "Dribbling", "Passing", etc. |
intensity |
string | Training intensity level | "Low", "Medium", "High", "Extreme" |
player_count |
string | Number of players | "Single", "Double" |
duration |
string | Session duration in minutes | "15" to "120" |
Optional Query Parameters:
| Parameter | Type | Description | Valid Values |
|---|---|---|---|
return_immediately |
string | Return UUID immediately and process in background | "true", "false" (default: "false") |
Request Example:
curl -X GET "http://localhost:3000/api/generate-session?user_id=1&focus_area=Shooting&intensity=Medium&player_count=Single&duration=45"
Request Example (Immediate Return):
curl -X GET "http://localhost:3000/api/generate-session?user_id=1&focus_area=Shooting&intensity=Medium&player_count=Single&duration=45&return_immediately=true"
Success Response (200 OK) - Full Generation:
{
"success": true,
"processing_time_ms": 2500,
"session_id": 42,
"uuid": "13fcd139-3a9d-4b4e-9627-74baae3ea477",
"saved_at": "2024-01-15T14:30:00.000Z",
"session": {
"session_date": "2024-01-15 14:30",
"total_duration": 45.0,
"focus_areas": ["Shooting"],
"intensity_allocation": [
{ "block": "Warmup", "minutes": 9.0 },
{ "block": "Maintenance", "minutes": 6.0 },
{ "block": "Focus", "minutes": 18.0 },
{ "block": "Intensive", "minutes": 9.0 },
{ "block": "Cooldown", "minutes": 3.0 }
],
"blocks": [
{
"name": "Warmup",
"duration": 9.0,
"exercises": [
{
"id": "123",
"title": "Dynamic Warm-up",
"skill": "Movement",
"type": "Single",
"horizontal_video_url": "https://example.com/video.mp4",
"vertical_video_url": "https://example.com/video_vertical.mp4",
"video_thumbnail_url": "https://example.com/thumbnail.jpg",
"rounds": 1.0,
"duration_per_round": 5.0,
"rest_minutes": 1.0,
"transition_minutes": 3.0,
"total_time": 9.0,
"total_time_equation": "(1 * 5) + (1 * 1) + 3 = 9 minutes"
}
]
}
// ... other blocks
]
}
}
Success Response (200 OK) - Immediate Return:
{
"success": true,
"uuid": "13fcd139-3a9d-4b4e-9627-74baae3ea477",
"status": "pending",
"message": "Session generation started. Use the UUID to check status and retrieve the session when ready.",
"processing_time_ms": 15
}
Note: When using immediate return, use the /session/status/ endpoint to monitor progress and /session/ to fetch the completed session.
Retrieve a specific training session by its unique ID.
Request Example:
curl -X GET "http://localhost:3000/api/session/42"
Response:
{
"success": true,
"session": {
"id": 42,
"user_id": 1,
"status": "Generated",
"created_at": "2024-01-15T14:30:00.000Z",
"training_session": { ... },
"generation_metadata": { ... }
}
}
Get a list of training sessions for a specific user.
Request Example:
curl -X GET "http://localhost:3000/api/sessions/user/1?limit=5&offset=0"
Response:
{
"success": true,
"user_id": 1,
"pagination": { "limit": 5, "offset": 0, "count": 3 },
"sessions": [
{
"id": 45,
"user_id": 1,
"status": "Generated",
"created_at": "2024-01-15T16:00:00.000Z",
"session_summary": { ... }
}
]
}
Check the status of a training session by ID or UUID. Use this to monitor session generation progress when using immediate return mode.
Supported Formats:
/session/status/123- Numeric ID/session/status/13fcd139-3a9d-4b4e-9627-74baae3ea477- Direct UUID/session/status/trainingSessionUuid=13fcd139-3a9d-4b4e-9627-74baae3ea477- Named parameter/session/status/training_session_uuid=13fcd139-3a9d-4b4e-9627-74baae3ea477- Snake case parameter/session/status/sessionUuid=13fcd139-3a9d-4b4e-9627-74baae3ea477- Short camelCase parameter/session/status/session_uuid=13fcd139-3a9d-4b4e-9627-74baae3ea477- Short snake_case parameter
Request Example:
curl -X GET "http://localhost:3000/api/session/status/13fcd139-3a9d-4b4e-9627-74baae3ea477"
Response - Session Ready:
{
"success": true,
"uuid": "13fcd139-3a9d-4b4e-9627-74baae3ea477",
"status": "Done",
"session_ready": true,
"message": "Session generation completed successfully. You can now fetch the full session data.",
"created_at": "2024-01-15T14:30:00.000Z",
"updated_at": "2024-01-15T14:30:15.000Z"
}
Response - Still Generating:
{
"success": true,
"uuid": "13fcd139-3a9d-4b4e-9627-74baae3ea477",
"status": "generating",
"session_ready": false,
"message": "Session generation is in progress. Please check again in a few moments.",
"created_at": "2024-01-15T14:30:00.000Z",
"updated_at": "2024-01-15T14:30:10.000Z"
}
Response - Failed:
{
"success": true,
"uuid": "13fcd139-3a9d-4b4e-9627-74baae3ea477",
"status": "Failed",
"session_ready": false,
"message": "Session generation failed.",
"error_details": "Generation timeout after 60 seconds",
"created_at": "2024-01-15T14:30:00.000Z",
"updated_at": "2024-01-15T14:31:00.000Z"
}
Check session status using query parameters. Alternative format for the status endpoint.
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
training_session_uuid |
string | Session UUID (recommended) |
trainingSessionUuid |
string | Session UUID (camelCase format) |
session_uuid |
string | Session UUID (short snake_case format) |
sessionUuid |
string | Session UUID (short camelCase format) |
Request Example:
curl -X GET "http://localhost:3000/api/session/status/?training_session_uuid=13fcd139-3a9d-4b4e-9627-74baae3ea477"
Request Example (Alternative Format):
curl -X GET "http://localhost:3000/api/session/status/?sessionUuid=13fcd139-3a9d-4b4e-9627-74baae3ea477"
Response:
// Same response format as /session/status/:id endpoint above
Wait for session completion and return the full training session data. This endpoint automatically polls the session status until completion (or failure) and returns the complete session when ready.
Supported Formats:
/session/await/123- Numeric ID/session/await/13fcd139-3a9d-4b4e-9627-74baae3ea477- Direct UUID/session/await/trainingSessionUuid=13fcd139-3a9d-4b4e-9627-74baae3ea477- Named parameter/session/await/training_session_uuid=13fcd139-3a9d-4b4e-9627-74baae3ea477- Snake case parameter/session/await/sessionUuid=13fcd139-3a9d-4b4e-9627-74baae3ea477- Short camelCase parameter/session/await/session_uuid=13fcd139-3a9d-4b4e-9627-74baae3ea477- Short snake_case parameter
Behavior:
- Polling Interval: Checks session status every 2 seconds
- Maximum Wait Time: 2 minutes (120 seconds)
- Automatic Completion: Returns full session data when status becomes "Done"
- Error Handling: Returns error details if session fails
- Timeout Protection: Returns timeout error if 2 minutes exceeded
Request Example:
curl -X GET "http://localhost:3000/api/session/await/13fcd139-3a9d-4b4e-9627-74baae3ea477"
Success Response (200 OK) - Session Completed:
{
"success": true,
"waited_ms": 1500,
"session": {
"id": 42,
"user_id": 1,
"status": "Done",
"created_at": "2024-01-15T14:30:00.000Z",
"updated_at": "2024-01-15T14:30:15.000Z",
"uuid": "13fcd139-3a9d-4b4e-9627-74baae3ea477",
"training_session": {
"session_date": "2024-01-15 14:30",
"total_duration": 45.0,
"focus_areas": ["Shooting"],
"blocks": [...]
},
"generation_metadata": {...}
}
}
Error Response (500) - Session Failed:
{
"error": "Session generation failed",
"message": "The training session generation failed during processing",
"waited_ms": 3000,
"error_details": "Generation timeout after 60 seconds",
"session": {
"id": 42,
"user_id": 1,
"status": "Failed",
"created_at": "2024-01-15T14:30:00.000Z",
"updated_at": "2024-01-15T14:31:00.000Z",
"uuid": "13fcd139-3a9d-4b4e-9627-74baae3ea477",
"generation_metadata": {...}
}
}
Timeout Response (408) - Wait Timeout:
{
"error": "Session wait timeout",
"message": "Session did not complete within 120 seconds",
"waited_ms": 120000,
"timeout": true
}
💡 Usage Tips:
- Ideal for: Single-request workflows where you want to wait for completion
- Alternative to: Manual polling with /session/status/ + /session/ endpoints
- Workflow: generate-session?return_immediately=true → /session/await/{uuid}
- Timeout Handling: If timeout occurs, session may still complete - check /session/status/ later
🔧 Integration Examples
JavaScript/Node.js
const axios = require('axios');
async function generateTrainingSession(params) {
try {
const queryParams = new URLSearchParams({
user_id: params.userId,
focus_area: params.focusArea,
intensity: params.intensity,
player_count: params.playerCount,
duration: params.duration.toString()
});
const response = await axios.get(`http://localhost:3000/api/generate-session?${queryParams.toString()}`);
return response.data;
} catch (error) {
console.error('Error generating session:', error.response?.data || error.message);
throw error;
}
}
// Usage
generateTrainingSession({
userId: "1",
focusArea: "Shooting",
intensity: "Medium",
playerCount: "Single",
duration: 45
}).then(session => {
console.log('Generated session:', session);
});
Python
import requests
import json
def generate_training_session(user_id, focus_area, intensity, player_count, duration):
base_url = "http://localhost:3000/api/generate-session"
params = {
"user_id": str(user_id),
"focus_area": focus_area,
"intensity": intensity,
"player_count": player_count,
"duration": str(duration)
}
try:
response = requests.get(base_url, params=params)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as e:
print(f"Error generating session: {e}")
raise
# Usage
session = generate_training_session(
user_id=1,
focus_area="Shooting",
intensity="Medium",
player_count="Single",
duration=45
)
print(json.dumps(session, indent=2))
Immediate Return with Status Polling (JavaScript)
const axios = require('axios');
async function generateSessionWithPolling(params, pollInterval = 2000) {
try {
// Step 1: Start session generation with immediate return
const generateResponse = await axios.get('http://localhost:3000/api/generate-session', {
params: {
...params,
return_immediately: 'true'
}
});
const { uuid } = generateResponse.data;
console.log(`Session started with UUID: ${uuid}`);
// Step 2: Poll for completion
while (true) {
const statusResponse = await axios.get(`http://localhost:3000/api/session/status/`, {
params: { training_session_uuid: uuid }
});
const { status, session_ready, message } = statusResponse.data;
console.log(`Status: ${status} - ${message}`);
if (session_ready) {
// Step 3: Fetch completed session
const sessionResponse = await axios.get(`http://localhost:3000/api/session/`, {
params: { training_session_uuid: uuid }
});
return sessionResponse.data;
}
if (status === 'Failed') {
throw new Error(`Session generation failed: ${statusResponse.data.error_details}`);
}
// Wait before next poll
await new Promise(resolve => setTimeout(resolve, pollInterval));
}
} catch (error) {
console.error('Error in session generation:', error.message);
throw error;
}
}
// Usage
generateSessionWithPolling({
user_id: "1",
focus_area: "Shooting",
intensity: "Medium",
player_count: "Single",
duration: "45"
}).then(session => {
console.log('Session generation completed:', session);
});
Simplified Workflow with Await Endpoint (JavaScript)
const axios = require('axios');
async function generateSessionAndWait(params) {
try {
// Step 1: Start session generation with immediate return
const generateResponse = await axios.get('http://localhost:3000/api/generate-session', {
params: {
...params,
return_immediately: 'true'
}
});
const { uuid } = generateResponse.data;
console.log(`Session started with UUID: ${uuid}`);
// Step 2: Wait for completion using the await endpoint
console.log('Waiting for session completion...');
const awaitResponse = await axios.get(`http://localhost:3000/api/session/await/${uuid}`);
console.log(`Session completed in ${awaitResponse.data.waited_ms}ms`);
return awaitResponse.data;
} catch (error) {
if (error.response?.status === 408) {
console.error('Session wait timeout - check status later');
} else if (error.response?.status === 500) {
console.error('Session generation failed:', error.response.data.error_details);
} else {
console.error('Error:', error.response?.data || error.message);
}
throw error;
}
}
// Usage
generateSessionAndWait({
user_id: "1",
focus_area: "Shooting",
intensity: "Extreme",
player_count: "Single",
duration: "45"
}).then(result => {
console.log('Session ready:', result.session);
}).catch(error => {
console.error('Failed to generate session:', error.message);
});
❌ Common Error Responses
400 Bad Request - Missing Fields:
{
"error": "Missing required fields",
"required": ["user_id", "focus_area", "intensity", "player_count", "duration"]
}
400 Bad Request - Invalid Values:
{
"error": "Invalid intensity",
"valid_values": ["Low", "Medium", "High", "Extreme"]
}
500 Internal Server Error:
{
"error": "Failed to generate training session",
"message": "Detailed error description",
"processing_time_ms": 150
}
📝 Important Notes
- Processing Time: Requests typically take 1-5 seconds due to database queries and AI generation
- Immediate Return: Use
return_immediately=trueto get instant UUID response and poll status for completion - Await Endpoint: Use
/session/await/{uuid}for simplified workflow - automatically waits up to 2 minutes for completion - Background Processing: Sessions with immediate return have a 60-second timeout for generation
- Status Monitoring: Use
/session/status/endpoints to track generation progress in real-time - Multiple Formats: All session endpoints support numeric IDs, UUIDs, and query parameters for maximum flexibility
- Rate Limits: No current rate limits, but be mindful of OpenAI API limits
- Data Requirements: Requires valid PostgreSQL data for the specified user and focus area
- Response Format: All responses include processing time and detailed session structure
📖 For complete documentation with more examples, see API_DOCUMENTATION.md