File systems (VFS)

51 calls. Every request needs the Authorization header: see the overview.

`vfs.list`

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.

Path parameters

Name	Type	Required	Description
`namespaceName`	`string`	yes

Response: VirtualFileSystem[] (200)

curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/vfs" \
  -H "Authorization: $MAITENTO_AUTH"

const systems = await mt.vfs.list({ namespace: "support" });

mt.vfs.list(namespace="demo")

`vfs.create`

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.

Path parameters

Name	Type	Required	Description
`namespaceName`	`string`	yes

Request body: VirtualFileSystemCreateRequest

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

Response: VirtualFileSystem (200)

curl -X POST "https://api.maitento.com/namespaces/<namespaceName>/vfs" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"name":"..."}'

const vfs = await mt.vfs.create({ name: "notes" }, { namespace: "support" });

mt.vfs.create("notes", namespace="demo")

`vfs.deleteByName`

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.

Path parameters

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

Response: no body (204)

curl -X DELETE "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.vfs.deleteByName("notes", { namespace: "support" });

mt.vfs.delete_by_name("notes", namespace="demo")

`vfs.getByName`

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.

Path parameters

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

Response: VirtualFileSystem (200)

curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>" \
  -H "Authorization: $MAITENTO_AUTH"

const vfs = await mt.vfs.getByName("notes", { namespace: "support" });

mt.vfs.get_by_name("notes", namespace="demo")

`vfs.open(name).batchEdit`

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.

Path parameters

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

Request body: BatchEditRequest

Field	Type	Required	Description
`edits`	`BatchEditFileRequest[]`		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 (200)

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}'

await mt.vfs.open("notes").batchEdit({ edits, atomic: true });

mt.vfs.open("notes", namespace="demo").batch_edit(edits=[{"path": "/notes/today.md", "operations": [{"type": "replace", "find": "TODO", "replace": "DONE"}]}])

`vfs.open(name).batchRead`

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.

Path parameters

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

Request body: BatchReadRequest

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 (200)

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}'

const read = await mt.vfs.open("notes").batchRead({ paths: ["/a.md", "/b.md"], maxLinesPerFile: 200 });

mt.vfs.open("notes", namespace="demo").batch_read(paths=["/notes/today.md", "/notes/ideas.md"])

`vfs.open(name).copy`

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.

Path parameters

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

Query parameters

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

Response: FileSystemEntry (200)

curl -X PUT "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/copy" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.vfs.open("notes").copy("/today.md", "/archive/2026-10-26.md");

mt.vfs.open("notes", namespace="demo").copy("/notes/today.md", "/archive/today.md")

`vfs.open(name).deleteDir`

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.

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)

curl -X DELETE "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/directories" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.vfs.open("notes").deleteDir("/archive", { recursive: true });

mt.vfs.open("notes", namespace="demo").delete_dir("/archive", recursive=True)

`vfs.open(name).mkdir`

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.

Path parameters

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

Query parameters

Name	Type	Required	Description
`path`	`string`

Response: FileSystemDirectory (200)

curl -X PUT "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/directories" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.vfs.open("notes").mkdir("/archive");

mt.vfs.open("notes", namespace="demo").mkdir("/archive")

`vfs.open(name).list`

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.

Path parameters

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

Query parameters

Name	Type	Required	Description
`path`	`string`

Response: FileSystemEntry[] (200)

curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/directories/contents" \
  -H "Authorization: $MAITENTO_AUTH"

const entries = await mt.vfs.open("notes").list("/");

mt.vfs.open("notes", namespace="demo").list("/notes")

`vfs.open(name).dirExists`

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.

Path parameters

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

Query parameters

Name	Type	Required	Description
`path`	`string`

Response: boolean (200)

curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/directories/exists" \
  -H "Authorization: $MAITENTO_AUTH"

const exists = await mt.vfs.open("notes").dirExists("/archive");

mt.vfs.open("notes", namespace="demo").dir_exists("/archive")

`vfs.open(name).delete`

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.

Path parameters

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

Query parameters

Name	Type	Required	Description
`path`	`string`

Response: no body (204)

curl -X DELETE "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/files" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.vfs.open("notes").delete("/today.md");

mt.vfs.open("notes", namespace="demo").delete("/notes/old.md")

`vfs.open(name).appendBytes`

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.

