# Create comment thread

`create_thread`

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

Start a comment thread anchored to a text range of a file, with a first comment. Name the file with `path` or with `file_id` — exactly one of the two. The `quote` IS the address: give the exact text the comment is about and the server finds it. No character offsets — nothing you hold tells you one, and counting them means re-reading the file. If the quote appears more than once the call is refused, listing each occurrence with its surrounding text, so you can retry with a longer quote (or with `prefix`/`suffix`) in one round trip.

**Who may call it:** agents and people.

**Writes:** yes.

## Arguments

| Name | Type | Required | Travels in | Description |
|---|---|---|---|---|
| `file_id` | string | no | JSON body | file_node id of the file to comment on — or use `path` |
| `path` | string | no | JSON body | Workspace-relative path of the file to comment on |
| `workspace_id` | string | no | JSON body | Only needed to disambiguate a `path` that exists in more than one workspace you can see |
| `quote` | string | yes | JSON body | The exact source text the comment anchors to. Make it long enough to occur once |
| `prefix` | string | no | JSON body | Source immediately BEFORE the quote — only needed to say which occurrence you mean |
| `suffix` | string | no | JSON body | Source immediately AFTER the quote — only needed to say which occurrence you mean |
| `body` | string | yes | JSON body | The first comment's markdown body |

## Success

`201` with `application/json`.

## Example request

```sh
curl -X POST https://api.markdownbrain.ai/v1/threads \
  -H "Authorization: Bearer $MDBRAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"specs/12-onboarding.md","workspace_id":"00000000-0000-4000-8000-000000000010","quote":"Each invitation expires after seven days.","body":"Should an expired invitation tell the person who sent it?"}'
```

```sh
mdbrain call create_thread \
  --path specs/12-onboarding.md \
  --workspace-id 00000000-0000-4000-8000-000000000010 \
  --quote 'Each invitation expires after seven days.' \
  --body 'Should an expired invitation tell the person who sent it?'
```

## Example response

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

```json
{
  "thread_id": "00000000-0000-4000-8000-000000000201",
  "file_id": "00000000-0000-4000-8000-000000000102"
}
```

## Refusals

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