Settings store user preferences, onboarding status, and custom configuration. Each user typically has one settings object.
Get Settings
Retrieve settings for the authenticated user.
curl -X GET http://localhost:3000/api/settings \
-H "Cookie: session=your-session-token"
Response
Returns an array of settings objects (typically one per user).
Unique settings identifier
ID of the user these settings belong to
ID of the last viewed dashboard
Custom user configuration (key-value pairs)
Whether the user has completed onboarding (default: false)
Success (200)
Error (401)
[
{
"id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
"userId": "user123",
"lastDashboardId": "550e8400-e29b-41d4-a716-446655440000",
"config": {
"theme": "dark",
"language": "en"
},
"onboardingCompleted": true,
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-20T14:22:00.000Z"
}
]
Update Settings
curl -X PUT http://localhost:3000/api/settings \
-H "Content-Type: application/json" \
-H "Cookie: session=your-session-token" \
-d '{
"id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
"lastDashboardId": "550e8400-e29b-41d4-a716-446655440000",
"config": {
"theme": "light",
"notifications": true
},
"onboardingCompleted": true
}'
Request Body
ID of the last viewed dashboard
Custom configuration object (key-value pairs)
Mark onboarding as completed
Response
Returns the updated settings object.
Success (200)
Error (400)
Error (403)
Error (404)
{
"id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
"userId": "user123",
"lastDashboardId": "550e8400-e29b-41d4-a716-446655440000",
"config": {
"theme": "light",
"notifications": true
},
"onboardingCompleted": true,
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-20T15:10:00.000Z"
}
User does not own these settings. { "error": "Settings not found or could not be updated" }
Config Field
The config field is a flexible JSONB object that can store any custom user preferences:
{
"config": {
"theme": "dark",
"language": "en",
"notifications": true,
"displayMode": "compact",
"customOption": "value"
}
}
Onboarding Flow
The onboardingCompleted field tracks whether a user has finished the initial setup:
- User signs up - settings created with
onboardingCompleted: false
- User completes onboarding steps in the UI
- Frontend calls
PUT /api/settings with onboardingCompleted: true
- User no longer sees onboarding prompts
// Mark onboarding as complete
await fetch('/api/settings', {
method: 'PUT',
credentials: 'include',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
id: settingsId,
onboardingCompleted: true
})
});