Images endpoints (Admin API)
6 FeatherPanel Admin API endpoints from admin/images.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/images.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/images
Get all images Retrieve a paginated list of all images 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 images by name |
Response data field | Type | Description |
|---|---|---|
images | Image[] | |
pagination | ImagePagination | |
search | object |
curl -X GET "$PANEL_URL/api/admin/images" \
-H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
-H "Accept: application/json"Responses: 200 Images retrieved successfully · 401 Unauthorized · 403 Forbidden - Insufficient permissions
GET/api/admin/images/{id}
Get image by ID Retrieve a specific image by its ID.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes | Image ID |
Response data field | Type | Description |
|---|---|---|
image | Image |
curl -X GET "$PANEL_URL/api/admin/images/$ID" \
-H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
-H "Accept: application/json"Responses: 200 Image retrieved successfully · 400 Bad request - Invalid image ID · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Image not found
POST/api/admin/images
Create new image Create a new image record with name and URL. Validates URL format and ensures uniqueness of name and URL.
Request body: ImageCreate (application/json)
| Body field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Image name |
url | string | yes | Image URL |
Response data field | Type | Description |
|---|---|---|
image_id | integer | ID of the created image |
curl -X POST "$PANEL_URL/api/admin/images" \
-H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"name":"","url":""}'Plugin events: featherpanel:admin:images:image:created
Responses: 201 Image created successfully · 400 Bad request - Missing required fields, invalid data types, invalid URL format, or validation errors · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 409 Conflict - Image name or URL already exists · 500 Internal server error - Failed to create image
POST/api/admin/images/upload
Upload image file Upload an image file and create a corresponding image record. Supports JPG, PNG, GIF, and WebP formats with a maximum size of 10MB.
| Body field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Image name |
image | string (binary) | yes | Image file (JPG, PNG, GIF, WebP, max 10MB) |
Response data field | Type | Description |
|---|---|---|
image_id | integer | ID of the created image |
url | string | Public URL of the uploaded image |
filename | string | Generated filename |
curl -X POST "$PANEL_URL/api/admin/images/upload" \
-H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
-H "Accept: application/json" \
-F "name=" \
-F "image=@./file"Responses: 201 Image uploaded successfully · 400 Bad request - No file provided, missing name, invalid file, file too large, or invalid file type · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 409 Conflict - Image name already exists · 500 Internal server error - Failed to save file or create image record
PATCH/api/admin/images/{id}
Update image Update an existing image. Only provided fields will be updated. Validates URL format and ensures uniqueness of name and URL.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes | Image ID |
Request body: ImageUpdate (application/json)
| Body field | Type | Required | Description |
|---|---|---|---|
name | string | no | Image name |
url | string | no | Image URL |
Response data field | Type | Description |
|---|---|---|
message | string | Success message |
curl -X PATCH "$PANEL_URL/api/admin/images/$ID" \
-H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"name":"","url":""}'Plugin events: featherpanel:admin:images:image:updated
Responses: 200 Image updated successfully · 400 Bad request - No data provided, invalid data types, invalid URL format, or validation errors · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Image not found · 409 Conflict - Image name or URL already exists · 500 Internal server error - Failed to update image
DELETE/api/admin/images/{id}
Delete image Permanently delete an image record.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes | Image ID |
Response data field | Type | Description |
|---|---|---|
message | string | Success message |
curl -X DELETE "$PANEL_URL/api/admin/images/$ID" \
-H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
-H "Accept: application/json"Plugin events: featherpanel:admin:images:image:deleted
Responses: 200 Image deleted successfully · 400 Bad request - Invalid image ID · 401 Unauthorized · 403 Forbidden - Insufficient permissions · 404 Image not found · 500 Internal server error - Failed to delete image