# Settings API

The Settings API manages user preferences organized into seven categories: appearance, notifications, chat, voice, privacy, integrations, and accessibility. Settings are deep-merged on update and fall back to platform defaults when unset. Rate limited to 100 requests per minute.

## GET /api/v2/settings

Get All Settings -- Returns all settings for the authenticated user, merged with platform defaults for any unset values.

**Authentication required**

### Example Request

```bash
curl -X GET https://api.lvng.ai/api/v2/settings \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Response (200)

```json
{
  "success": true,
  "settings": {
    "appearance": {
      "theme": "system",
      "fontSize": "medium",
      "compactMode": false,
      "sidebarCollapsed": false,
      "accentColor": "#6366f1"
    },
    "notifications": {
      "enabled": true,
      "desktop": true,
      "email": true,
      "mentions": true,
      "directMessages": true,
      "workflowUpdates": true,
      "soundEnabled": true,
      "quietHoursEnabled": false,
      "quietHoursStart": "22:00",
      "quietHoursEnd": "08:00"
    },
    "chat": {
      "defaultPersonality": "lvng",
      "streamResponses": true,
      "showTimestamps": true,
      "enterToSend": true,
      "showAvatars": true,
      "messageGrouping": true
    },
    "voice": {
      "autoTranscribe": true,
      "language": "en-US",
      "saveRecordings": true
    },
    "privacy": {
      "shareAnalytics": true,
      "activityStatus": "online",
      "readReceipts": true
    },
    "integrations": {
      "connectedPlatforms": [],
      "defaultExportFormat": "json"
    },
    "accessibility": {
      "reduceMotion": false,
      "highContrast": false,
      "screenReaderOptimized": false,
      "keyboardShortcuts": true
    }
  }
}
```

## PUT /api/v2/settings

Update All Settings -- Deep-merges the provided settings with existing user settings. Only the keys you include are changed; everything else is preserved.

**Authentication required**

### Body Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| appearance | object | No | Appearance settings (theme, fontSize, compactMode, sidebarCollapsed, accentColor). |
| notifications | object | No | Notification preferences (enabled, desktop, email, mentions, directMessages, workflowUpdates, soundEnabled, quietHoursEnabled, quietHoursStart, quietHoursEnd). |
| chat | object | No | Chat behavior (defaultPersonality, streamResponses, showTimestamps, enterToSend, showAvatars, messageGrouping). |
| voice | object | No | Voice settings (autoTranscribe, language, saveRecordings). |
| privacy | object | No | Privacy options (shareAnalytics, activityStatus, readReceipts). activityStatus is one of: online, away, dnd, invisible. |
| integrations | object | No | Integration config (connectedPlatforms, defaultExportFormat). |
| accessibility | object | No | Accessibility options (reduceMotion, highContrast, screenReaderOptimized, keyboardShortcuts). |

### Example Request

```bash
curl -X PUT https://api.lvng.ai/api/v2/settings \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "appearance": {
      "theme": "dark",
      "compactMode": true
    },
    "notifications": {
      "quietHoursEnabled": true,
      "quietHoursStart": "23:00",
      "quietHoursEnd": "07:00"
    }
  }'
```

### Response (200)

```json
{
  "success": true,
  "settings": {
    "appearance": {
      "theme": "dark",
      "fontSize": "medium",
      "compactMode": true,
      "sidebarCollapsed": false,
      "accentColor": "#6366f1"
    },
    "notifications": {
      "enabled": true,
      "desktop": true,
      "email": true,
      "mentions": true,
      "directMessages": true,
      "workflowUpdates": true,
      "soundEnabled": true,
      "quietHoursEnabled": true,
      "quietHoursStart": "23:00",
      "quietHoursEnd": "07:00"
    },
    "chat": {
      "defaultPersonality": "lvng",
      "streamResponses": true,
      "showTimestamps": true,
      "enterToSend": true,
      "showAvatars": true,
      "messageGrouping": true
    },
    "voice": {
      "autoTranscribe": true,
      "language": "en-US",
      "saveRecordings": true
    },
    "privacy": {
      "shareAnalytics": true,
      "activityStatus": "online",
      "readReceipts": true
    },
    "integrations": {
      "connectedPlatforms": [],
      "defaultExportFormat": "json"
    },
    "accessibility": {
      "reduceMotion": false,
      "highContrast": false,
      "screenReaderOptimized": false,
      "keyboardShortcuts": true
    }
  }
}
```

## GET /api/v2/settings/:category

Get Category Settings -- Returns settings for a single category. Returns 400 if the category is invalid.

**Authentication required**

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| category | string | Yes | One of: appearance, notifications, chat, voice, privacy, integrations, accessibility. |

### Example Request

```bash
curl -X GET https://api.lvng.ai/api/v2/settings/chat \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Response (200)

```json
{
  "success": true,
  "category": "chat",
  "settings": {
    "defaultPersonality": "lvng",
    "streamResponses": true,
    "showTimestamps": true,
    "enterToSend": true,
    "showAvatars": true,
    "messageGrouping": true
  }
}
```

