Notifications API

The Notifications API has two groups: the in-app inbox for every signed-in user (/api/v1/notifications — list visible notifications, unread count, mark as read) and the /api/v1/admin/notifications routes used by administrators to publish, browse, and delete notifications. A notification's scope (global / team / user) decides who can see it, and read state is per user.

Endpoints

Every endpoint requires Authorization: Bearer <token>.

Visibility

The caller can see a notification if and only if at least one of these holds:

• scope is global;
• scope is user and user_id is the caller;
• scope is team and team_id is one of the caller's teams.

Notifications whose expires_at is in the past are excluded from the list and the unread count; only include_expired=true (admin route) brings them back, for troubleshooting.

Notification object

Delivery record (deliveries[])

List notifications

GET /api/v1/notifications

Returns the notifications visible to the caller, ordered by created_at descending.

Query parameters

curl -X GET "https://your-domain.com/api/v1/notifications?unread_only=true&page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

200 OK:

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
        "scope": "team",
        "team_id": "550e8400-e29b-41d4-a716-446655440000",
        "user_id": null,
        "type": "agent.published",
        "source": "system",
        "title": "Agent published",
        "content": "Support Assistant is now available to the team.",
        "level": "medium",
        "data": {"agent_id": "1c2f1a2e-0f4e-4a8f-9d4a-2b0d7b3dcb6d"},
        "link_url": "/app/apps/1c2f1a2e-0f4e-4a8f-9d4a-2b0d7b3dcb6d",
        "status": "active",
        "expires_at": null,
        "created_at": "2026-09-26T08:15:00Z",
        "updated_at": "2026-09-26T08:15:00Z",
        "is_read": false,
        "read_at": null,
        "deliveries": []
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  },
  "msg": "success"
}

The pagination envelope is data.items / data.total / data.page / data.page_size.

Get unread count

GET /api/v1/notifications/unread-count

Counts the caller's visible, unread notifications (same visibility and expiry rules).

200 OK:

{
  "code": 0,
  "data": {"total": 3},
  "msg": "success"
}

Mark as read

POST /api/v1/notifications/read

Marks notifications by ID, or marks every visible notification as read with mark_all.

Request body

At least one of notification_ids or mark_all must be present, otherwise the request fails with 400 + 1002 (validation_error).

{
  "notification_ids": ["9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"],
  "mark_all": false
}

200 OK:

{
  "code": 0,
  "data": {"updated": 1},
  "msg": "Notification read status updated"
}

data.updated is the number of newly created read records; already-read notifications are not counted and are not an error.

Browse notifications (admin)

GET /api/v1/admin/notifications

Query parameters

Returns the same {items, total, page, page_size} envelope as the user route, but:

• items[].is_read is always false and read_at always null (read state is per user and is not aggregated here);
• items[].deliveries is populated with per-channel records.

Authorization rules:

Errors:

Create and dispatch a notification

POST /api/v1/admin/notifications

Requires the admin:notification:create permission.

Request body

Scope authorization:

Batch mode (user_ids) creates one notification per user and returns only the first notification object (msg is Notifications created successfully).

curl -X POST "https://your-domain.com/api/v1/admin/notifications" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "team",
    "team_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "maintenance_notice",
    "source": "system",
    "title": "Scheduled maintenance",
    "content": "The platform will be unavailable on Sunday 02:00-04:00 UTC.",
    "level": "high",
    "link_url": "/status",
    "notify_channels": ["email", "webhook"]
  }'

200 OK: data is the created notification object; deliveries contains the newly created delivery records (pending, sent asynchronously by a background task).

Delete notification

DELETE /api/v1/admin/notifications/{notification_id}

Requires the admin:notification:delete permission. An audit record is written before deletion.

Authorization: global and user scoped notifications can only be deleted by a global admin; team scoped notifications require the caller to be an OWNER/ADMIN of that team (the team comes from the notification itself, not from the request).

200 OK:

{
  "code": 0,
  "data": {"id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"},
  "msg": "Notification deleted successfully"
}

Errors:

Error handling

Related

• Notification settings — admin configuration and delivery channels
• Settings API — enabling and testing channels (SMTP, DingTalk, WeCom, Feishu, webhook, Slack)
• Error Handling — recover by HTTP status and business error code