POST /api/session/start

Initialize a new focus session with planning data

Start a new focus session and capture planning data for enhanced POF scoring and analytics.

Event-Driven Architecture: This creates a PreSession record that links to completed Pomodoro sessions for enhanced tracking.

Endpoint URL

POST https://game.regardingwork.com/api/session/start

Authentication

JWT Bearer token required

📤 Request

Headers

Content-Type: application/json
Authorization: Bearer <your_jwt_token>

Request Body

{
  "session_id": "39440f6c-26cb-434d-a024-14caef17f3e0",  // Required: Unique UUID for session
  "planned_duration": 45,                               // Required: Planned duration in minutes
  "category": "Programming",                            // Required: Work category
  "project": "Mac App Development",                     // Optional: Project name or "team_X" format
  "planning_notes": "Implement API sync functionality", // Optional: Pre-session planning notes
  "goals": "Complete user authentication flow",         // Optional: Session goals
  "energy_level": 8,                                   // Optional: User energy 1-10
  "source": "mac_app",                                 // Required: Source app identifier
  "app_version": "1.2.3",                             // Optional: App version for analytics
  "project_id": 47,                                    // Optional: Personal project ID
  "team_project_id": 12                                // Optional: Team project ID
}

✅ Response (201 Created)

{
  "success": true,
  "session_id": "39440f6c-26cb-434d-a024-14caef17f3e0",
  "message": "Session started successfully",
  "pre_session": {
    "id": 123,
    "session_id": "39440f6c-26cb-434d-a024-14caef17f3e0",
    "planned_duration": 45,
    "category": "Programming",
    "project": "Mac App Development",
    "planning_notes": "Implement API sync functionality",
    "goals": "Complete user authentication flow",
    "energy_level": 8,
    "source": "mac_app",
    "created_at": "2025-08-24T15:30:00Z"
  },
  "next_steps": {
    "timer_start": "Start your focus timer now",
    "completion_endpoint": "/api/pomodoro/submit",
    "cancellation_endpoint": "/api/session/cancel"
  }
}

🎯 Planning Data Benefits

Enhanced POF Scoring

Planning bonus points for pre-session data
Goal achievement tracking
Energy level correlation analysis
Improved session quality metrics

Analytics & Insights

Comprehensive session timeline
Planning vs execution analysis
Energy level patterns
Goal completion rates

❌ Error Responses

400 Bad Request

{
  "error": "Missing required fields: session_id, planned_duration, category"
}

409 Conflict

{
  "error": "Session ID already exists. Use a unique UUID."
}

💻 Code Examples

JavaScript (Fetch)

const token = localStorage.getItem('jwt_token');
const sessionId = crypto.randomUUID(); // Generate unique session ID

const response = await fetch('https://game.regardingwork.com/api/session/start', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    session_id: sessionId,
    planned_duration: 45,
    category: "Programming",
    project: "Mac App Development",
    planning_notes: "Implement API sync functionality",
    goals: "Complete user authentication flow",
    energy_level: 8,
    source: "mac_app",
    app_version: "1.2.3"
  })
});

const result = await response.json();
if (result.success) {
  console.log(`Session started! ID: ${result.session_id}`);
  // Start your timer here
}