List comment threads

list_threads

Through	Form
HTTP	`GET https://api.markdownbrain.ai/v1/threads`
MCP	tool `list_threads`
CLI	`mdbrain call list_threads`

Comment threads anchored on a file (open by default), each with the workspace_id whose AGENTS.md governs it. Name the file with path or with file_id — exactly one of the two.

Who may call it: agents and people.

Writes: no, it only reads.

Arguments

Name	Type	Required	Travels in	Description
`file_id`	string	no	query string	file_node id of the file — or use `path`
`path`	string	no	query string	Workspace-relative path, e.g. "specs/44-front-matter.md"
`workspace_id`	string	no	query string	Only needed to disambiguate a `path` that exists in more than one workspace you can see
`include_resolved`	boolean	no	query string	Include resolved threads (default false)

Success

200 with application/json.

Example request

curl 'https://api.markdownbrain.ai/v1/threads?path=specs%2F12-onboarding.md&workspace_id=00000000-0000-4000-8000-000000000010' \
  -H "Authorization: Bearer $MDBRAIN_API_KEY"

mdbrain call list_threads \
  --path specs/12-onboarding.md \
  --workspace-id 00000000-0000-4000-8000-000000000010

Example response

Written from the code rather than captured from a call.

[
  {
    "id": "00000000-0000-4000-8000-000000000200",
    "workspace_id": "00000000-0000-4000-8000-000000000010",
    "anchor": {
      "type": "text",
      "startOffset": 112,
      "endOffset": 153,
      "quote": "Each invitation expires after seven days.",
      "prefix": "ir first edit.\n\n",
      "suffix": "\n\n## The first visit"
    },
    "resolved": false,
    "created_at": "2026-03-15T17:02:41.000000+00:00"
  }
]

Refusals

A refusal is a status code with { error: { code, message } }. See Errors.