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

Name	In	Type	Description
`unread`	query	string	Only unread notificationsOne of 1, true
`limit`	query	integer	-

Response 200

Field	Type	Description
`data`required	object	-
`notifications`requireddata.notifications	object[]	-
`id`requireddata.notifications[].id	string (uuid)	-
`userId`requireddata.notifications[].userId	string (uuid)	-
`type`requireddata.notifications[].type	string	Machine-readable kind, e.g. webhook_failing, connection, route_check_failed
`title`requireddata.notifications[].title	string	-
`message`requireddata.notifications[].message	string	-
`read`requireddata.notifications[].read	boolean	-
`data`requireddata.notifications[].data	object \| null	-
`createdAt`requireddata.notifications[].createdAt	string (date-time)	ISO-8601 timestamp (UTC)
`severity`requireddata.notifications[].severity	string	critical = something is broken and needs your action (a failing route, a suspension, traffic stopped)One of `info`, `warning`, `critical`
`link`requireddata.notifications[].link	string \| null	Dashboard path the notification opens, when it has one
`occurrences`requireddata.notifications[].occurrences	integer	How many events this notification groups (repeats update one notification instead of adding more)
`lastEventAt`requireddata.notifications[].lastEventAt	string (date-time) \| null	When a grouped notification was last updated; null if never
`unreadCount`requireddata.unreadCount	integer	-
`criticalUnreadCount`requireddata.criticalUnreadCount	integer	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

Name	In	Type	Description
`id`required	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

Field	Type	Description
`data`required	object	-
`actionEmail`requireddata.actionEmail	boolean	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)

Field	Type	Description
`actionEmail`required	boolean	-

Response 200

Field	Type	Description
`data`required	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.