---
method: PUT
path: /api/system/settings
auth: jwt+admin
area: system
---
<!-- source: internal/handlers/system_settings.go:65 SystemSettingsHandler.UpdateSetting -->

# Update System Setting

Validates, persists, and reloads a single tunable system setting. Admin only.

## Example request

```json example-request
{
  "key": "scan_poll_interval_seconds",
  "value": "60"
}
```

## Example response

```json example-response
{
  "key": "scan_poll_interval_seconds",
  "value": "60",
  "type": "int",
  "requires_restart": false,
  "category": "scanner",
  "group": "Scanning",
  "description": "How often to scan all libraries (seconds)",
  "is_default": true,
  "reload_required": false
}
```

## Fields

| Field | Type | Required | Notes |
| ----- | ---- | -------- | ----- |
| key | string | Yes | Known setting key |
| value | string | Yes | Value (validated against type/bounds) |

## Errors

| Status | Body | When |
| ------ | ---- | ---- |
| 400 | `{"error": "invalid request"}` / `{"error": "key is required"}` / `{"error": "unknown setting key: ..."}` / `{"error": "value must be ..."}` | malformed body or invalid value |
| 503 | `{"error": "settings registry not initialized"}` | registry not wired |