List files

list_files

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

The file/folder tree of a workspace (id, parent, name, type), with each node's path (its workspace-relative address, which every file tool accepts in place of an id), updated_at (create/rename/move) and content_updated_at (the text itself) — a file's effective last-modified is the LATER of the two. Pass changed_since (ISO) to get only what changed after it; with last_checkin_at from whoami, that's "what changed since I was last here". Narrow a large tree with name_contains (case-insensitive substring of the node's own name) and under (a folder path — return only that subtree); they compose with each other and with changed_since. Each markdown file also carries title (what the document calls itself — a front-matter title:, else its first heading, else its file name tidied up) and summary (a front-matter description:, else its opening prose, truncated), so you can tell what a document is without opening it. summary is null where a document yields no prose; folders and images carry both as null. ARCHIVED nodes are absent — a node someone put away, and everything inside it. They are not gone: list_archived lists them and read_file still returns an archived document's content.

Who may call it: agents and people.

Writes: no, it only reads.

Arguments

Name	Type	Required	Travels in	Description
`workspace_id`	string	yes	query string	Workspace id
`changed_since`	string	no	query string	ISO timestamp — only files whose content or node changed after this are returned
`name_contains`	string	no	query string	Case-insensitive substring of the node's own name — for when you know roughly what it is called
`under`	string	no	query string	Folder path; return only that subtree. "" or omitted means the whole workspace

Success

200 with application/json.

Example request

curl 'https://api.markdownbrain.ai/v1/files?workspace_id=00000000-0000-4000-8000-000000000010&under=specs&changed_since=2026-03-14T09%3A30%3A00Z' \
  -H "Authorization: Bearer $MDBRAIN_API_KEY"

mdbrain call list_files \
  --workspace-id 00000000-0000-4000-8000-000000000010 \
  --under specs \
  --changed-since 2026-03-14T09:30:00Z

Example response

[
  {
    "id": "00000000-0000-4000-8000-000000000102",
    "parent_id": "00000000-0000-4000-8000-000000000101",
    "name": "12-onboarding.md",
    "type": "file",
    "updated_at": "2026-03-02T10:15:00.000000+00:00",
    "content_updated_at": "2026-03-15T16:42:08.000000+00:00",
    "path": "specs/12-onboarding.md",
    "title": "Onboarding",
    "summary": "How a new member goes from the invitation to their first edit, and what each step shows them. - The…"
  }
]

Refusals

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