0 people focusing right now

POST /api/pomodoro/submit

Log a completed Pomodoro session

Back to API Docs

Submit a completed Pomodoro session with full POF scoring and team notifications.

⚠️ Critical for Third-Party Developers: This exact format prevents HTTP 500 errors. Any deviation in field names, data types, or missing required fields will cause server errors.
Endpoint URL
POST https://game.regardingwork.com/api/pomodoro/submit
Authentication
JWT Bearer token required

📤 Request

Headers
Content-Type: application/json
Authorization: Bearer <your_jwt_token>
Request Body
{
  "start_time": "2025-08-17T14:30:00Z",   // Required: Session start time (ISO 8601)
  "end_time": "2025-08-17T14:55:00Z",     // Required: Session end time (ISO 8601)
  "duration": 25,                           // Required: Duration in minutes
  "category": "Work",                       // Required: Category name
  "project": "team_2",                      // Required: Project identifier (see format below)
  "note": "Productive session",             // Required: Session notes (use "note", not "notes")
  "source": "mac_app",                      // Required: Source app identifier
  "session_id": "39440f6c-26cb-434d-a024-14caef17f3e0"  // Required: Unique session UUID
}
Common Issues
  • Using "notes" instead of "note" → Use "note"
  • Missing required fields → All fields above are required
  • Incorrect project format → Use "team_X" for team projects, project name for personal
  • Wrong data types → duration must be number, session_id must be UUID string

🔒 Enhanced Security Requirements

  • Time Validation: start_time and end_time are required to prevent timing manipulation
  • Duration Check: Duration must match the time difference (within 1-minute tolerance)
  • Source Tracking: Include X-App-Identifier header (e.g., "RegardingWork-Mac-v1.0") or source parameter

✅ Response (201 Created)

{
  "success": true,
  "session_id": "451",
  "message": "Pomodoro session logged successfully",
  "pomodoro": {
    "id": 451,
    "duration": 25,
    "category": "Testing",
    "project": "API Enhancement",
    "source": "mac_app",
    "start_time": "2025-08-17T03:00:00Z",
    "end_time": "2025-08-17T03:25:00Z",
    "points": 1.0,
    "date": "2025-08-17",
    "pof_score": 100,
    "trustworthiness": "High"
  }
}
Success Check: Apps should check for success: true to confirm successful sync. The session_id contains the database ID for the created session.

❌ Error Responses

400 Bad Request
{
  "error": "Missing required fields"
}
500 Internal Server Error
{
  "error": "Internal server error"
}

💻 Code Examples

JavaScript (Fetch) - EXACT format required
const token = localStorage.getItem('jwt_token');
const sessionId = generateUUID(); // Generate unique session ID

const response = await fetch('https://game.regardingwork.com/api/pomodoro/submit', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`,
    'X-App-Identifier': 'RegardingWork-Mac-v1.0'
  },
  body: JSON.stringify({
    "start_time": "2025-08-23T14:30:00.000Z",
    "end_time": "2025-08-23T14:55:00.000Z",
    "duration": 25,
    "category": "Programming",
    "project": "Mac App Development",
    "note": "Implemented API sync",  // Use "note", not "notes"
    "source": "mac_app",
    "session_id": sessionId
  })
});

// Check for successful response
const result = await response.json();
if (result.success) {
  console.log(`Session saved! ID: ${result.session_id}`);
} else {
  console.error('Session submission failed');
}

🔗 Related Endpoints

Session Flow
Project Management