# Settings endpoints (Admin API)

> 10 FeatherPanel Admin API endpoints from admin/settings.php: methods, paths, auth, permissions, rate limits, parameters and responses.

Source: https://featherpanel.com/docs/api/reference/admin/settings/

Defined in [`backend/app/routes/admin/settings.php`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/settings.php). Authentication used here: **Admin**. Read [Authentication](https://featherpanel.com/docs/api/authentication/) for how to send credentials and [Rate limits and errors](https://featherpanel.com/docs/api/rate-limits-and-errors/) for the response envelope.

Paths, methods, permissions and rate limits come from the route file. Summaries, parameters and response codes come from the OpenAPI annotations on the controllers; endpoints without annotations show only what the route file declares.

## Endpoints

### GET `/api/admin/settings/telemetry/status`

- Auth: Admin
- Permission: `admin.settings.view`
- Route name: `admin-settings-telemetry-status`
- Controller: [`SettingsController::telemetryStatus`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/SettingsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/settings.php#L25)

```bash
curl -X GET "$PANEL_URL/api/admin/settings/telemetry/status" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

### GET `/api/admin/settings`

- Auth: Admin
- Permission: `admin.settings.view`
- Route name: `admin-settings`
- Controller: [`SettingsController::index`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/SettingsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/settings.php#L35)

**Get all settings** Retrieve all application settings organized by category. Can optionally filter by category using query parameter.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `category` | query | string | no | Filter settings by category |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `settings` | object | All settings |
| `categories` | object | Settings categories |
| `organized_settings` | OrganizedSettings |  |

```bash
curl -X GET "$PANEL_URL/api/admin/settings" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Plugin events: [`featherpanel:admin:settings:retrieved`](https://featherpanel.com/docs/plugins/events/settings/#settings-retrieved)

Responses: `200` Settings retrieved successfully · `401` Unauthorized · `403` Forbidden - Insufficient permissions

### GET `/api/admin/settings/categories`

- Auth: Admin
- Permission: `admin.settings.view`
- Route name: `admin-settings-categories`
- Controller: [`SettingsController::categories`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/SettingsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/settings.php#L45)

**Get settings categories** Retrieve all available settings categories with their metadata.

| Response `data` field | Type | Description |
| --- | --- | --- |
| `categories` | object | Settings categories |

```bash
curl -X GET "$PANEL_URL/api/admin/settings/categories" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Plugin events: [`featherpanel:admin:settings:category:retrieved`](https://featherpanel.com/docs/plugins/events/settings/#settings-by-category-retrieved)

Responses: `200` Categories retrieved successfully · `401` Unauthorized · `403` Forbidden - Insufficient permissions

### GET `/api/admin/settings/category/{category}`

- Auth: Admin
- Permission: `admin.settings.view`
- Route name: `admin-settings-category`
- Controller: [`SettingsController::getSettingsByCategory`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/SettingsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/settings.php#L55)

**Get settings by category** Retrieve all settings belonging to a specific category.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `category` | path | string | yes | Category name |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `category` | object | Category information |
| `settings` | object | Settings in this category |

```bash
curl -X GET "$PANEL_URL/api/admin/settings/category/$CATEGORY" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Plugin events: [`featherpanel:admin:settings:category:retrieved`](https://featherpanel.com/docs/plugins/events/settings/#settings-by-category-retrieved)

Responses: `200` Category settings retrieved successfully · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `404` Category not found

### GET `/api/admin/settings/{setting}`

- Auth: Admin
- Permission: `admin.settings.view`
- Route name: `admin-settings-show`
- Controller: [`SettingsController::show`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/SettingsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/settings.php#L65)

**Get specific setting** Retrieve a specific setting by its name/key.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `setting` | path | string | yes | Setting name/key |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `setting` | Setting |  |

```bash
curl -X GET "$PANEL_URL/api/admin/settings/$SETTING" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Plugin events: [`featherpanel:admin:settings:setting:retrieved`](https://featherpanel.com/docs/plugins/events/settings/#setting-retrieved)

Responses: `200` Setting retrieved successfully · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `404` Setting not found

### PATCH `/api/admin/settings`

- Auth: Admin
- Permission: `admin.settings.edit`
- Route name: `admin-settings-update`
- Controller: [`SettingsController::update`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/SettingsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/settings.php#L75)

**Update settings** Update multiple application settings with validation and activity logging.

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |
| `updated_settings` | string\[\] | List of updated setting names |

```bash
curl -X PATCH "$PANEL_URL/api/admin/settings" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Plugin events: [`featherpanel:admin:settings:updated`](https://featherpanel.com/docs/plugins/events/settings/#settings-updated)

Responses: `200` Settings updated successfully · `400` Bad request - Invalid setting name, required field empty, or value too long · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `500` Internal server error - Failed to update setting

### GET `/api/admin/settings/chatbot/system-prompt`

- Auth: Admin
- Permission: `admin.settings.view`
- Route name: `admin-settings-chatbot-system-prompt`
- Controller: [`SettingsController::getSystemPrompt`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/SettingsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/settings.php#L85)

**Get AI system prompt** Retrieve the AI system prompt from the system-prompt.txt file.

| Response `data` field | Type | Description |
| --- | --- | --- |
| `system_prompt` | string | The system prompt content |

```bash
curl -X GET "$PANEL_URL/api/admin/settings/chatbot/system-prompt" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` System prompt retrieved successfully · `401` Unauthorized - User not authenticated · `403` Forbidden - Admin access required · `404` Not found - System prompt file not found · `500` Internal server error - Failed to read system prompt

### POST `/api/admin/settings/upload-image`

- Auth: Admin
- Permission: `admin.settings.edit`
- Route name: `admin-settings-upload-image`
- Controller: [`SettingsController::uploadImage`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/SettingsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/settings.php#L95)

**Upload an image attachment for settings fields** Upload a JPG/PNG/GIF/WebP image (max 5MB) into /attachments/settings and return its public URL.

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `image` | string (binary) | yes |  |

```bash
curl -X POST "$PANEL_URL/api/admin/settings/upload-image" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -F "image=@./file"
```

Responses: `201` Image uploaded successfully · `400` Bad request · `401` Unauthorized · `403` Forbidden · `500` Failed to save file

### POST `/api/admin/settings/email/test`

- Auth: Admin
- Permission: `admin.settings.edit`
- Route name: `admin-settings-email-test`
- Controller: [`SettingsController::sendTestEmail`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/SettingsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/settings.php#L106)

**Send test email to current user** Send a test email to the currently authenticated user to verify SMTP configuration. This is useful for testing email settings, especially with providers like SendGrid that require email verification.

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |
| `queue_id` | integer | Mail queue ID |

```bash
curl -X POST "$PANEL_URL/api/admin/settings/email/test" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Test email queued successfully · `400` Bad request - SMTP not enabled or user has no email · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `500` Internal server error - Failed to queue test email

### POST `/api/admin/settings/docker/update`

- Auth: Admin
- Permission: `admin.settings.edit`
- Route name: `admin-settings-docker-update`
- Controller: [`SettingsController::triggerDockerUpdate`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/SettingsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/settings.php#L116)

**Trigger Docker panel update** Docker-only action that asks the local updater service to pull latest images and recreate containers.

```bash
curl -X POST "$PANEL_URL/api/admin/settings/docker/update" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Docker update started successfully · `400` Bad request - not a Docker deployment · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `500` Internal server error - updater service unavailable or misconfigured