REST API

Conventions

Find your workspace id in the web app URL (/w/<workspaceId>/…), with GET /api/workspace, or with list_workspaces over MCP.

Files

All paths in this section are relative to /api/workspaces/{workspaceId}/.

Read a file

GET files/{path} returns the raw bytes with these headers:

Send If-None-Match: "<version>" to get 304 Not Modified when you already have that version. Add ?download=1 to get a Content-Disposition: attachment response. Errors: 404 not found, 502 if the stored bytes are missing.

curl -i https://api.trytree.house/api/workspaces/$WS/files/Projects/plan.md \
  -H "x-api-key: $TREEHOUSE_API_KEY"

Write a file

PUT files/{path} with the complete file as the request body. Choose one precondition:

The Content-Type you send is stored with the file. If you send none, it is guessed from the extension. Note that curl --data-binary sends application/x-www-form-urlencoded unless you set the header yourself.

A stale write with content identical to the current file succeeds without creating a copy. See versions and conflicts.

# Update version 3 of a file
curl -X PUT https://api.trytree.house/api/workspaces/$WS/files/Projects/plan.md \
  -H "x-api-key: $TREEHOUSE_API_KEY" \
  -H 'If-Match: "3"' \
  -H "Content-Type: text/markdown" \
  --data-binary @plan.md

# Create a new file, failing safely if it already exists
curl -X PUT https://api.trytree.house/api/workspaces/$WS/files/Inbox/idea.md \
  -H "x-api-key: $TREEHOUSE_API_KEY" \
  -H "If-None-Match: *" \
  -H "Content-Type: text/markdown" \
  --data-binary @idea.md

Delete a file

DELETE files/{path} with If-Match: "<n>" (required, 428 without it). Returns 204. If the file has changed since version n, nothing is deleted and you get 412 with { "error": "version_conflict", "current_version" }.

List files

GET list?prefix=Projects returns every entry under the prefix in one response:

{
  "entries": [
    { "path": "Projects/plan.md", "size": 1204, "contentType": "text/markdown", "version": 3 }
  ],
  "icons": { "Projects": "📁" },
  "orders": { "Projects/plan.md": 0 },
  "privatePaths": [],
  "nextCursor": null
}

Omit prefix for the whole workspace. Entries include .keep files, the hidden placeholders that keep empty folders in place. privatePaths lists items that are private to you. limit and cursor are accepted for forward compatibility but currently have no effect, and nextCursor is always null. If you page, keep requesting until nextCursor is null.

Move a file

POST move with { "from", "to", "baseVersion"? }. Returns { "path", "version": 1 }: a moved file restarts at version 1. With baseVersion, the move only happens if the source is still at that version (412 otherwise). 404 if the source is missing, 409 if the destination exists.

To move a folder, move each file, then call POST move-folder with { "from", "to" } so the folder's own privacy setting, icon and ordering follow it. move-folder does not move any files.

Versions and restore

GET version?path=Projects/plan.md&version=2 returns that version's bytes, with ETag set to the version. 404 if the path or version isn't available.

POST restore with { "path", "targetVersion" } writes that version's bytes as a new version and returns { "path", "version", "restoredFrom" }. If concurrent writes keep winning, it returns 409 with { "error": "restore_conflicted", "current_version", "conflict_copy_path" } and the restored bytes are in the conflicted copy.

Search

GET search?q=clinot&limit=20 fuzzy-matches file and folder paths (not contents), ranked best first:

{
  "results": [
    { "path": "Clients/acme/notes.md", "name": "notes.md", "isDir": false, "score": 41.2 }
  ],
  "totalMatches": 1,
  "truncated": false
}

q is required and at most 200 characters. limit defaults to 50 and is capped at 200. There is no offset: narrow the query instead.

Workspace

Share links

kind is file or folder; access is member or public. API keys can only create member links. Public links, password-protected links, and turning scripts on require a signed-in browser session; with a key they return 403. A key can turn scripts off. Private items can't be shared (409), and folder links can never run scripts (400).

Comments

The list accepts the same filters as the MCP list_comments tool, as query parameters: path, threadId, status, anchorStatus, author, limit, offset, entriesLimit, entriesOffset. It returns { threads, total, nextOffset, truncated }.

Creating a thread takes { path, body, kind, quote?, contextBefore?, contextAfter?, occurrence?, baseVersion? }. Unlike MCP, kind (range or point) is required here. Success is 201 { thread }. A quote that can't be placed returns 409 with anchor_ambiguous (plus occurrences), anchor_not_found or base_version_conflict. A non-markdown file returns 400 { "error": "not_markdown" }, and a read-only workspace 402. Size limits match the MCP server.

Change feed

GET /api/workspaces/{id}/changes?sinceSeq=<n> returns every change after a cursor. See change feed.

Account and top-level endpoints

To list workspaces with an API key, use the MCP list_workspaces tool with an account-wide key.

Content types

When a write doesn't send a Content-Type, the file's type comes from its extension. Anything else is stored as application/octet-stream.

Size limits