# Images endpoints (Admin API)

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

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

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

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

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

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

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

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

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

- Auth: Admin
- Permission: `admin.images.create`
- Route name: `admin-images-create`
- Controller: [`ImagesController::create`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/ImagesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/images.php#L56)

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

```bash
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`](https://featherpanel.com/docs/plugins/events/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`

- Auth: Admin
- Permission: `admin.images.create`
- Route name: `admin-images-upload`
- Controller: [`ImagesController::upload`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/ImagesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/images.php#L68)

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

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

- Auth: Admin
- Permission: `admin.images.edit`
- Route name: `admin-images-update`
- Controller: [`ImagesController::update`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/ImagesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/images.php#L80)

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

```bash
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`](https://featherpanel.com/docs/plugins/events/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}`

- Auth: Admin
- Permission: `admin.images.delete`
- Route name: `admin-images-delete`
- Controller: [`ImagesController::delete`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/ImagesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/images.php#L97)

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

```bash
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`](https://featherpanel.com/docs/plugins/events/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