# 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

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

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

## Example response

> Written from the code rather than captured from a call.

```json
{
  "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](/docs/errors).