Tree
MarkdownThe directory tree of a Space: list it, and make, move, copy, delete, and restore paths.
List a directory
GET/v2/spaces/{space_id}/tree
List a directory, or return one file. A member with a read_root only sees that directory and what is under it: any other path, including / and the directories above the root, returns 404 not_found. GET /v2/spaces/{space_id} shows your read_root. With snapshot the listing is the snapshot's: directories are the ones its files were in, changes_cursor is the snapshot's, and a page cursor from one kind of listing does not work in the other. Needs knowledge:read.
Capability knowledge:read
Guide: Files and versions
Parameters
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | DevSpaceRef | A Space id; default for your default Space (your own, or the only Space you can see); or ext:<external_id> for the Space that carries your own id for it, such as ext:user-42. All three work in a path, in ?space_id=, and in space_ids. An external_id that no visible Space carries returns 404.length 1..256 |
path | Query | DevPath | Absolute path inside a Space: / then names joined by single /, no trailing /. At most 64 levels, 4096 bytes, 255 bytes per name. Names compare by NFKC and case folding and keep the spelling you wrote. ., .., control characters, backslashes, and leading or trailing whitespace are not allowed, and /.mirabase/ is reserved except for /.mirabase/skills/<name>/.... A path over these limits returns 422 path_too_long.length 1..4096 |
recursive | Query | boolean | true lists every descendant of path instead of its direct children. |
branch | Query | DevBranchRef | The branch to use instead of main: its id, or the name of an active branch. For a member with a read_root in this Space, any branch returns 403 outside_read_root. |
snapshot | Query | DevSnapshotRef | A snapshot id or name. Paths, versions, and a read_root are judged as they were when the snapshot was taken; the file must also still be visible to you now. |
cursor | Query | DevCursor | The next_cursor of the previous page. Omit it to start from the first page.length 1..1024 |
limit | Query | integer | How many items a page holds at most: 1 to 100, 20 by default.1..100, default: 20 |
Responses
200application/jsonDevTreePage
Error statuses
400 401 403 404 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/tree" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"data": [
{
"path": "/notes/hello.md",
"name": "research",
"kind": "dir",
"updated_at": "2026-11-06T00:00:00Z"
}
],
"changes_cursor": "<cursor>"
}Run tree operations
POST/v2/spaces/{space_id}/tree/operations
Create directories and move, copy, delete, and restore paths in one request: 1 to 200 operations, applied in order, all of them or none. One request deletes, restores, or copies at most 200 nodes and moves at most 1000; larger subtrees return 409 subtree_too_large. With Prefer: respond-async, a request of one move, copy, recursive delete, or restore by delete_batch_id over the limit runs as a job instead, up to 10,000 nodes, and returns 202 with job_id, Location, and Preference-Applied: respond-async. Everything that can be checked up front is checked before the job exists; each chunk checks permissions again, so revoking a key or a membership stops the job. A job move is one transaction; delete, restore, and copy run in chunks of 200 nodes and are not atomic. A Space runs at most 4 jobs that change the tree at a time, and 4 exports on top of those; the next returns 429 too_many_jobs. copy returns the new Entries in copies. A member with a write_root can only change nodes under it (403 outside_write_root); deleting a directory that is, or contains, any member's write_root returns 409 directory_is_write_root, for the Space owner too. A member with a read_root gets 404 for a from or path outside it and 403 outside_write_root for a target outside its write root, whether or not something is there; deleting a directory that is, or contains, a member's read_root returns 409 directory_is_read_root. Needs knowledge:write.
Capability knowledge:write
Guide: Files and versions
Parameters
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | DevSpaceRef | A Space id; default for your default Space (your own, or the only Space you can see); or ext:<external_id> for the Space that carries your own id for it, such as ext:user-42. All three work in a path, in ?space_id=, and in space_ids. An external_id that no visible Space carries returns 404.length 1..256 |
branch | Query | DevBranchRef | The branch to use instead of main: its id, or the name of an active branch. For a member with a read_root in this Space, any branch returns 403 outside_read_root. |
Idempotency-Key | Header | DevIdempotencyKey | The same Idempotency-Key, principal, API key, operation, and input replay the original result for 24 hours. The same Idempotency-Key with different input returns 409 conflict.length 1..512 |
Prefer | Header | string | respond-async: a request of exactly one operation that would return 409 subtree_too_large runs as a job instead and returns 202 DevJobReceipt. Under the limit the request runs as usual, with no Preference-Applied; several operations over the limit return 422 validation_error with field: "Prefer". Other preferences are ignored. |
Request body
application/json DevTreeOperationsRequest Atomic: all operations apply in order, or none do. One request deletes, restores, or copies at most 200 nodes and moves at most 1000. With branch, restore and copy return 422 (roll back to a checkpoint instead).
| Field | Type | Description |
|---|---|---|
operationsRequired | DevTreeOperation[] | 1 to 200 operations, applied in order.items 1..200 |
Responses
200application/jsonDevTreeOperationsResponse202application/jsonDevJobReceipt
Response headers
Location/v2/jobs/{job_id}: poll it untilstatusissucceededorfailed.Preference-Appliedrespond-async.
Error statuses
400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/tree/operations" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"operations":[{"op":"mkdir","path":"/notes/drafts"}]}'Example response
{}