Skip to content

Notifications

User-facing notification feed.

All endpoints below are mounted under /api. Authentication: Authorization: Bearer <token> unless noted as public.

Endpoint count: 3

Endpoints

Method Path Handler Guards
POST /api/notifications/delete deleteNotifications -
POST /api/notifications/mark-read markNotificationsRead -
GET /api/notifications/unread-count getNotificationsUnreadCount -

Source

Handlers for this section live in api/routes/handlers_*.go in the StarkOne source. Each handler binds its request body with gin.ShouldBindJSON(&req) and responds with the standard envelope:

{ "data": { ... } }

On error:

{ "error": { "code": "string", "message": "string" } }

Reference

POST /api/notifications/delete

Deletes the given notification ids for the current user, or all of the user's notifications when {"all": true} is passed.

Request body

{ "ids": "[]int64 (optional)", "all": "bool (optional)" }
Field Type Required Description
ids array of int64 no Notification ids to delete. Used when all is not set; must be non-empty if all is false.
all bool no When true, deletes all notifications for the current user and ids is ignored.

Note: the body is bound with c.ShouldBindJSON and bind errors are ignored, so an absent or malformed body is treated as {} (which yields the bad_request error below).

Response - 200 OK

This handler returns a flat (non-enveloped) body, not the standard { "data": ... } envelope.

{ "success": true }

Errors

Status Code Meaning
400 bad_request Neither ids (non-empty) nor all was provided.
500 db_error The delete query failed.

Side effects

  • DB write: DELETE FROM notifications for the current user, scoped either to the supplied ids or to all of the user's rows when all is true.

Example

curl -X POST https://panel.example.com:2087/api/notifications/delete \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ids": [1, 2, 3]}'

POST /api/notifications/mark-read

Marks the given notification ids as read for the current user, or marks all of the user's notifications as read when {"all": true} is passed.

Request body

{ "ids": "[]int64 (optional)", "all": "bool (optional)" }
Field Type Required Description
ids array of int64 no Notification ids to mark as read. Used when all is not set; must be non-empty if all is false.
all bool no When true, marks all notifications for the current user as read and ids is ignored.

Note: the body is bound with c.ShouldBindJSON and bind errors are ignored, so an absent or malformed body is treated as {} (which yields the bad_request error below).

Response - 200 OK

This handler returns a flat (non-enveloped) body, not the standard { "data": ... } envelope.

{ "success": true }

Errors

Status Code Meaning
400 bad_request Neither ids (non-empty) nor all was provided.
500 db_error The update query failed.

Side effects

  • DB write: UPDATE notifications SET read = 1 for the current user, scoped either to the supplied ids or to all of the user's rows when all is true.

Example

curl -X POST https://panel.example.com:2087/api/notifications/mark-read \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"all": true}'

GET /api/notifications/unread-count

Returns just the unread notification count for the current user, intended for bell-badge polling.

Response - 200 OK

This handler returns a flat (non-enveloped) body, not the standard { "data": ... } envelope.

{ "unread": 0 }
Field Type Description
unread int Number of notifications with read = 0 for the current user.

Note: the underlying count query is run without error handling; if it fails, unread defaults to 0 and the response is still 200 OK.

Example

curl -X GET https://panel.example.com:2087/api/notifications/unread-count \
  -H "Authorization: Bearer $TOKEN"