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

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?"}'

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.

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