## PUT /api/v2/settings/:category

Update Category Settings -- Shallow-merges the request body into the specified category. Existing keys within the category that are not in the request body are preserved.

**Authentication required**

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| category | string | Yes | The settings category to update. |

### Body Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| ...keys | any | Yes | Key-value pairs for the category. Send only the fields you want to change. |

### Example Request

```bash
curl -X PUT https://api.lvng.ai/api/v2/settings/notifications \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": false,
    "soundEnabled": false
  }'
```

### Response (200)

```json
{
  "success": true,
  "category": "notifications",
  "settings": {
    "enabled": true,
    "desktop": true,
    "email": false,
    "mentions": true,
    "directMessages": true,
    "workflowUpdates": true,
    "soundEnabled": false,
    "quietHoursEnabled": false,
    "quietHoursStart": "22:00",
    "quietHoursEnd": "08:00"
  }
}
```

## DELETE /api/v2/settings/:category/:key

Reset Setting to Default -- Resets a single setting key back to its platform default value. Returns 400 if the category or key is invalid.

**Authentication required**

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| category | string | Yes | The settings category (e.g. appearance, chat). |
| key | string | Yes | The specific setting key to reset (e.g. theme, streamResponses). |

### Example Request

```bash
curl -X DELETE https://api.lvng.ai/api/v2/settings/appearance/theme \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Response (200)

```json
{
  "success": true,
  "category": "appearance",
  "key": "theme",
  "value": "system",
  "message": "Setting reset to default"
}
```

## POST /api/v2/settings/export

Export Settings -- Exports all user settings as a versioned JSON object. Use this for backups or migrating settings between accounts.

**Authentication required**

### Example Request

```bash
curl -X POST https://api.lvng.ai/api/v2/settings/export \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Response (200)

```json
{
  "success": true,
  "export": {
    "version": "2.0",
    "exportedAt": "2026-03-19T10:30:00.000Z",
    "settings": {
      "appearance": { "theme": "dark", "fontSize": "medium", "compactMode": true, "sidebarCollapsed": false, "accentColor": "#6366f1" },
      "notifications": { "enabled": true, "desktop": true, "email": true, "mentions": true, "directMessages": true, "workflowUpdates": true, "soundEnabled": true, "quietHoursEnabled": false, "quietHoursStart": "22:00", "quietHoursEnd": "08:00" },
      "chat": { "defaultPersonality": "lvng", "streamResponses": true, "showTimestamps": true, "enterToSend": true, "showAvatars": true, "messageGrouping": true },
      "voice": { "autoTranscribe": true, "language": "en-US", "saveRecordings": true },
      "privacy": { "shareAnalytics": true, "activityStatus": "online", "readReceipts": true },
      "integrations": { "connectedPlatforms": [], "defaultExportFormat": "json" },
      "accessibility": { "reduceMotion": false, "highContrast": false, "screenReaderOptimized": false, "keyboardShortcuts": true }
    }
  }
}
```

## POST /api/v2/settings/import

Import Settings -- Imports settings from a previously exported payload. By default merges with existing settings. Set merge to false to replace all settings entirely.

**Authentication required**

### Body Parameters

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| settings | object | Yes | -- | The settings object to import, matching the export format structure. |
| merge | boolean | No | true | When true (default), imported keys are merged with existing settings. When false, all settings are replaced. |

### Example Request

```bash
curl -X POST https://api.lvng.ai/api/v2/settings/import \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "chat": {
        "defaultPersonality": "lvng",
        "streamResponses": false,
        "enterToSend": false
      },
      "appearance": {
        "theme": "light",
        "accentColor": "#ec4899"
      }
    },
    "merge": true
  }'
```

### Response (200)

```json
{
  "success": true,
  "message": "Settings merged successfully",
  "settings": {
    "appearance": {
      "theme": "light",
      "fontSize": "medium",
      "compactMode": true,
      "sidebarCollapsed": false,
      "accentColor": "#ec4899"
    },
    "notifications": {
      "enabled": true,
      "desktop": true,
      "email": true,
      "mentions": true,
      "directMessages": true,
      "workflowUpdates": true,
      "soundEnabled": true,
      "quietHoursEnabled": false,
      "quietHoursStart": "22:00",
      "quietHoursEnd": "08:00"
    },
    "chat": {
      "defaultPersonality": "lvng",
      "streamResponses": false,
      "showTimestamps": true,
      "enterToSend": false,
      "showAvatars": true,
      "messageGrouping": true
    },
    "voice": {
      "autoTranscribe": true,
      "language": "en-US",
      "saveRecordings": true
    },
    "privacy": {
      "shareAnalytics": true,
      "activityStatus": "online",
      "readReceipts": true
    },
    "integrations": {
      "connectedPlatforms": [],
      "defaultExportFormat": "json"
    },
    "accessibility": {
      "reduceMotion": false,
      "highContrast": false,
      "screenReaderOptimized": false,
      "keyboardShortcuts": true
    }
  }
}
```