# Spells endpoints (Admin API)

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

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

Defined in [`backend/app/routes/admin/spells.php`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/spells.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/spells`

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

**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 |  |

```bash
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: Admin
- Permission: `admin.spells.view`
- Route name: `admin-spells-show`
- Controller: [`SpellsController::show`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/SpellsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/spells.php#L35)

**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 |  |

```bash
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: Admin
- Permission: `admin.spells.edit`
- Route name: `admin-spells-update`
- Controller: [`SpellsController::update`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/SpellsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/spells.php#L49)

**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`](https://featherpanel.com/docs/api/schemas/#schema-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 |  |

```bash
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`](https://featherpanel.com/docs/plugins/events/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: Admin
- Permission: `admin.spells.delete`
- Route name: `admin-spells-delete`
- Controller: [`SpellsController::delete`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/SpellsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/spells.php#L64)

**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 |

```bash
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`](https://featherpanel.com/docs/plugins/events/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: Admin
- Permission: `admin.spells.create`
- Route name: `admin-spells-create`
- Controller: [`SpellsController::create`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/SpellsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/spells.php#L79)

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

Request body: [`SpellCreate`](https://featherpanel.com/docs/api/schemas/#schema-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 |  |

```bash
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`](https://featherpanel.com/docs/plugins/events/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: Admin
- Permission: `admin.spells.edit`
- Route name: `admin-spells-reorder`
- Controller: [`SpellsController::reorder`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/SpellsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/spells.php#L89)

**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 |  |

```bash
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`](https://featherpanel.com/docs/plugins/events/spells/#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: Admin
- Permission: `admin.spells.view`
- Route name: `admin-spells-by-realm`
- Controller: [`SpellsController::getByRealm`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/SpellsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/spells.php#L99)

**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 |  |

```bash
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: Admin
- Permission: `admin.spells.create`
- Route name: `admin-spells-import`
- Controller: [`SpellsController::import`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/SpellsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/spells.php#L113)

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

Request body: [`SpellImport`](https://featherpanel.com/docs/api/schemas/#schema-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 |  |

```bash
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: Admin
- Permission: `admin.spells.view`
- Route name: `admin-spells-export`
- Controller: [`SpellsController::export`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/SpellsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/spells.php#L123)

**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 |

```bash
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: Admin
- Permission: `admin.spells.view`
- Route name: `admin-spell-variables-list`
- Controller: [`SpellsController::listVariables`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/SpellsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/spells.php#L138)

**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\[\] |  |

```bash
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: Admin
- Permission: `admin.spells.edit`
- Route name: `admin-spell-variables-create`
- Controller: [`SpellsController::createVariable`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/SpellsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/spells.php#L153)

**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`](https://featherpanel.com/docs/api/schemas/#schema-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 |  |

```bash
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`](https://featherpanel.com/docs/plugins/events/spells/#spell-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: Admin
- Permission: `admin.spells.edit`
- Route name: `admin-spell-variables-update`
- Controller: [`SpellsController::updateVariable`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/SpellsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/spells.php#L168)

**Update spell variable** Update an existing spell variable.

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

Request body: [`SpellVariableUpdate`](https://featherpanel.com/docs/api/schemas/#schema-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 |  |

```bash
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`](https://featherpanel.com/docs/plugins/events/spells/#spell-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: Admin
- Permission: `admin.spells.edit`
- Route name: `admin-spell-variables-delete`
- Controller: [`SpellsController::deleteVariable`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/SpellsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/spells.php#L183)

**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 |

```bash
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`](https://featherpanel.com/docs/plugins/events/spells/#spell-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: Admin
- Permission: `admin.spells.view`
- Route name: `admin-spells-online-list`
- Controller: [`SpellsController::onlineList`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/SpellsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/spells.php#L198)

**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 |

```bash
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: Admin
- Permission: `admin.spells.create`
- Route name: `admin-spells-online-install`
- Controller: [`SpellsController::onlineInstall`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/SpellsController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/spells.php#L208)

**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`](https://featherpanel.com/docs/api/schemas/#schema-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 |  |

```bash
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