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 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
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"}'
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.
{
"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.