Path parameters

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

Query parameters

Name	Type	Required	Description
`path`	`string`

Request body: FileByteContentRequest

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

Response: FileSystemFile (200)

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":"..."}'

await mt.vfs.open("notes").appendBytes("/log.bin", new Uint8Array([1, 2, 3]));

mt.vfs.open("notes", namespace="demo").append_bytes("/logs/run.bin", b"\x00\x01")

`vfs.open(name).appendLines`

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.

Path parameters

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

Query parameters

Name	Type	Required	Description
`path`	`string`

Request body: FileLinesContentRequest

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

Response: FileSystemFile (200)

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":[]}'

await mt.vfs.open("notes").appendLines("/log.txt", ["10:02 deploy started", "10:04 deploy finished"]);

mt.vfs.open("notes", namespace="demo").append_lines("/notes/today.md", ["- call Ada"])

`vfs.open(name).append`

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.

Path parameters

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

Query parameters

Name	Type	Required	Description
`path`	`string`

Request body: FileTextContentRequest

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

Response: FileSystemFile (200)

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":"..."}'

await mt.vfs.open("notes").append("/today.md", "- call Ada\n");

mt.vfs.open("notes", namespace="demo").append("/notes/today.md", "\n- call Ada")

`vfs.open(name).readBytes`

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.

Path parameters

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

Query parameters

Name	Type	Required	Description
`path`	`string`

Response: binary (200)

curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/files/contents/bytes" \
  -H "Authorization: $MAITENTO_AUTH"

const bytes = await mt.vfs.open("notes").readBytes("/logo.png");

mt.vfs.open("notes", namespace="demo").read_bytes("/images/logo.png")

`vfs.open(name).readLines`

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.

Path parameters

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

Query parameters

Name	Type	Required	Description
`path`	`string`

Response: string[] (200)

curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/files/contents/lines" \
  -H "Authorization: $MAITENTO_AUTH"

const lines = await mt.vfs.open("notes").readLines("/today.md");

mt.vfs.open("notes", namespace="demo").read_lines("/notes/today.md")

`vfs.open(name).readText`

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.

Path parameters

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

Query parameters

Name	Type	Required	Description
`path`	`string`

Response: string (200)

curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/files/contents/text" \
  -H "Authorization: $MAITENTO_AUTH"

const text = await mt.vfs.open("notes").readText("/today.md");

mt.vfs.open("notes", namespace="demo").read_text("/notes/today.md")

`vfs.open(name).edit`

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.

Path parameters

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

Request body: EditRequest

Field	Type	Required	Description
`path`	`string`		Path to the file within the file system.
`operations`	`EditOperation[]`		List of edit operations to apply, in order.

Response: EditResponse (200)

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":[]}'

await mt.vfs.open("notes").edit({ path: "/today.md", operations });

mt.vfs.open("notes", namespace="demo").edit(path="/notes/today.md", operations=[{"type": "replace", "find": "TODO", "replace": "DONE"}])

`vfs.open(name).exists`

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.

Path parameters

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

Query parameters

Name	Type	Required	Description
`path`	`string`

Response: boolean (200)

curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/files/exists" \
  -H "Authorization: $MAITENTO_AUTH"

const exists = await mt.vfs.open("notes").exists("/today.md");

mt.vfs.open("notes", namespace="demo").exists("/notes/today.md")

`vfs.open(name).writeBytes`

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.

Path parameters

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

Query parameters

Name	Type	Required	Description
`path`	`string`

Request body: FileByteContentRequest

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

Response: FileSystemFile (200)

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":"..."}'

await mt.vfs.open("notes").writeBytes("/logo.png", pngBytes);

mt.vfs.open("notes", namespace="demo").write_bytes("/images/logo.png", pathlib.Path("logo.png").read_bytes())

`vfs.open(name).writeLines`

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.

Path parameters

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

Query parameters

Name	Type	Required	Description
`path`	`string`

Request body: FileLinesContentRequest

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

Response: FileSystemFile (200)

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":[]}'

await mt.vfs.open("notes").writeLines("/todo.txt", ["call Ada", "ship v2"]);

mt.vfs.open("notes", namespace="demo").write_lines("/notes/today.md", ["# Today", "- ship the SDK"])

`vfs.open(name).writeText`

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.

Path parameters

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

Query parameters

