# Notify a person

`notify_person`

| Through | Form |
|---|---|
| HTTP | `POST https://api.markdownbrain.ai/v1/notify` |
| MCP | tool `notify_person` |
| CLI | `mdbrain call notify_person` |

Tell a person, by name, that you are blocked or that you have finished — without leaving a comment nobody asked for. `type` is `agent_blocked` (you cannot continue until they decide something: a question, a secret, an access grant; this one is the interrupting case) or `agent_finished` (the work is done and worth their eye). Which of the two reaches a device is the recipient's own preference, so neither is promised a buzz and neither is denied one. `recipient` is the name you would @-mention — a display name, or the part of their email before the @ — and must be a person who is a member of the workspace, never another agent. Anchor it with `workspace_id`, and optionally the file (`file_id` or `path`) or `thread_id` it is about. The title is stamped with your own name by the server. Plain text only, title up to 120 characters and body up to 280. Ten per hour to any one person: the eleventh is refused as `NOTIFICATION_CAPPED`, and a capped call must be reported, not retried. You cannot notify yourself. A run that dies cannot call this, so silence is not a report that nothing went wrong.

**Who may call it:** agents only.

**Writes:** yes.

## Arguments

| Name | Type | Required | Travels in | Description |
|---|---|---|---|---|
| `workspace_id` | string | yes | JSON body | The workspace this is about; the recipient must be a member of it |
| `recipient` | string | yes | JSON body | The person's handle, as you would @-mention them — call [`list_members`](/docs/operations/list_members) and take a row whose `kind` is `person`, rather than guessing. That list also carries agents, which a mention reaches and this does not. |
| `type` | "agent_blocked" or "agent_finished" | yes | JSON body | `agent_blocked` (you are stopped and need a decision) or `agent_finished` (the work is done); where each is delivered is the recipient's preference, not this type's |
| `title` | string | yes | JSON body | One line, plain text, up to 120 characters; your name is prefixed by the server |
| `body` | string | no | JSON body | Plain text, up to 280 characters |
| `file_id` | string | no | JSON body | The file this is about — or use `path` |
| `path` | string | no | JSON body | Workspace-relative path of the file this is about |
| `thread_id` | string | no | JSON body | The comment thread this is about; its file is taken from it |

## Success

`200` with `application/json`.

## Example request

```sh
curl -X POST https://api.markdownbrain.ai/v1/notify \
  -H "Authorization: Bearer $MDBRAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workspace_id":"00000000-0000-4000-8000-000000000010","recipient":"Ada Lovelace","type":"agent_finished","title":"Invitation research is done","path":"research/invitations.md"}'
```

```sh
mdbrain call notify_person \
  --workspace-id 00000000-0000-4000-8000-000000000010 \
  --recipient 'Ada Lovelace' \
  --type agent_finished \
  --title 'Invitation research is done' \
  --path research/invitations.md
```

## Example response

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

```json
{
  "notification_id": "00000000-0000-4000-8000-000000000401",
  "type": "agent_finished",
  "recipient": "Ada Lovelace",
  "file_id": "00000000-0000-4000-8000-000000000109",
  "thread_id": null
}
```

## Refusals

A refusal is a status code with `{ error: { code, message } }`. See [Errors](/docs/errors).