PUT /api/user/preferences

Update user preferences and settings

Back to API Docs

Update user preferences including session durations, daily goals, themes, and notification settings.

Sync Friendly: Changes sync across all user's devices and platforms automatically.

Endpoint URL

PUT https://game.regardingwork.com/api/user/preferences

Authentication

JWT Bearer token required

📤 Request

Headers

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

Request Body (Partial Update Supported)

{
  "daily_goal": 8,                    // Optional: Sessions per day target (1-20)
  "default_duration": 45,             // Optional: Default session minutes (5-120)
  "short_break_duration": 5,          // Optional: Short break minutes (1-30)
  "long_break_duration": 20,          // Optional: Long break minutes (5-60)
  "notification_sound": "chime",      // Optional: "chime", "bell", "soft", "none"
  "theme_preference": "dark",         // Optional: "light", "dark", "auto"
  "timezone": "America/New_York",     // Optional: Valid timezone identifier
  "public_leaderboard": true,         // Optional: Show in public leaderboards
  "email_notifications": false,       // Optional: Receive email notifications
  "slack_notifications": true,        // Optional: Team Slack notifications
  "auto_start_breaks": false,         // Optional: Automatically start break timers
  "focus_mode": "strict"              // Optional: "relaxed", "normal", "strict"
}

Partial Updates: You only need to include the preferences you want to change. Existing preferences remain unchanged.

⚙️ Preference Options

Session Settings

daily_goal: 1-20 sessions (recommended: 4-8)
default_duration: 5-120 minutes (popular: 25, 45, 90)
break_durations: Short (1-30), Long (5-60)
auto_start_breaks: Timer convenience

Experience Settings

notification_sound: Audio feedback options
theme_preference: Visual interface style
focus_mode: Distraction blocking level
public_leaderboard: Privacy control

✅ Response (200 OK)

{
  "success": true,
  "message": "Preferences updated successfully",
  "updated_preferences": {
    "daily_goal": 8,
    "default_duration": 45,
    "short_break_duration": 5,
    "long_break_duration": 20,
    "notification_sound": "chime",
    "theme_preference": "dark",
    "timezone": "America/New_York",
    "public_leaderboard": true,
    "email_notifications": false,
    "slack_notifications": true,
    "auto_start_breaks": false,
    "focus_mode": "strict"
  },
  "sync_status": {
    "devices_notified": 3,
    "last_sync": "2025-08-24T15:30:45Z"
  }
}

❌ Error Responses

400 Bad Request

{
  "error": "Invalid preference value",
  "details": "daily_goal must be between 1 and 20"
}

422 Validation Error

{
  "error": "Invalid timezone",
  "details": "Timezone 'Invalid/Zone' not recognized"
}

💻 Code Examples

JavaScript (Fetch) - Update Timer Preferences

const token = localStorage.getItem('jwt_token');

// Update just the session duration and daily goal
const response = await fetch('https://game.regardingwork.com/api/user/preferences', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    default_duration: 45,
    daily_goal: 6,
    notification_sound: "chime"
  })
});

const result = await response.json();
if (result.success) {
  console.log('Preferences updated!');
  console.log(`Synced to ${result.sync_status.devices_notified} devices`);
}

JavaScript - Theme and Privacy Settings

// Update appearance and privacy preferences
const updateThemeAndPrivacy = async (theme, showInLeaderboard) => {
  const response = await fetch('https://game.regardingwork.com/api/user/preferences', {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${localStorage.getItem('jwt_token')}`
    },
    body: JSON.stringify({
      theme_preference: theme,
      public_leaderboard: showInLeaderboard
    })
  });
  
  return response.json();
};