API reference

Notifications

In-app notifications for your account.

5 operationsBase URL https://packetexchange.io/api/v1Postman collection

List your notifications

GET/api/v1/notifications

Access: API key. Full-access keys only; not reachable by scoped keys.
Rate limit: 100 requests per second (the default)

Unread critical notifications first, then newest activity first, with the unread and unread-critical counts.

Parameters

unread
query · string
Only unread notificationsOne of 1, true
limit
query · integer

Response 200

FieldDescription

datarequired
object
notificationsrequired
object[] · data.notifications
idrequired
string (uuid) · data.notifications[].id
userIdrequired
string (uuid) · data.notifications[].userId
typerequired
string · data.notifications[].type
Machine-readable kind, e.g. webhook_failing, connection, route_check_failed
titlerequired
string · data.notifications[].title
messagerequired
string · data.notifications[].message
readrequired
boolean · data.notifications[].read
datarequired
object | null · data.notifications[].data
createdAtrequired
string (date-time) · data.notifications[].createdAt
ISO-8601 timestamp (UTC)
severityrequired
string · data.notifications[].severity
critical = something is broken and needs your action (a failing route, a suspension, traffic stopped)One of info, warning, critical
linkrequired
string | null · data.notifications[].link
Dashboard path the notification opens, when it has one
occurrencesrequired
integer · data.notifications[].occurrences
How many events this notification groups (repeats update one notification instead of adding more)
lastEventAtrequired
string (date-time) | null · data.notifications[].lastEventAt
When a grouped notification was last updated; null if never
unreadCountrequired
integer · data.unreadCount
criticalUnreadCountrequired
integer · data.criticalUnreadCount
Unread notifications that need action

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Mark a notification as read

POST/api/v1/notifications/{id}/read

Access: API key. Full-access keys only; not reachable by scoped keys.
Rate limit: 100 requests per second (the default)

Parameters

idrequired
path · string

Response 200

Returns the standard envelope with no documented data fields.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
404NOT_FOUND: no such resource on your account.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Get your notification email preference

GET/api/v1/notifications/preferences

Access: API key. Full-access keys only; not reachable by scoped keys.
Rate limit: 100 requests per second (the default)

Whether unread critical notifications are emailed to you as a digest (on by default).

Response 200

FieldDescription

datarequired
object
actionEmailrequired
boolean · data.actionEmail
Email me about issues that need action: at most one email every 4 hours listing unread critical notifications

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

Set your notification email preference

PUT/api/v1/notifications/preferences

Access: API key. Full-access keys only; not reachable by scoped keys.
Rate limit: 100 requests per second (the default)

Turn the "needs attention" digest email on or off. The digest lists unread critical notifications, at most once every 4 hours. Security and account emails are not affected.

Request body (application/json)

FieldDescription

actionEmailrequired
boolean

Response 200

FieldDescription

datarequired
object
Same fields as NotificationEmailPrefs, shown earlier on this page.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.

HTTP

curl -X PUT "https://packetexchange.io/api/v1/notifications/preferences" \
  -H "Authorization: Bearer $PACKETEXCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "actionEmail": true
}'

Run it here with a test key.

Mark all notifications as read

POST/api/v1/notifications/read-all

Access: API key. Full-access keys only; not reachable by scoped keys.
Rate limit: 100 requests per second (the default)

Response 200

Returns the standard envelope with no documented data fields.

Errors

400VALIDATION_ERROR, INVALID_INPUT or BAD_REQUEST. For VALIDATION_ERROR, error.details is an array of { path, message }.
401UNAUTHORIZED: missing, invalid, expired or revoked credential.
403FORBIDDEN: not allowed - a scoped key lacks the scope, or the endpoint is session-only.
409CONFLICT (or a code-specific 409): the change clashes with existing state.
429RATE_LIMITED: slow down and retry after the Retry-After seconds.
500INTERNAL_ERROR: unexpected failure. Quote X-Request-Id to support.