Notifications API

Complete API reference for listing notifications and performing read, unread, and delete actions.

Authentication Required: All notification APIs require the X-API-Key header.

Standard Response Format

Notifications use the standard API envelope:

{
  "success": true,
  "data": {},
  "timestamp": "2026-04-17T12:34:56Z"
}

Action endpoints return structured data as well as a top-level message.

API Endpoints

List Notifications

GET /v1/notifications

Query parameters

Name	Type	Required	Description
page	integer	No	Page number, default `1`
limit	integer	No	Max items, default `50`, capped at `100` (alias: `page_size`)
offset	integer	No	Offset, default `0` (alias: `skip`)
read	string	No	`true` for read only, `false` for unread only
type	string	No	Exact notification type

Response

{
  "success": true,
  "data": {
    "notifications": [
      {
        "id": "ntf-abc123def456789",
        "user_id": "usr-xyz789abc123456",
        "title": "Sandbox Timeout Warning",
        "message": "Your sandbox will timeout soon",
        "type": "sandbox_timeout",
        "is_read": false,
        "category": "sandbox",
        "created_at": "2026-04-17T11:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1,
      "total_pages": 1
    },
    "unread_count": 3
  },
  "timestamp": "2026-04-17T12:00:00Z"
}

unread_count is the user's overall unread count; it is not limited to the current filter set.

Get Notification

GET /v1/notifications/{notification_id}

Response

{
  "success": true,
  "data": {
    "id": "ntf-abc123def456789",
    "user_id": "usr-xyz789abc123456",
    "title": "Sandbox Timeout Warning",
    "message": "Your sandbox will timeout soon",
    "type": "sandbox_timeout",
    "is_read": false,
    "created_at": "2026-04-17T11:30:00Z",
    "related_entity_type": "sandbox",
    "related_entity_id": "sbx-abc123def456789"
  },
  "timestamp": "2026-04-17T12:01:00Z"
}

Mark Notification as Read

PATCH /v1/notifications/{notification_id}/read

Response

{
  "success": true,
  "data": {
    "notification_id": "ntf-abc123def456789",
    "is_read": true
  },
  "message": "Notification marked as read",
  "timestamp": "2026-04-17T12:02:00Z"
}

Mark Notification as Unread

PATCH /v1/notifications/{notification_id}/unread

Response

{
  "success": true,
  "data": {
    "notification_id": "ntf-abc123def456789",
    "is_read": false
  },
  "message": "Notification marked as unread",
  "timestamp": "2026-04-17T12:03:00Z"
}

Mark All Notifications as Read

PATCH /v1/notifications/read-all

Response

{
  "success": true,
  "data": {
    "marked_count": 3,
    "is_read": true
  },
  "message": "All notifications marked as read",
  "timestamp": "2026-04-17T12:04:00Z"
}

Delete Notification

DELETE /v1/notifications/{notification_id}

Response

{
  "success": true,
  "data": {
    "notification_id": "ntf-abc123def456789",
    "deleted": true
  },
  "message": "Notification deleted",
  "timestamp": "2026-04-17T12:04:30Z"
}

Delete All Notifications

DELETE /v1/notifications

Response

{
  "success": true,
  "data": {
    "deleted_count": 4
  },
  "message": "All notifications deleted",
  "timestamp": "2026-04-17T12:05:00Z"
}

Bulk Delete Notifications

POST /v1/notifications/bulk-delete

Request body

Name	Type	Required	Description
notification_ids	array[string]	Yes	Notification ids to delete

Response

{
  "success": true,
  "data": {
    "notification_ids": [
      "ntf-abc123def456789",
      "ntf-def456ghi789012"
    ],
    "deleted_count": 2
  },
  "message": "Notifications deleted",
  "timestamp": "2026-04-17T12:06:00Z"
}

Bulk Mark Notifications as Read

PATCH /v1/notifications/bulk-read

Request body

Name	Type	Required	Description
notification_ids	array[string]	Yes	Notification ids to mark read

Response

{
  "success": true,
  "data": {
    "notification_ids": [
      "ntf-abc123def456789",
      "ntf-def456ghi789012"
    ],
    "marked_count": 2,
    "is_read": true
  },
  "message": "Notifications marked as read",
  "timestamp": "2026-04-17T12:07:00Z"
}

Bulk Mark Notifications as Unread

PATCH /v1/notifications/bulk-unread

Request body

Name	Type	Required	Description
notification_ids	array[string]	Yes	Notification ids to mark unread

Response

{
  "success": true,
  "data": {
    "notification_ids": [
      "ntf-abc123def456789",
      "ntf-def456ghi789012"
    ],
    "marked_count": 2,
    "is_read": false
  },
  "message": "Notifications marked as unread",
  "timestamp": "2026-04-17T12:08:00Z"
}

Common Errors

{
  "success": false,
  "error": "Notification not found",
  "timestamp": "2026-04-17T12:10:00Z"
}

Common notification errors:

400: invalid bulk request body or empty notification_ids
404: notification not found in your scope
500: database read, update, or delete failure

Notifications API

On this page