Name	Type	Required	Description
`path`	`string`

Request body: FileTextContentRequest

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

Response: FileSystemFile (200)

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":"..."}'

await mt.vfs.open("notes").writeText("/today.md", "# Today\n");

mt.vfs.open("notes", namespace="demo").write_text("/notes/today.md", "# Today\n- ship the SDK\n")

`vfs.open(name).find`

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.

Path parameters

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

Request body: FindRequest

Field	Type	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 (200)

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}'

const found = await mt.vfs.open("notes").find({ path: "/", grep: "Ada" });

mt.vfs.open("notes", namespace="demo").find(pattern="*.md", grep="TODO")

`vfs.open(name).move`

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.

Path parameters

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

Query parameters

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

Response: FileSystemEntry (200)

curl -X POST "https://api.maitento.com/namespaces/<namespaceName>/vfs/by-name/<name>/move" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.vfs.open("notes").move("/today.md", "/archive/today.md");

mt.vfs.open("notes", namespace="demo").move("/notes/today.md", "/archive/today.md")

`vfs.open(name).tree`

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.

Path parameters

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

Request body: TreeRequest

Field	Type	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 (200)

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":"..."}'

const tree = await mt.vfs.open("notes").tree({ path: "/", maxDepth: 3 });

mt.vfs.open("notes", namespace="demo").tree(path="/", max_depth=2)

`vfs.list`

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.

Response: VirtualFileSystem[] (200)

curl -X GET "https://api.maitento.com/vfs" \
  -H "Authorization: $MAITENTO_AUTH"

const systems = await mt.vfs.list();

mt.vfs.list()

`vfs.delete`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Response: no body (204)

curl -X DELETE "https://api.maitento.com/vfs/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.vfs.delete("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b");

mt.vfs.delete("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b")

`vfs.get`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Response: VirtualFileSystem (200)

curl -X GET "https://api.maitento.com/vfs/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"

const vfs = await mt.vfs.get("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b");

mt.vfs.get("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b")

`vfs.openById(id).batchEdit`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Request body: BatchEditRequest

Field	Type	Required	Description
`edits`	`BatchEditFileRequest[]`		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 (200)

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}'

