Settings endpoints (Admin API)

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

Last synced from FeatherPanel 15b94e9 on 23 Oct 2026.

On this page

Defined in backend/app/routes/admin/settings.php. Authentication used here: Admin. Read Authentication for how to send credentials and 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: AdminPermission: admin.settings.viewRoute name: admin-settings-telemetry-statusController: SettingsController::telemetryStatusroute source

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: AdminPermission: admin.settings.viewRoute name: admin-settingsController: SettingsController::indexroute source

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

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

Plugin events: featherpanel:admin:settings:retrieved

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

GET`/api/admin/settings/categories`

Auth: AdminPermission: admin.settings.viewRoute name: admin-settings-categoriesController: SettingsController::categoriesroute source

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

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

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

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

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

Auth: AdminPermission: admin.settings.viewRoute name: admin-settings-categoryController: SettingsController::getSettingsByCategoryroute source

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

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

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

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

Auth: AdminPermission: admin.settings.viewRoute name: admin-settings-showController: SettingsController::showroute source

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

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

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

PATCH`/api/admin/settings`

Auth: AdminPermission: admin.settings.editRoute name: admin-settings-updateController: SettingsController::updateroute source

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

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

Plugin events: featherpanel:admin: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: AdminPermission: admin.settings.viewRoute name: admin-settings-chatbot-system-promptController: SettingsController::getSystemPromptroute source

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

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: AdminPermission: admin.settings.editRoute name: admin-settings-upload-imageController: SettingsController::uploadImageroute source

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

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: AdminPermission: admin.settings.editRoute name: admin-settings-email-testController: SettingsController::sendTestEmailroute source

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

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: AdminPermission: admin.settings.editRoute name: admin-settings-docker-updateController: SettingsController::triggerDockerUpdateroute source

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

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

Settings endpoints (Admin API)

Endpoints

GET/api/admin/settings/telemetry/status

GET/api/admin/settings

GET/api/admin/settings/categories

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

GET/api/admin/settings/{setting}

PATCH/api/admin/settings

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

POST/api/admin/settings/upload-image

POST/api/admin/settings/email/test

POST/api/admin/settings/docker/update