Realms endpoints (Admin API)
5 FeatherPanel Admin API endpoints from admin/realms.php: methods, paths, auth, permissions, rate limits, parameters and responses.
Last synced from FeatherPanel 15b94e9 on .
On this page
Defined in backend/app/routes/admin/realms.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/realms
Get all realms Retrieve a paginated list of all realms with optional 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 realms by name or description |
Response data field | Type | Description |
|---|---|---|
realms | Realm[] | |
pagination | RealmPagination | |
search | object |
curl -X GET "$PANEL_URL/api/admin/realms" \
-H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
-H "Accept: application/json"Responses: 200 Realms retrieved successfully · 401 Unauthorized · 403 Forbidden - Insufficient permissions
GET/api/admin/realms/{id}
Get realm by ID Retrieve a specific realm by its ID.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes | Realm ID |
Response data field | Type | Description |
|---|---|---|
realm | Realm |
curl -X GET "$PANEL_URL/api/admin/realms/$ID" \
-H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
-H "Accept: application/json"Responses: 200 Realm retrieved successfully · 400 Bad request - Invalid realm ID · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Realm not found
PATCH/api/admin/realms/{id}
Update realm Update an existing realm. Only provided fields will be updated. Validates field lengths and data types.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes | Realm ID |
Request body: RealmUpdate (application/json)
| Body field | Type | Required | Description |
|---|---|---|---|
name | string | no | Realm name |
description | string | no | Realm description |
Response data field | Type | Description |
|---|---|---|
realm | Realm |
curl -X PATCH "$PANEL_URL/api/admin/realms/$ID" \
-H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"name":"","description":""}'Plugin events: featherpanel:admin:realms:realm:updated
Responses: 200 Realm updated successfully · 400 Bad request - Invalid JSON, no data provided, invalid data types, or validation errors · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Realm not found · 500 Internal server error - Failed to update realm
DELETE/api/admin/realms/{id}
Delete realm Permanently delete a realm from the database. This action cannot be undone.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes | Realm ID |
Response data field | Type | Description |
|---|---|---|
message | string | Success message |
curl -X DELETE "$PANEL_URL/api/admin/realms/$ID" \
-H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
-H "Accept: application/json"Plugin events: featherpanel:admin:realms:realm:deleted
Responses: 200 Realm deleted successfully · 400 Bad request - Invalid realm ID or realm has spells assigned · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Realm not found · 500 Internal server error - Failed to delete realm
PUT/api/admin/realms
Create new realm Create a new realm with name and optional description. Validates field lengths and data types.
Request body: RealmCreate (application/json)
| Body field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Realm name |
description | string | no | Realm description |
id | integer | no | Optional realm ID (useful for migrations from other platforms) |
Response data field | Type | Description |
|---|---|---|
realm | Realm |
curl -X PUT "$PANEL_URL/api/admin/realms" \
-H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"name":"","description":"","id":0}'Plugin events: featherpanel:admin:realms:realm:created
Responses: 201 Realm created successfully · 400 Bad request - Invalid JSON, missing required fields, invalid data types, or validation errors · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 500 Internal server error - Failed to create realm