await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").batchEdit({ edits, atomic: true });

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`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Request body: BatchReadRequest

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 (200)

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}'

const read = await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").batchRead({ paths: ["/a.md"], maxLinesPerFile: 200 });

mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").batch_read(paths=["/notes/today.md", "/notes/ideas.md"])

`vfs.openById(id).copy`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Query parameters

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

Response: FileSystemEntry (200)

curl -X PUT "https://api.maitento.com/vfs/by-id/<id>/copy" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").copy("/today.md", "/archive/today.md");

mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").copy("/notes/today.md", "/archive/today.md")

`vfs.openById(id).deleteDir`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Query parameters

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

Response: no body (204)

curl -X DELETE "https://api.maitento.com/vfs/by-id/<id>/directories" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").deleteDir("/archive", { recursive: true });

mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").delete_dir("/archive", recursive=True)

`vfs.openById(id).mkdir`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Query parameters

Name	Type	Required	Description
`path`	`string`

Response: FileSystemDirectory (200)

curl -X PUT "https://api.maitento.com/vfs/by-id/<id>/directories" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").mkdir("/archive");

mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").mkdir("/archive")

`vfs.openById(id).list`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Query parameters

Name	Type	Required	Description
`path`	`string`

Response: FileSystemEntry[] (200)

curl -X GET "https://api.maitento.com/vfs/by-id/<id>/directories/contents" \
  -H "Authorization: $MAITENTO_AUTH"

const entries = await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").list("/");

mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").list("/notes")

`vfs.openById(id).dirExists`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Query parameters

Name	Type	Required	Description
`path`	`string`

Response: boolean (200)

curl -X GET "https://api.maitento.com/vfs/by-id/<id>/directories/exists" \
  -H "Authorization: $MAITENTO_AUTH"

const exists = await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").dirExists("/archive");

mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").dir_exists("/archive")

`vfs.openById(id).delete`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Query parameters

Name	Type	Required	Description
`path`	`string`

Response: no body (204)

curl -X DELETE "https://api.maitento.com/vfs/by-id/<id>/files" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").delete("/today.md");

mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").delete("/notes/old.md")

`vfs.openById(id).appendBytes`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Query parameters

Name	Type	Required	Description
`path`	`string`

Request body: FileByteContentRequest

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

Response: FileSystemFile (200)

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":"..."}'

await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").appendBytes("/log.bin", new Uint8Array([1, 2, 3]));

mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").append_bytes("/logs/run.bin", b"\x00\x01")

`vfs.openById(id).appendLines`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Query parameters

Name	Type	Required	Description
`path`	`string`

Request body: FileLinesContentRequest

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

Response: FileSystemFile (200)

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":[]}'

await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").appendLines("/log.txt", ["10:02 deploy started"]);

mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").append_lines("/notes/today.md", ["- call Ada"])

`vfs.openById(id).append`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Query parameters

Name	Type	Required	Description
`path`	`string`

Request body: FileTextContentRequest

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

Response: FileSystemFile (200)

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":"..."}'

await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").append("/today.md", "- call Ada\n");

mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").append("/notes/today.md", "\n- call Ada")

`vfs.openById(id).readBytes`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Query parameters

Name	Type	Required	Description
`path`	`string`

Response: binary (200)

curl -X GET "https://api.maitento.com/vfs/by-id/<id>/files/contents/bytes" \
  -H "Authorization: $MAITENTO_AUTH"

const bytes = await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").readBytes("/logo.png");

mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").read_bytes("/images/logo.png")

`vfs.openById(id).readLines`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Query parameters

Name	Type	Required	Description
`path`	`string`

Response: string[] (200)

curl -X GET "https://api.maitento.com/vfs/by-id/<id>/files/contents/lines" \
  -H "Authorization: $MAITENTO_AUTH"

const lines = await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").readLines("/today.md");

mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").read_lines("/notes/today.md")

`vfs.openById(id).readText`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Query parameters

Name	Type	Required	Description
`path`	`string`

Response: string (200)

curl -X GET "https://api.maitento.com/vfs/by-id/<id>/files/contents/text" \
  -H "Authorization: $MAITENTO_AUTH"

const text = await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").readText("/today.md");

mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").read_text("/notes/today.md")

`vfs.openById(id).edit`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Request body: EditRequest

Field	Type	Required	Description
`path`	`string`		Path to the file within the file system.
`operations`	`EditOperation[]`		List of edit operations to apply, in order.

Response: EditResponse (200)

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":[]}'

await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").edit({ path: "/today.md", operations });

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`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Query parameters

Name	Type	Required	Description
`path`	`string`

Response: boolean (200)

curl -X GET "https://api.maitento.com/vfs/by-id/<id>/files/exists" \
  -H "Authorization: $MAITENTO_AUTH"

const exists = await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").exists("/today.md");

mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").exists("/notes/today.md")

`vfs.openById(id).writeBytes`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Query parameters

Name	Type	Required	Description
`path`	`string`

Request body: FileByteContentRequest

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

Response: FileSystemFile (200)

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":"..."}'

await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").writeBytes("/logo.png", pngBytes);

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`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Query parameters

Name	Type	Required	Description
`path`	`string`

Request body: FileLinesContentRequest

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

Response: FileSystemFile (200)

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":[]}'

await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").writeLines("/todo.txt", ["call Ada", "ship v2"]);

mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").write_lines("/notes/today.md", ["# Today", "- ship the SDK"])

`vfs.openById(id).writeText`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Query parameters

Name	Type	Required	Description
`path`	`string`

Request body: FileTextContentRequest

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

Response: FileSystemFile (200)

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":"..."}'

await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").writeText("/today.md", "# Today\n");

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`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Request body: FindRequest

Field	Type	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 (200)

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}'

const found = await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").find({ path: "/", grep: "Ada" });

mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").find(pattern="*.md", grep="TODO")

`vfs.openById(id).move`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Query parameters

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

Response: FileSystemEntry (200)

curl -X POST "https://api.maitento.com/vfs/by-id/<id>/move" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").move("/today.md", "/archive/today.md");

mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").move("/notes/today.md", "/archive/today.md")

`vfs.openById(id).tree`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Request body: TreeRequest

Field	Type	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 (200)

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":"..."}'

const tree = await mt.vfs.openById("e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b").tree({ path: "/", maxDepth: 3 });

mt.vfs.open_by_id("7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b").tree(path="/", max_depth=2)