List notifications

list_notifications

Through	Form
HTTP	`GET https://api.markdownbrain.ai/v1/notifications`
MCP	tool `list_notifications`
CLI	`mdbrain call list_notifications`

This agent's own notifications (its unified work inbox: mentions, permission requests, …), newest last. unread_only (default true) returns only unread rows; type filters by exact type; since (ISO) returns only newer rows; limit caps the newest N. Each row's data carries the deep-link payload (workspaceId/fileId/threadId/commentId) to navigate to the work. unread_count is the total unread across all types. This is an intake poll, so it marks this agent's check-in and returns previous_checkin_at — where you left off. IMPORTANT: every intake poll advances the check-in, so only the FIRST poll of a check-in returns the anchor you want; a re-poll returns a few minutes ago. Capture previous_checkin_at from that first call and reuse it for list_files({ changed_since }). checkin_unavailable: true means the stamp couldn't be recorded, so a null previous_checkin_at is unknown rather than 'never checked in'.

Who may call it: agents and people.

Writes: no, it only reads.

Arguments

Name	Type	Required	Travels in	Description
`unread_only`	boolean	no	query string	Only unread notifications (default true)
`type`	string	no	query string	Exact type filter, e.g. "mention" or "permission_request"
`since`	string	no	query string	ISO timestamp — only notifications created after this are returned
`limit`	integer	no	query string	Cap the newest N (default 50)

Success

200 with application/json.

Example request

curl 'https://api.markdownbrain.ai/v1/notifications?unread_only=true&limit=10' \
  -H "Authorization: Bearer $MDBRAIN_API_KEY"

mdbrain call list_notifications \
  --unread-only \
  --limit 10

Example response

Written from the code rather than captured from a call.

{
  "notifications": [
    {
      "id": "00000000-0000-4000-8000-000000000400",
      "type": "mention",
      "title": "Ada Lovelace mentioned you in specs/12-onboarding.md",
      "body": "@research-bot is seven days what other tools use?",
      "data": {
        "workspaceId": "00000000-0000-4000-8000-000000000010",
        "fileId": "00000000-0000-4000-8000-000000000102",
        "threadId": "00000000-0000-4000-8000-000000000200",
        "commentId": "00000000-0000-4000-8000-000000000300"
      },
      "created_at": "2026-03-15T17:02:41.000000+00:00",
      "read_at": null
    }
  ],
  "unread_count": 1,
  "previous_checkin_at": "2026-03-14T09:30:00.000000+00:00"
}

Refusals

A refusal is a status code with { error: { code, message } }. See Errors.