# Notifications endpoints (Admin API)

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

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

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

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

**Get all notifications** Retrieve a paginated list of all notifications with optional search and filtering.

| 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 notifications by title or message |
| `type` | query | string | no | Filter by notification type |
| `user_id` | query | integer | no | Filter by target user ID |
| `server_id` | query | integer | no | Filter by target server ID |
| `global_only` | query | boolean | no | When true, only return global (all-users) notifications |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `notifications` | Notification\[\] |  |
| `pagination` | NotificationPagination |  |

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

Plugin events: [`featherpanel:admin:notifications:retrieved`](https://featherpanel.com/docs/plugins/events/notifications/#notifications-retrieved)

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

### GET `/api/admin/notifications/{id}`

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

**Get notification by ID** Retrieve a specific notification by its ID with comprehensive information.

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

| Response `data` field | Type | Description |
| --- | --- | --- |
| `notification` | Notification |  |

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

Plugin events: [`featherpanel:admin:notifications:notification:not:found`](https://featherpanel.com/docs/plugins/events/notifications/#notification-not-found), [`featherpanel:admin:notifications:notification:retrieved`](https://featherpanel.com/docs/plugins/events/notifications/#notification-retrieved)

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

### PUT `/api/admin/notifications`

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

**Create new notification** Create a new notification with comprehensive validation.

Request body: [`NotificationCreate`](https://featherpanel.com/docs/api/schemas/#schema-notificationcreate) (application/json)

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string | yes | Notification title |
| `message_markdown` | string | yes | Notification message in Markdown format |
| `type` | string | yes | Notification type |
| `user_id` | integer | no | Target user ID (null = all users) |
| `server_id` | integer | no | Target server ID (optional; implies owner) |
| `send_email` | boolean | no | Also email the target user (requires user or server target) |
| `is_dismissible` | boolean | no | Whether the notification can be dismissed (default: true) |
| `is_sticky` | boolean | no | Whether the notification stays until explicitly closed (default: false) |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `notification_id` | integer | Created notification ID |

```bash
curl -X PUT "$PANEL_URL/api/admin/notifications" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"title":"","message_markdown":"","type":"","user_id":0,"server_id":0,"send_email":false,"is_dismissible":false,"is_sticky":false}'
```

Plugin events: [`featherpanel:admin:notifications:notification:created`](https://featherpanel.com/docs/plugins/events/notifications/#notification-created)

Responses: `201` Notification created successfully · `400` Bad request - Validation errors · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `500` Internal server error

### PATCH `/api/admin/notifications/{id}`

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

**Update notification** Update an existing notification with comprehensive validation.

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

Request body: [`NotificationUpdate`](https://featherpanel.com/docs/api/schemas/#schema-notificationupdate) (application/json)

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string | no | Notification title |
| `message_markdown` | string | no | Notification message in Markdown format |
| `type` | string | no | Notification type |
| `user_id` | integer | no | Target user ID (null = all users) |
| `server_id` | integer | no | Target server ID |
| `is_dismissible` | boolean | no | Whether the notification can be dismissed |
| `is_sticky` | boolean | no | Whether the notification stays until explicitly closed |

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

```bash
curl -X PATCH "$PANEL_URL/api/admin/notifications/$ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"title":"","message_markdown":"","type":"","user_id":0,"server_id":0,"is_dismissible":false,"is_sticky":false}'
```

Plugin events: [`featherpanel:admin:notifications:notification:updated`](https://featherpanel.com/docs/plugins/events/notifications/#notification-updated)

Responses: `200` Notification updated successfully · `400` Bad request - Validation errors · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `404` Notification not found · `500` Internal server error

### DELETE `/api/admin/notifications/{id}`

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

**Delete notification** Permanently delete a notification.

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

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

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

Plugin events: [`featherpanel:admin:notifications:notification:deleted`](https://featherpanel.com/docs/plugins/events/notifications/#notification-deleted)

Responses: `200` Notification deleted successfully · `400` Bad request - Invalid ID · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `404` Notification not found · `500` Internal server error