Personalized Training Session Generator

Generate Your Training Session

User ID:

Focus Area (Optional):

Intensity:

Player Count:

Duration (minutes):

📡 API Documentation

▼

Use these HTTP endpoints to integrate training session generation into your applications.

Base URL: http://localhost:3000/api

GET /health

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"
}

GET /generate-session

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.

GET /session/:id

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 /sessions/user/:userId

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": { ... }
    }
  ]
}

GET /session/status/:id

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"
}

GET /session/status/

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

GET /session/await/:id

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=true to 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

Generate Your Training Session

❌ Error

📡 API Documentation

Request:

Response:

Required Query Parameters:

Optional Query Parameters:

Request Example:

Request Example (Immediate Return):

Success Response (200 OK) - Full Generation:

Success Response (200 OK) - Immediate Return:

Request Example:

Response:

Request Example:

Response:

Supported Formats:

Request Example:

Response - Session Ready:

Response - Still Generating:

Response - Failed:

Query Parameters:

Request Example:

Request Example (Alternative Format):

Response:

Supported Formats:

Behavior:

Request Example:

Success Response (200 OK) - Session Completed:

Error Response (500) - Session Failed:

Timeout Response (408) - Wait Timeout:

💡 Usage Tips:

🔧 Integration Examples

JavaScript/Node.js

Python

Immediate Return with Status Polling (JavaScript)

Simplified Workflow with Await Endpoint (JavaScript)

❌ Common Error Responses

400 Bad Request - Missing Fields:

400 Bad Request - Invalid Values:

500 Internal Server Error:

📝 Important Notes

🏃‍♀️ Your Training Session

Time Allocation

Training Blocks