# Tree

The directory tree of a Space: list it, and make, move, copy, delete, and restore paths.

API reference. Base URL: `https://api.mirabase.dev`

## 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}`](https://mirabase.io/developers/api/spaces.md#spaces-read) 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](https://mirabase.io/developers/files.md#tree)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | 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` | Optional | 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` | Optional | `true` lists every descendant of `path` instead of its direct children. |
| `branch` | Query | `DevBranchRef` | Optional | 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` | Optional | 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` | Optional | The `next_cursor` of the previous page. Omit it to start from the first page. length 1..1024 |
| `limit` | Query | `integer` | Optional | How many items a page holds at most: 1 to 100, 20 by default. 1..100, default: 20 |

### Responses

- `200` `application/json` `DevTreePage`

### Error statuses

`400` `401` `403` `404` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/tree" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

### Example response

```json
{
  "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](https://mirabase.io/developers/files.md#tree)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | 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` | Optional | 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` | Optional | 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` | Optional | `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 | Required | Description |
| --- | --- | --- | --- |
| `operations` | `DevTreeOperation[]` | Required | 1 to 200 operations, applied in order. items 1..200 |

### Responses

- `200` `application/json` `DevTreeOperationsResponse`
- `202` `application/json` `DevJobReceipt`

### Response headers

- `Location` `/v2/jobs/{job_id}`: poll it until `status` is `succeeded` or `failed`.
- `Preference-Applied` `respond-async`.

### Error statuses

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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

```json
{}
```
