Spells endpoints (Admin API)

15 FeatherPanel Admin API endpoints from admin/spells.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/spells.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/spells`

Auth: AdminPermission: admin.spells.viewRoute name: admin-spellsController: SpellsController::indexroute source

Get all spells Retrieve a paginated list of all spells with optional filtering by realm and search functionality.

Parameter	In	Type	Required	Description
`page`	query	integer	no	Page number for pagination
`limit`	query	integer	no	Number of records per page
`search`	query	string	no	Search term to filter spells by name, author, or description
`realm_id`	query	integer	no	Filter spells by realm ID

Response `data` field	Type	Description
`spells`	Spell[]
`pagination`	SpellPagination
`search`	object

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

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

GET`/api/admin/spells/{id}`

Auth: AdminPermission: admin.spells.viewRoute name: admin-spells-showController: SpellsController::showroute source

Get spell by ID Retrieve a specific spell by its ID with realm information.

Parameter	In	Type	Required	Description
`id`	path	integer	yes	Spell ID

Response `data` field	Type	Description
`spell`	Spell

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

Responses: 200 Spell retrieved successfully · 400 Bad request - Invalid spell ID · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Spell not found

PATCH`/api/admin/spells/{id}`

Auth: AdminPermission: admin.spells.editRoute name: admin-spells-updateController: SpellsController::updateroute source

Update spell Update an existing spell with comprehensive validation including JSON field validation, UUID validation, and activity logging.

Parameter	In	Type	Required	Description
`id`	path	integer	yes	Spell ID

Request body: SpellUpdate (application/json)

Body field	Type	Required	Description
`realm_id`	integer	no	Realm ID
`author`	string	no	Spell author
`name`	string	no	Spell name
`description`	string	no	Spell description
`features`	string	no	Spell features (JSON)
`docker_images`	string	no	Docker images (JSON)
`default_docker_image`	string	no	Default Docker image used on new server installs
`file_denylist`	string	no	File denylist (JSON)
`update_url`	string	no	Update URL
`config_files`	string	no	Config files
`config_startup`	string	no	Config startup
`config_logs`	string	no	Config logs
`config_stop`	string	no	Config stop
`startup`	string	no	Startup command
`script_container`	string	no	Script container
`script_entry`	string	no	Script entry point
`script_is_privileged`	boolean	no	Script is privileged
`script_install`	string	no	Installation script
`force_outgoing_ip`	boolean	no	Force outgoing IP
`config_from`	integer	no	Config from spell ID
`copy_script_from`	integer	no	Copy script from spell ID
`uuid`	string	no	Spell UUID

Response `data` field	Type	Description
`spell`	Spell

curl -X PATCH "$PANEL_URL/api/admin/spells/$ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"realm_id":0,"author":"","name":"","description":"","features":"","docker_images":"","default_docker_image":"","file_denylist":"","update_url":"","config_files":"","config_startup":"","config_logs":"","config_stop":"","startup":"","script_container":"","script_entry":"","script_is_privileged":false,"script_install":"","force_outgoing_ip":false,"config_from":0,"copy_script_from":0,"uuid":""}'

Plugin events: featherpanel:admin:spells:spell:updated

Responses: 200 Spell updated successfully · 400 Bad request - Invalid JSON, no data provided, invalid data types, validation errors, invalid realm, invalid UUID format, or UUID already exists · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Spell or realm not found

DELETE`/api/admin/spells/{id}`

Auth: AdminPermission: admin.spells.deleteRoute name: admin-spells-deleteController: SpellsController::deleteroute source

Delete spell Permanently delete a spell. Checks for references from other spells before deletion.

Parameter	In	Type	Required	Description
`id`	path	integer	yes	Spell ID

Response `data` field	Type	Description
`message`	string	Success message

curl -X DELETE "$PANEL_URL/api/admin/spells/$ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Plugin events: featherpanel:admin:spells:spell:deleted

Responses: 200 Spell deleted successfully · 400 Bad request - Spell is referenced by other spells or failed to delete · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Spell not found

PUT`/api/admin/spells`

Auth: AdminPermission: admin.spells.createRoute name: admin-spells-createController: SpellsController::createroute source

Create new spell Create a new spell with comprehensive validation including JSON field validation, UUID generation, and activity logging.

Request body: SpellCreate (application/json)

Body field	Type	Required	Description
`realm_id`	integer	yes	Realm ID
`author`	string	yes	Spell author
`name`	string	yes	Spell name
`description`	string	no	Spell description
`features`	string	no	Spell features (JSON)
`docker_images`	string	no	Docker images (JSON)
`default_docker_image`	string	no	Default Docker image used on new server installs
`file_denylist`	string	no	File denylist (JSON)
`update_url`	string	no	Update URL
`config_files`	string	no	Config files
`config_startup`	string	no	Config startup
`config_logs`	string	no	Config logs
`config_stop`	string	no	Config stop
`startup`	string	no	Startup command
`script_container`	string	no	Script container
`script_entry`	string	no	Script entry point
`script_is_privileged`	boolean	no	Script is privileged
`script_install`	string	no	Installation script
`force_outgoing_ip`	boolean	no	Force outgoing IP
`config_from`	integer	no	Config from spell ID
`copy_script_from`	integer	no	Copy script from spell ID
`uuid`	string	no	Spell UUID (auto-generated if not provided)
`id`	integer	no	Optional spell ID (useful for migrations from other platforms)

Response `data` field	Type	Description
`spell`	Spell

curl -X PUT "$PANEL_URL/api/admin/spells" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"realm_id":0,"author":"","name":"","description":"","features":"","docker_images":"","default_docker_image":"","file_denylist":"","update_url":"","config_files":"","config_startup":"","config_logs":"","config_stop":"","startup":"","script_container":"","script_entry":"","script_is_privileged":false,"script_install":"","force_outgoing_ip":false,"config_from":0,"copy_script_from":0,"uuid":"","id":0}'

Plugin events: featherpanel:admin:spells:spell:created

Responses: 201 Spell created successfully · 400 Bad request - Invalid JSON, missing required fields, invalid data types, validation errors, invalid realm, invalid UUID format, or UUID already exists · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Realm not found

POST`/api/admin/spells/reorder`

Auth: AdminPermission: admin.spells.editRoute name: admin-spells-reorderController: SpellsController::reorderroute source

Reorder spells within a realm Update the display sort order of spells in a realm (e.g. Node.js first, then Python, then Java).

Body field	Type	Required	Description
`realm_id`	integer	yes
`spells`	object[]	yes

curl -X POST "$PANEL_URL/api/admin/spells/reorder" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"realm_id":0,"spells":[]}'

Plugin events: featherpanel:admin:spells:reordered

Responses: 200 Spells reordered successfully · 400 Bad request · 404 Realm not found · 500 Internal server error

GET`/api/admin/spells/realm/{realmId}`

Auth: AdminPermission: admin.spells.viewRoute name: admin-spells-by-realmController: SpellsController::getByRealmroute source

Get spells by realm Retrieve all spells belonging to a specific realm with pagination and search functionality.

Parameter	In	Type	Required	Description
`realmId`	path	integer	yes	Realm ID
`page`	query	integer	no	Page number for pagination
`limit`	query	integer	no	Number of records per page
`search`	query	string	no	Search term to filter spells

Response `data` field	Type	Description
`spells`	Spell[]
`realm`	object	Realm information
`pagination`	object

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

Responses: 200 Spells for realm retrieved successfully · 400 Bad request - Invalid realm ID · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Realm not found

POST`/api/admin/spells/import`

Auth: AdminPermission: admin.spells.createRoute name: admin-spells-importController: SpellsController::importroute source

Import spell from file Import a spell from a JSON file with comprehensive validation, variable import, and metadata preservation.

Request body: SpellImport (multipart/form-data)

Body field	Type	Required	Description
`realm_id`	integer	yes	Realm ID
`file`	string (binary)	no	Spell JSON file

Response `data` field	Type	Description
`spell`	Spell

curl -X POST "$PANEL_URL/api/admin/spells/import" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -F "realm_id=" \
  -F "file=@./file"

Responses: 201 Spell imported successfully · 400 Bad request - Invalid realm ID, no file uploaded, file upload error, file read error, invalid JSON format, or failed to create spell · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Realm not found

GET`/api/admin/spells/{id}/export`

Auth: AdminPermission: admin.spells.viewRoute name: admin-spells-exportController: SpellsController::exportroute source

Export spell to file Export a spell to a JSON file with complete metadata, variables, and FeatherPanel-specific information.

Parameter	In	Type	Required	Description
`id`	path	integer	yes	Spell ID

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

Responses: 200 Spell exported successfully · 400 Bad request - Invalid spell ID · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Spell not found

GET`/api/admin/spells/{spellId}/variables`

Auth: AdminPermission: admin.spells.viewRoute name: admin-spell-variables-listController: SpellsController::listVariablesroute source

List spell variables Retrieve all variables for a specific spell.

Parameter	In	Type	Required	Description
`spellId`	path	integer	yes	Spell ID

Response `data` field	Type	Description
`variables`	SpellVariable[]

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

Responses: 200 Variables retrieved successfully · 400 Bad request - Invalid spell ID · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Spell not found

POST`/api/admin/spells/{spellId}/variables`

Auth: AdminPermission: admin.spells.editRoute name: admin-spell-variables-createController: SpellsController::createVariableroute source

Create spell variable Create a new variable for a specific spell with validation.

Parameter	In	Type	Required	Description
`spellId`	path	integer	yes	Spell ID

Request body: SpellVariableCreate (application/json)

Body field	Type	Required	Description
`name`	string	yes	Variable name
`env_variable`	string	yes	Environment variable name
`description`	string	yes	Variable description
`default_value`	string	yes	Default value
`user_viewable`	boolean	no	User viewable flag
`user_editable`	boolean	no	User editable flag
`rules`	string	no	Validation rules
`field_type`	string	no	Field type

Response `data` field	Type	Description
`variable`	SpellVariable

curl -X POST "$PANEL_URL/api/admin/spells/$SPELL_ID/variables" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"","env_variable":"","description":"","default_value":"","user_viewable":false,"user_editable":false,"rules":"","field_type":""}'

Plugin events: featherpanel:admin:spells:variable:created

Responses: 201 Variable created successfully · 400 Bad request - Invalid JSON, missing required fields, or failed to create variable · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Spell not found

PATCH`/api/admin/spell-variables/{id}`

Auth: AdminPermission: admin.spells.editRoute name: admin-spell-variables-updateController: SpellsController::updateVariableroute source

Update spell variable Update an existing spell variable.

Parameter	In	Type	Required	Description
`id`	path	integer	yes	Variable ID

Request body: SpellVariableUpdate (application/json)

Body field	Type	Required	Description
`name`	string	no	Variable name
`env_variable`	string	no	Environment variable name
`description`	string	no	Variable description
`default_value`	string	no	Default value
`user_viewable`	boolean	no	User viewable flag
`user_editable`	boolean	no	User editable flag
`rules`	string	no	Validation rules
`field_type`	string	no	Field type

Response `data` field	Type	Description
`variable`	SpellVariable

curl -X PATCH "$PANEL_URL/api/admin/spell-variables/$ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"","env_variable":"","description":"","default_value":"","user_viewable":false,"user_editable":false,"rules":"","field_type":""}'

Plugin events: featherpanel:admin:spells:variable:updated

Responses: 200 Variable updated successfully · 400 Bad request - Invalid JSON or failed to update variable · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Variable not found

DELETE`/api/admin/spell-variables/{id}`

Auth: AdminPermission: admin.spells.editRoute name: admin-spell-variables-deleteController: SpellsController::deleteVariableroute source

Delete spell variable Delete an existing spell variable.

Parameter	In	Type	Required	Description
`id`	path	integer	yes	Variable ID

Response `data` field	Type	Description
`message`	string	Success message

curl -X DELETE "$PANEL_URL/api/admin/spell-variables/$ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Plugin events: featherpanel:admin:spells:variable:deleted

Responses: 200 Variable deleted successfully · 400 Bad request - Failed to delete variable · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Variable not found

GET`/api/admin/spells/online/list`

Auth: AdminPermission: admin.spells.viewRoute name: admin-spells-online-listController: SpellsController::onlineListroute source

List online spells Retrieve spells from the online FeatherPanel spell registry with search and pagination.

Parameter	In	Type	Required	Description
`q`	query	string	no	Search query
`page`	query	integer	no	Page number for pagination
`per_page`	query	integer	no	Number of records per page

Response `data` field	Type	Description
`spells`	OnlineSpell[]
`pagination`	object	Pagination information

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

Responses: 200 Online spells retrieved successfully · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 500 Failed to fetch online spell list or invalid response

POST`/api/admin/spells/online/install`

Auth: AdminPermission: admin.spells.createRoute name: admin-spells-online-installController: SpellsController::onlineInstallroute source

Install spell from online registry Install a spell from the online FeatherPanel spell registry with comprehensive validation, variable import, and metadata preservation.

Request body: OnlineSpellInstall (application/json)

Body field	Type	Required	Description
`identifier`	string	yes	Spell identifier
`realm_id`	integer	yes	Realm ID

Response `data` field	Type	Description
`spell`	Spell

curl -X POST "$PANEL_URL/api/admin/spells/online/install" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"","realm_id":0}'

Responses: 201 Spell installed successfully from online repository · 400 Bad request - Invalid identifier, invalid realm ID, invalid JSON format, or failed to create spell · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Realm not found or spell not found in registry · 500 Failed to download spell JSON

Spells endpoints (Admin API)

Endpoints

GET/api/admin/spells

GET/api/admin/spells/{id}

PATCH/api/admin/spells/{id}

DELETE/api/admin/spells/{id}

PUT/api/admin/spells

POST/api/admin/spells/reorder

GET/api/admin/spells/realm/{realmId}

POST/api/admin/spells/import

GET/api/admin/spells/{id}/export

GET/api/admin/spells/{spellId}/variables

POST/api/admin/spells/{spellId}/variables

PATCH/api/admin/spell-variables/{id}

DELETE/api/admin/spell-variables/{id}

GET/api/admin/spells/online/list

POST/api/admin/spells/online/install