# File systems (VFS)

51 calls. Every request needs the `Authorization` header: see [the overview](https://docs.maitento.com/reference.md).

## `vfs.list`

```http
GET /namespaces/{namespaceName}/vfs
```

Every VFS of the tenant, or of one namespace with `{ namespace }`.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |

**Response:** [`VirtualFileSystem`](https://docs.maitento.com/reference/types/virtual-file-system.md)`[]` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/vfs" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const systems = await mt.vfs.list({ namespace: "support" });
```
```python title="Python"
mt.vfs.list(namespace="demo")
```

## `vfs.create`

```http
POST /namespaces/{namespaceName}/vfs
```

Creates a VFS in the namespace.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |

**Request body:** [`VirtualFileSystemCreateRequest`](https://docs.maitento.com/reference/types/virtual-file-system-create-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | yes | The file system's name, under 150 characters. |

**Response:** [`VirtualFileSystem`](https://docs.maitento.com/reference/types/virtual-file-system.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/namespaces/<namespaceName>/vfs" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"name":"..."}'
```
```ts title="TypeScript"
const vfs = await mt.vfs.create({ name: "notes" }, { namespace: "support" });
```
```python title="Python"
mt.vfs.create("notes", namespace="demo")
```

## `vfs.deleteByName`

```http
DELETE /namespaces/{namespaceName}/vfs/by-name/{name}
```

Deletes the VFS with this name.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=DELETE%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs%2Fby-name%2F%7Bname%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Response:** no body (204)

```bash title="curl"
curl -X DELETE "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.vfs.deleteByName("notes", { namespace: "support" });
```
```python title="Python"
mt.vfs.delete_by_name("notes", namespace="demo")
```

## `vfs.getByName`

```http
GET /namespaces/{namespaceName}/vfs/by-name/{name}
```

The VFS with this name. Throws `NotFoundError` when there is none.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs%2Fby-name%2F%7Bname%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Response:** [`VirtualFileSystem`](https://docs.maitento.com/reference/types/virtual-file-system.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const vfs = await mt.vfs.getByName("notes", { namespace: "support" });
```
```python title="Python"
mt.vfs.get_by_name("notes", namespace="demo")
```

## `vfs.open(name).batchEdit`

```http
POST /namespaces/{namespaceName}/vfs/by-name/{name}/batch/edit
```

Applies edits to several files (optionally all-or-nothing).

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs%2Fby-name%2F%7Bname%7D%2Fbatch%2Fedit).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Request body:** [`BatchEditRequest`](https://docs.maitento.com/reference/types/batch-edit-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `edits` | [`BatchEditFileRequest`](https://docs.maitento.com/reference/types/batch-edit-file-request.md)`[]` |  | List of file edits to apply. |
| `atomic` | `boolean` |  | If true, all edits must succeed or none are applied. If false, each file is edited independently. |

**Response:** [`BatchEditResponse`](https://docs.maitento.com/reference/types/batch-edit-response.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/batch/edit" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"edits":[],"atomic":false}'
```
```ts title="TypeScript"
await mt.vfs.open("notes").batchEdit({ edits, atomic: true });
```
```python title="Python"
mt.vfs.open("notes", namespace="demo").batch_edit(edits=[{"path": "/notes/today.md", "operations": [{"type": "replace", "find": "TODO", "replace": "DONE"}]}])
```

## `vfs.open(name).batchRead`

```http
POST /namespaces/{namespaceName}/vfs/by-name/{name}/batch/read
```

Reads several files at once.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs%2Fby-name%2F%7Bname%7D%2Fbatch%2Fread).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Request body:** [`BatchReadRequest`](https://docs.maitento.com/reference/types/batch-read-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `paths` | `string[]` |  | Paths to the files to read. |
| `maxLinesPerFile` | `integer` |  | Maximum lines per file (0 = unlimited). Truncates large files. |

**Response:** [`BatchReadResponse`](https://docs.maitento.com/reference/types/batch-read-response.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/batch/read" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"paths":[],"maxLinesPerFile":0}'
```
```ts title="TypeScript"
const read = await mt.vfs.open("notes").batchRead({ paths: ["/a.md", "/b.md"], maxLinesPerFile: 200 });
```
```python title="Python"
mt.vfs.open("notes", namespace="demo").batch_read(paths=["/notes/today.md", "/notes/ideas.md"])
```

## `vfs.open(name).copy`

```http
PUT /namespaces/{namespaceName}/vfs/by-name/{name}/copy
```

Copies a file or directory.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs%2Fby-name%2F%7Bname%7D%2Fcopy).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |
| `destination` | `string` |  |  |

**Response:** [`FileSystemEntry`](https://docs.maitento.com/reference/types/file-system-entry.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/copy" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.vfs.open("notes").copy("/today.md", "/archive/2026-10-26.md");
```
```python title="Python"
mt.vfs.open("notes", namespace="demo").copy("/notes/today.md", "/archive/today.md")
```

## `vfs.open(name).deleteDir`

```http
DELETE /namespaces/{namespaceName}/vfs/by-name/{name}/directories
```

Deletes a directory (with `recursive: true`, and everything in it).

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=DELETE%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs%2Fby-name%2F%7Bname%7D%2Fdirectories).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |
| `recursive` | `boolean` |  |  |

**Response:** no body (204)

```bash title="curl"
curl -X DELETE "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/directories" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.vfs.open("notes").deleteDir("/archive", { recursive: true });
```
```python title="Python"
mt.vfs.open("notes", namespace="demo").delete_dir("/archive", recursive=True)
```

## `vfs.open(name).mkdir`

```http
PUT /namespaces/{namespaceName}/vfs/by-name/{name}/directories
```

Creates a directory.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs%2Fby-name%2F%7Bname%7D%2Fdirectories).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Response:** [`FileSystemDirectory`](https://docs.maitento.com/reference/types/file-system-directory.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/directories" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.vfs.open("notes").mkdir("/archive");
```
```python title="Python"
mt.vfs.open("notes", namespace="demo").mkdir("/archive")
```

## `vfs.open(name).list`

```http
GET /namespaces/{namespaceName}/vfs/by-name/{name}/directories/contents
```

Every VFS of the tenant, or of one namespace with `{ namespace }`.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs%2Fby-name%2F%7Bname%7D%2Fdirectories%2Fcontents).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Response:** [`FileSystemEntry`](https://docs.maitento.com/reference/types/file-system-entry.md)`[]` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/directories/contents" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const entries = await mt.vfs.open("notes").list("/");
```
```python title="Python"
mt.vfs.open("notes", namespace="demo").list("/notes")
```

## `vfs.open(name).dirExists`

```http
GET /namespaces/{namespaceName}/vfs/by-name/{name}/directories/exists
```

Whether a DIRECTORY exists at the path.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs%2Fby-name%2F%7Bname%7D%2Fdirectories%2Fexists).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Response:** `boolean` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/directories/exists" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const exists = await mt.vfs.open("notes").dirExists("/archive");
```
```python title="Python"
mt.vfs.open("notes", namespace="demo").dir_exists("/archive")
```

## `vfs.open(name).delete`

```http
DELETE /namespaces/{namespaceName}/vfs/by-name/{name}/files
```

Deletes the VFS with this id.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=DELETE%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs%2Fby-name%2F%7Bname%7D%2Ffiles).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Response:** no body (204)

```bash title="curl"
curl -X DELETE "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/files" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.vfs.open("notes").delete("/today.md");
```
```python title="Python"
mt.vfs.open("notes", namespace="demo").delete("/notes/old.md")
```

## `vfs.open(name).appendBytes`

```http
PUT /namespaces/{namespaceName}/vfs/by-name/{name}/files/append/bytes
```

Appends bytes to a file. Never retried.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs%2Fby-name%2F%7Bname%7D%2Ffiles%2Fappend%2Fbytes).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Request body:** [`FileByteContentRequest`](https://docs.maitento.com/reference/types/file-byte-content-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `content` | `base64` | yes | The file's bytes, up to 100 MB. May be empty. |

**Response:** [`FileSystemFile`](https://docs.maitento.com/reference/types/file-system-file.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/files/append/bytes" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"content":"..."}'
```
```ts title="TypeScript"
await mt.vfs.open("notes").appendBytes("/log.bin", new Uint8Array([1, 2, 3]));
```
```python title="Python"
mt.vfs.open("notes", namespace="demo").append_bytes("/logs/run.bin", b"\x00\x01")
```

## `vfs.open(name).appendLines`

```http
PUT /namespaces/{namespaceName}/vfs/by-name/{name}/files/append/lines
```

Appends lines to a file. Never retried.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs%2Fby-name%2F%7Bname%7D%2Ffiles%2Fappend%2Flines).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Request body:** [`FileLinesContentRequest`](https://docs.maitento.com/reference/types/file-lines-content-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `content` | `string[]` | yes | The file's lines, up to 100,000. May be empty. |

**Response:** [`FileSystemFile`](https://docs.maitento.com/reference/types/file-system-file.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/files/append/lines" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"content":[]}'
```
```ts title="TypeScript"
await mt.vfs.open("notes").appendLines("/log.txt", ["10:02 deploy started", "10:04 deploy finished"]);
```
```python title="Python"
mt.vfs.open("notes", namespace="demo").append_lines("/notes/today.md", ["- call Ada"])
```

## `vfs.open(name).append`

```http
PUT /namespaces/{namespaceName}/vfs/by-name/{name}/files/append/text
```

Appends text to a file (creating it). Never retried.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs%2Fby-name%2F%7Bname%7D%2Ffiles%2Fappend%2Ftext).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Request body:** [`FileTextContentRequest`](https://docs.maitento.com/reference/types/file-text-content-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `content` | `string` | yes | The file's text, up to 100 MB. Whitespace is kept exactly as sent. |

**Response:** [`FileSystemFile`](https://docs.maitento.com/reference/types/file-system-file.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/files/append/text" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"content":"..."}'
```
```ts title="TypeScript"
await mt.vfs.open("notes").append("/today.md", "- call Ada\n");
```
```python title="Python"
mt.vfs.open("notes", namespace="demo").append("/notes/today.md", "\n- call Ada")
```

## `vfs.open(name).readBytes`

```http
GET /namespaces/{namespaceName}/vfs/by-name/{name}/files/contents/bytes
```

A file's bytes.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs%2Fby-name%2F%7Bname%7D%2Ffiles%2Fcontents%2Fbytes).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Response:** `binary` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/files/contents/bytes" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const bytes = await mt.vfs.open("notes").readBytes("/logo.png");
```
```python title="Python"
mt.vfs.open("notes", namespace="demo").read_bytes("/images/logo.png")
```

## `vfs.open(name).readLines`

```http
GET /namespaces/{namespaceName}/vfs/by-name/{name}/files/contents/lines
```

A file's lines.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs%2Fby-name%2F%7Bname%7D%2Ffiles%2Fcontents%2Flines).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Response:** `string[]` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/files/contents/lines" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const lines = await mt.vfs.open("notes").readLines("/today.md");
```
```python title="Python"
mt.vfs.open("notes", namespace="demo").read_lines("/notes/today.md")
```

## `vfs.open(name).readText`

```http
GET /namespaces/{namespaceName}/vfs/by-name/{name}/files/contents/text
```

A file's text, exactly as stored.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs%2Fby-name%2F%7Bname%7D%2Ffiles%2Fcontents%2Ftext).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Response:** `string` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/files/contents/text" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const text = await mt.vfs.open("notes").readText("/today.md");
```
```python title="Python"
mt.vfs.open("notes", namespace="demo").read_text("/notes/today.md")
```

## `vfs.open(name).edit`

```http
POST /namespaces/{namespaceName}/vfs/by-name/{name}/files/edit
```

Applies edit operations to one file.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs%2Fby-name%2F%7Bname%7D%2Ffiles%2Fedit).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Request body:** [`EditRequest`](https://docs.maitento.com/reference/types/edit-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  | Path to the file within the file system. |
| `operations` | [`EditOperation`](https://docs.maitento.com/reference/types/edit-operation.md)`[]` |  | List of edit operations to apply, in order. |

**Response:** [`EditResponse`](https://docs.maitento.com/reference/types/edit-response.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/files/edit" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"path":"...","operations":[]}'
```
```ts title="TypeScript"
await mt.vfs.open("notes").edit({ path: "/today.md", operations });
```
```python title="Python"
mt.vfs.open("notes", namespace="demo").edit(path="/notes/today.md", operations=[{"type": "replace", "find": "TODO", "replace": "DONE"}])
```

## `vfs.open(name).exists`

```http
GET /namespaces/{namespaceName}/vfs/by-name/{name}/files/exists
```

Whether a FILE exists at the path.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs%2Fby-name%2F%7Bname%7D%2Ffiles%2Fexists).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Response:** `boolean` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/files/exists" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const exists = await mt.vfs.open("notes").exists("/today.md");
```
```python title="Python"
mt.vfs.open("notes", namespace="demo").exists("/notes/today.md")
```

## `vfs.open(name).writeBytes`

```http
PUT /namespaces/{namespaceName}/vfs/by-name/{name}/files/write/bytes
```

Writes (creates or replaces) a binary file.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs%2Fby-name%2F%7Bname%7D%2Ffiles%2Fwrite%2Fbytes).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Request body:** [`FileByteContentRequest`](https://docs.maitento.com/reference/types/file-byte-content-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `content` | `base64` | yes | The file's bytes, up to 100 MB. May be empty. |

**Response:** [`FileSystemFile`](https://docs.maitento.com/reference/types/file-system-file.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/files/write/bytes" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"content":"..."}'
```
```ts title="TypeScript"
await mt.vfs.open("notes").writeBytes("/logo.png", pngBytes);
```
```python title="Python"
mt.vfs.open("notes", namespace="demo").write_bytes("/images/logo.png", pathlib.Path("logo.png").read_bytes())
```

## `vfs.open(name).writeLines`

```http
PUT /namespaces/{namespaceName}/vfs/by-name/{name}/files/write/lines
```

Writes (creates or replaces) a file from lines.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs%2Fby-name%2F%7Bname%7D%2Ffiles%2Fwrite%2Flines).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Request body:** [`FileLinesContentRequest`](https://docs.maitento.com/reference/types/file-lines-content-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `content` | `string[]` | yes | The file's lines, up to 100,000. May be empty. |

**Response:** [`FileSystemFile`](https://docs.maitento.com/reference/types/file-system-file.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/files/write/lines" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"content":[]}'
```
```ts title="TypeScript"
await mt.vfs.open("notes").writeLines("/todo.txt", ["call Ada", "ship v2"]);
```
```python title="Python"
mt.vfs.open("notes", namespace="demo").write_lines("/notes/today.md", ["# Today", "- ship the SDK"])
```

## `vfs.open(name).writeText`

```http
PUT /namespaces/{namespaceName}/vfs/by-name/{name}/files/write/text
```

Writes (creates or replaces) a text file.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs%2Fby-name%2F%7Bname%7D%2Ffiles%2Fwrite%2Ftext).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Request body:** [`FileTextContentRequest`](https://docs.maitento.com/reference/types/file-text-content-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `content` | `string` | yes | The file's text, up to 100 MB. Whitespace is kept exactly as sent. |

**Response:** [`FileSystemFile`](https://docs.maitento.com/reference/types/file-system-file.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/files/write/text" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"content":"..."}'
```
```ts title="TypeScript"
await mt.vfs.open("notes").writeText("/today.md", "# Today\n");
```
```python title="Python"
mt.vfs.open("notes", namespace="demo").write_text("/notes/today.md", "# Today\n- ship the SDK\n")
```

## `vfs.open(name).find`

```http
POST /namespaces/{namespaceName}/vfs/by-name/{name}/find
```

The VFS with this id, or `null`.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs%2Fby-name%2F%7Bname%7D%2Ffind).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Request body:** [`FindRequest`](https://docs.maitento.com/reference/types/find-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  | Starting directory path. Defaults to "/" (root). |
| `pattern` | `string \| null` |  | Glob pattern to match files (e.g., "**/*.cs", "src/**/*.ts"). Supports *, **, ?, [abc], {a,b} patterns. |
| `grep` | `string \| null` |  | Search pattern for file contents. If specified, only files containing this pattern are returned. |
| `grepMode` | `string` |  | How to interpret the grep pattern: "literal" (default) or "regex". |
| `ignoreCase` | `boolean` |  | Case-insensitive search for grep. Default false. |
| `contextLines` | `integer` |  | Number of lines before and after each grep match to include as context. |
| `includePreview` | `boolean` |  | If true, include a preview of each file's content (first N lines). |
| `previewLines` | `integer` |  | Number of lines to include in preview. Default 30. |
| `maxResults` | `integer` |  | Maximum number of results to return. Default 100. |
| `maxDepth` | `integer` |  | Maximum recursion depth. Default -1 (unlimited). |
| `type` | `string` |  | Filter by entry type: "file", "directory", or "all". Default "file". |
| `includeHidden` | `boolean` |  | Include hidden files/directories (starting with .). Default false. |

**Response:** [`FindResponse`](https://docs.maitento.com/reference/types/find-response.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/find" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"path":"...","pattern":"...","grep":"...","grepMode":"...","ignoreCase":false,"contextLines":0,"includePreview":false,"previewLines":0,"maxResults":0,"maxDepth":0,"type":"...","includeHidden":false}'
```
```ts title="TypeScript"
const found = await mt.vfs.open("notes").find({ path: "/", grep: "Ada" });
```
```python title="Python"
mt.vfs.open("notes", namespace="demo").find(pattern="*.md", grep="TODO")
```

## `vfs.open(name).move`

```http
POST /namespaces/{namespaceName}/vfs/by-name/{name}/move
```

Moves a file or directory.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs%2Fby-name%2F%7Bname%7D%2Fmove).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |
| `destination` | `string` |  |  |

**Response:** [`FileSystemEntry`](https://docs.maitento.com/reference/types/file-system-entry.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/move" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.vfs.open("notes").move("/today.md", "/archive/today.md");
```
```python title="Python"
mt.vfs.open("notes", namespace="demo").move("/notes/today.md", "/archive/today.md")
```

## `vfs.open(name).tree`

```http
POST /namespaces/{namespaceName}/vfs/by-name/{name}/tree
```

The directory tree below a path.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fvfs%2Fby-name%2F%7Bname%7D%2Ftree).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Request body:** [`TreeRequest`](https://docs.maitento.com/reference/types/tree-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  | Starting path. Defaults to "/". |
| `maxDepth` | `integer` |  | Maximum depth to recurse. -1 for unlimited. |
| `includeFiles` | `boolean` |  | Include files in output (not just directories). |
| `includeHidden` | `boolean` |  | Include hidden files/directories. |
| `pattern` | `string \| null` |  | Glob pattern to filter results (optional). |

**Response:** [`TreeResponse`](https://docs.maitento.com/reference/types/tree-response.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/tree" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"path":"...","maxDepth":0,"includeFiles":false,"includeHidden":false,"pattern":"..."}'
```
```ts title="TypeScript"
const tree = await mt.vfs.open("notes").tree({ path: "/", maxDepth: 3 });
```
```python title="Python"
mt.vfs.open("notes", namespace="demo").tree(path="/", max_depth=2)
```

## `vfs.list`

```http
GET /vfs
```

Every VFS of the tenant, or of one namespace with `{ namespace }`.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fvfs).

**Response:** [`VirtualFileSystem`](https://docs.maitento.com/reference/types/virtual-file-system.md)`[]` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/vfs" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const systems = await mt.vfs.list();
```
```python title="Python"
mt.vfs.list()
```

## `vfs.delete`

```http
DELETE /vfs/by-id/{id}
```

Deletes the VFS with this id.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=DELETE%20%2Fvfs%2Fby-id%2F%7Bid%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Response:** no body (204)

```bash title="curl"
curl -X DELETE "https://api.maitento.com/vfs/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.vfs.delete("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b");
```
```python title="Python"
mt.vfs.delete("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b")
```

## `vfs.get`

```http
GET /vfs/by-id/{id}
```

The VFS with this id. Throws `NotFoundError` when there is none.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fvfs%2Fby-id%2F%7Bid%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Response:** [`VirtualFileSystem`](https://docs.maitento.com/reference/types/virtual-file-system.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/vfs/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const vfs = await mt.vfs.get("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b");
```
```python title="Python"
mt.vfs.get("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b")
```

## `vfs.openById(id).batchEdit`

```http
POST /vfs/by-id/{id}/batch/edit
```

Applies edits to several files (optionally all-or-nothing).

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fvfs%2Fby-id%2F%7Bid%7D%2Fbatch%2Fedit).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Request body:** [`BatchEditRequest`](https://docs.maitento.com/reference/types/batch-edit-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `edits` | [`BatchEditFileRequest`](https://docs.maitento.com/reference/types/batch-edit-file-request.md)`[]` |  | List of file edits to apply. |
| `atomic` | `boolean` |  | If true, all edits must succeed or none are applied. If false, each file is edited independently. |

**Response:** [`BatchEditResponse`](https://docs.maitento.com/reference/types/batch-edit-response.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/vfs/by-id/<id>/batch/edit" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"edits":[],"atomic":false}'
```
```ts title="TypeScript"
await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").batchEdit({ edits, atomic: true });
```
```python title="Python"
mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").batch_edit(edits=[{"path": "/notes/today.md", "operations": [{"type": "replace", "find": "TODO", "replace": "DONE"}]}])
```

## `vfs.openById(id).batchRead`

```http
POST /vfs/by-id/{id}/batch/read
```

Reads several files at once.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fvfs%2Fby-id%2F%7Bid%7D%2Fbatch%2Fread).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Request body:** [`BatchReadRequest`](https://docs.maitento.com/reference/types/batch-read-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `paths` | `string[]` |  | Paths to the files to read. |
| `maxLinesPerFile` | `integer` |  | Maximum lines per file (0 = unlimited). Truncates large files. |

**Response:** [`BatchReadResponse`](https://docs.maitento.com/reference/types/batch-read-response.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/vfs/by-id/<id>/batch/read" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"paths":[],"maxLinesPerFile":0}'
```
```ts title="TypeScript"
const read = await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").batchRead({ paths: ["/a.md"], maxLinesPerFile: 200 });
```
```python title="Python"
mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").batch_read(paths=["/notes/today.md", "/notes/ideas.md"])
```

## `vfs.openById(id).copy`

```http
PUT /vfs/by-id/{id}/copy
```

Copies a file or directory.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Fvfs%2Fby-id%2F%7Bid%7D%2Fcopy).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |
| `destination` | `string` |  |  |

**Response:** [`FileSystemEntry`](https://docs.maitento.com/reference/types/file-system-entry.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/vfs/by-id/<id>/copy" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").copy("/today.md", "/archive/today.md");
```
```python title="Python"
mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").copy("/notes/today.md", "/archive/today.md")
```

## `vfs.openById(id).deleteDir`

```http
DELETE /vfs/by-id/{id}/directories
```

Deletes a directory (with `recursive: true`, and everything in it).

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=DELETE%20%2Fvfs%2Fby-id%2F%7Bid%7D%2Fdirectories).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |
| `recursive` | `boolean` |  |  |

**Response:** no body (204)

```bash title="curl"
curl -X DELETE "https://api.maitento.com/vfs/by-id/<id>/directories" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").deleteDir("/archive", { recursive: true });
```
```python title="Python"
mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").delete_dir("/archive", recursive=True)
```

## `vfs.openById(id).mkdir`

```http
PUT /vfs/by-id/{id}/directories
```

Creates a directory.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Fvfs%2Fby-id%2F%7Bid%7D%2Fdirectories).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Response:** [`FileSystemDirectory`](https://docs.maitento.com/reference/types/file-system-directory.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/vfs/by-id/<id>/directories" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").mkdir("/archive");
```
```python title="Python"
mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").mkdir("/archive")
```

## `vfs.openById(id).list`

```http
GET /vfs/by-id/{id}/directories/contents
```

Every VFS of the tenant, or of one namespace with `{ namespace }`.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fvfs%2Fby-id%2F%7Bid%7D%2Fdirectories%2Fcontents).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Response:** [`FileSystemEntry`](https://docs.maitento.com/reference/types/file-system-entry.md)`[]` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/vfs/by-id/<id>/directories/contents" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const entries = await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").list("/");
```
```python title="Python"
mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").list("/notes")
```

## `vfs.openById(id).dirExists`

```http
GET /vfs/by-id/{id}/directories/exists
```

Whether a DIRECTORY exists at the path.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fvfs%2Fby-id%2F%7Bid%7D%2Fdirectories%2Fexists).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Response:** `boolean` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/vfs/by-id/<id>/directories/exists" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const exists = await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").dirExists("/archive");
```
```python title="Python"
mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").dir_exists("/archive")
```

## `vfs.openById(id).delete`

```http
DELETE /vfs/by-id/{id}/files
```

Deletes the VFS with this id.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=DELETE%20%2Fvfs%2Fby-id%2F%7Bid%7D%2Ffiles).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Response:** no body (204)

```bash title="curl"
curl -X DELETE "https://api.maitento.com/vfs/by-id/<id>/files" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").delete("/today.md");
```
```python title="Python"
mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").delete("/notes/old.md")
```

## `vfs.openById(id).appendBytes`

```http
PUT /vfs/by-id/{id}/files/append/bytes
```

Appends bytes to a file. Never retried.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Fvfs%2Fby-id%2F%7Bid%7D%2Ffiles%2Fappend%2Fbytes).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Request body:** [`FileByteContentRequest`](https://docs.maitento.com/reference/types/file-byte-content-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `content` | `base64` | yes | The file's bytes, up to 100 MB. May be empty. |

**Response:** [`FileSystemFile`](https://docs.maitento.com/reference/types/file-system-file.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/vfs/by-id/<id>/files/append/bytes" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"content":"..."}'
```
```ts title="TypeScript"
await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").appendBytes("/log.bin", new Uint8Array([1, 2, 3]));
```
```python title="Python"
mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").append_bytes("/logs/run.bin", b"\x00\x01")
```

## `vfs.openById(id).appendLines`

```http
PUT /vfs/by-id/{id}/files/append/lines
```

Appends lines to a file. Never retried.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Fvfs%2Fby-id%2F%7Bid%7D%2Ffiles%2Fappend%2Flines).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Request body:** [`FileLinesContentRequest`](https://docs.maitento.com/reference/types/file-lines-content-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `content` | `string[]` | yes | The file's lines, up to 100,000. May be empty. |

**Response:** [`FileSystemFile`](https://docs.maitento.com/reference/types/file-system-file.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/vfs/by-id/<id>/files/append/lines" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"content":[]}'
```
```ts title="TypeScript"
await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").appendLines("/log.txt", ["10:02 deploy started"]);
```
```python title="Python"
mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").append_lines("/notes/today.md", ["- call Ada"])
```

## `vfs.openById(id).append`

```http
PUT /vfs/by-id/{id}/files/append/text
```

Appends text to a file (creating it). Never retried.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Fvfs%2Fby-id%2F%7Bid%7D%2Ffiles%2Fappend%2Ftext).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Request body:** [`FileTextContentRequest`](https://docs.maitento.com/reference/types/file-text-content-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `content` | `string` | yes | The file's text, up to 100 MB. Whitespace is kept exactly as sent. |

**Response:** [`FileSystemFile`](https://docs.maitento.com/reference/types/file-system-file.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/vfs/by-id/<id>/files/append/text" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"content":"..."}'
```
```ts title="TypeScript"
await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").append("/today.md", "- call Ada\n");
```
```python title="Python"
mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").append("/notes/today.md", "\n- call Ada")
```

## `vfs.openById(id).readBytes`

```http
GET /vfs/by-id/{id}/files/contents/bytes
```

A file's bytes.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fvfs%2Fby-id%2F%7Bid%7D%2Ffiles%2Fcontents%2Fbytes).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Response:** `binary` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/vfs/by-id/<id>/files/contents/bytes" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const bytes = await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").readBytes("/logo.png");
```
```python title="Python"
mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").read_bytes("/images/logo.png")
```

## `vfs.openById(id).readLines`

```http
GET /vfs/by-id/{id}/files/contents/lines
```

A file's lines.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fvfs%2Fby-id%2F%7Bid%7D%2Ffiles%2Fcontents%2Flines).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Response:** `string[]` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/vfs/by-id/<id>/files/contents/lines" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const lines = await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").readLines("/today.md");
```
```python title="Python"
mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").read_lines("/notes/today.md")
```

## `vfs.openById(id).readText`

```http
GET /vfs/by-id/{id}/files/contents/text
```

A file's text, exactly as stored.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fvfs%2Fby-id%2F%7Bid%7D%2Ffiles%2Fcontents%2Ftext).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Response:** `string` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/vfs/by-id/<id>/files/contents/text" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const text = await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").readText("/today.md");
```
```python title="Python"
mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").read_text("/notes/today.md")
```

## `vfs.openById(id).edit`

```http
POST /vfs/by-id/{id}/files/edit
```

Applies edit operations to one file.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fvfs%2Fby-id%2F%7Bid%7D%2Ffiles%2Fedit).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Request body:** [`EditRequest`](https://docs.maitento.com/reference/types/edit-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  | Path to the file within the file system. |
| `operations` | [`EditOperation`](https://docs.maitento.com/reference/types/edit-operation.md)`[]` |  | List of edit operations to apply, in order. |

**Response:** [`EditResponse`](https://docs.maitento.com/reference/types/edit-response.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/vfs/by-id/<id>/files/edit" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"path":"...","operations":[]}'
```
```ts title="TypeScript"
await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").edit({ path: "/today.md", operations });
```
```python title="Python"
mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").edit(path="/notes/today.md", operations=[{"type": "replace", "find": "TODO", "replace": "DONE"}])
```

## `vfs.openById(id).exists`

```http
GET /vfs/by-id/{id}/files/exists
```

Whether a FILE exists at the path.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fvfs%2Fby-id%2F%7Bid%7D%2Ffiles%2Fexists).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Response:** `boolean` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/vfs/by-id/<id>/files/exists" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const exists = await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").exists("/today.md");
```
```python title="Python"
mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").exists("/notes/today.md")
```

## `vfs.openById(id).writeBytes`

```http
PUT /vfs/by-id/{id}/files/write/bytes
```

Writes (creates or replaces) a binary file.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Fvfs%2Fby-id%2F%7Bid%7D%2Ffiles%2Fwrite%2Fbytes).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Request body:** [`FileByteContentRequest`](https://docs.maitento.com/reference/types/file-byte-content-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `content` | `base64` | yes | The file's bytes, up to 100 MB. May be empty. |

**Response:** [`FileSystemFile`](https://docs.maitento.com/reference/types/file-system-file.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/vfs/by-id/<id>/files/write/bytes" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"content":"..."}'
```
```ts title="TypeScript"
await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").writeBytes("/logo.png", pngBytes);
```
```python title="Python"
mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").write_bytes("/images/logo.png", pathlib.Path("logo.png").read_bytes())
```

## `vfs.openById(id).writeLines`

```http
PUT /vfs/by-id/{id}/files/write/lines
```

Writes (creates or replaces) a file from lines.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Fvfs%2Fby-id%2F%7Bid%7D%2Ffiles%2Fwrite%2Flines).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Request body:** [`FileLinesContentRequest`](https://docs.maitento.com/reference/types/file-lines-content-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `content` | `string[]` | yes | The file's lines, up to 100,000. May be empty. |

**Response:** [`FileSystemFile`](https://docs.maitento.com/reference/types/file-system-file.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/vfs/by-id/<id>/files/write/lines" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"content":[]}'
```
```ts title="TypeScript"
await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").writeLines("/todo.txt", ["call Ada", "ship v2"]);
```
```python title="Python"
mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").write_lines("/notes/today.md", ["# Today", "- ship the SDK"])
```

## `vfs.openById(id).writeText`

```http
PUT /vfs/by-id/{id}/files/write/text
```

Writes (creates or replaces) a text file.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Fvfs%2Fby-id%2F%7Bid%7D%2Ffiles%2Fwrite%2Ftext).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |

**Request body:** [`FileTextContentRequest`](https://docs.maitento.com/reference/types/file-text-content-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `content` | `string` | yes | The file's text, up to 100 MB. Whitespace is kept exactly as sent. |

**Response:** [`FileSystemFile`](https://docs.maitento.com/reference/types/file-system-file.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/vfs/by-id/<id>/files/write/text" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"content":"..."}'
```
```ts title="TypeScript"
await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").writeText("/today.md", "# Today\n");
```
```python title="Python"
mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").write_text("/notes/today.md", "# Today\n- ship the SDK\n")
```

## `vfs.openById(id).find`

```http
POST /vfs/by-id/{id}/find
```

The VFS with this id, or `null`.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fvfs%2Fby-id%2F%7Bid%7D%2Ffind).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Request body:** [`FindRequest`](https://docs.maitento.com/reference/types/find-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  | Starting directory path. Defaults to "/" (root). |
| `pattern` | `string \| null` |  | Glob pattern to match files (e.g., "**/*.cs", "src/**/*.ts"). Supports *, **, ?, [abc], {a,b} patterns. |
| `grep` | `string \| null` |  | Search pattern for file contents. If specified, only files containing this pattern are returned. |
| `grepMode` | `string` |  | How to interpret the grep pattern: "literal" (default) or "regex". |
| `ignoreCase` | `boolean` |  | Case-insensitive search for grep. Default false. |
| `contextLines` | `integer` |  | Number of lines before and after each grep match to include as context. |
| `includePreview` | `boolean` |  | If true, include a preview of each file's content (first N lines). |
| `previewLines` | `integer` |  | Number of lines to include in preview. Default 30. |
| `maxResults` | `integer` |  | Maximum number of results to return. Default 100. |
| `maxDepth` | `integer` |  | Maximum recursion depth. Default -1 (unlimited). |
| `type` | `string` |  | Filter by entry type: "file", "directory", or "all". Default "file". |
| `includeHidden` | `boolean` |  | Include hidden files/directories (starting with .). Default false. |

**Response:** [`FindResponse`](https://docs.maitento.com/reference/types/find-response.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/vfs/by-id/<id>/find" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"path":"...","pattern":"...","grep":"...","grepMode":"...","ignoreCase":false,"contextLines":0,"includePreview":false,"previewLines":0,"maxResults":0,"maxDepth":0,"type":"...","includeHidden":false}'
```
```ts title="TypeScript"
const found = await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").find({ path: "/", grep: "Ada" });
```
```python title="Python"
mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").find(pattern="*.md", grep="TODO")
```

## `vfs.openById(id).move`

```http
POST /vfs/by-id/{id}/move
```

Moves a file or directory.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fvfs%2Fby-id%2F%7Bid%7D%2Fmove).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  |  |
| `destination` | `string` |  |  |

**Response:** [`FileSystemEntry`](https://docs.maitento.com/reference/types/file-system-entry.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/vfs/by-id/<id>/move" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").move("/today.md", "/archive/today.md");
```
```python title="Python"
mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").move("/notes/today.md", "/archive/today.md")
```

## `vfs.openById(id).tree`

```http
POST /vfs/by-id/{id}/tree
```

The directory tree below a path.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fvfs%2Fby-id%2F%7Bid%7D%2Ftree).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Request body:** [`TreeRequest`](https://docs.maitento.com/reference/types/tree-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `path` | `string` |  | Starting path. Defaults to "/". |
| `maxDepth` | `integer` |  | Maximum depth to recurse. -1 for unlimited. |
| `includeFiles` | `boolean` |  | Include files in output (not just directories). |
| `includeHidden` | `boolean` |  | Include hidden files/directories. |
| `pattern` | `string \| null` |  | Glob pattern to filter results (optional). |

**Response:** [`TreeResponse`](https://docs.maitento.com/reference/types/tree-response.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/vfs/by-id/<id>/tree" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"path":"...","maxDepth":0,"includeFiles":false,"includeHidden":false,"pattern":"..."}'
```
```ts title="TypeScript"
const tree = await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").tree({ path: "/", maxDepth: 3 });
```
```python title="Python"
mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").tree(path="/", max_depth=2)
```