File System

The file system API provides CRUD operations on files and directories within the vault. All paths are validated against the vault root -- any attempt to traverse outside it returns 403 Forbidden.

Endpoints

List Directory

GET /api/fs/list

List files and directories at the given path. Directories are sorted first, then alphabetically.

Authentication: Required

Query Parameters:

Response: 200 OK

{
  "data": [
    {
      "name": "projects",
      "path": "/projects",
      "type": "directory",
      "modifiedAt": "2026-02-18T10:00:00.000Z",
      "children": []
    },
    {
      "name": "readme.md",
      "path": "/readme.md",
      "type": "file",
      "size": 1420,
      "modifiedAt": "2026-02-17T15:30:00.000Z"
    }
  ]
}

Errors:

Read File

POST /api/fs/read

Read the contents of a file as UTF-8 text.

Authentication: Required

Request Body:

Response: 200 OK

{
  "data": {
    "path": "/notes/meeting.md",
    "content": "# Meeting Notes\n\nDiscussed the new API...",
    "modifiedAt": "2026-02-18T09:00:00.000Z"
  }
}

Errors:

Write File

POST /api/fs/write

Write content to a file. Creates the file and any missing parent directories if they do not exist. Overwrites existing files.

Authentication: Required

Request Body:

Response: 200 OK

{
  "data": {
    "path": "/notes/new-note.md",
    "created": true
  }
}

The created field is true when the file did not previously exist, false when overwriting.

Create Directory

POST /api/fs/mkdir

Create a new directory. Supports recursive creation (nested paths).

Authentication: Required

Request Body:

Response: 200 OK

{
  "data": {
    "path": "/projects/new-project",
    "created": true
  }
}

Errors:

Rename

POST /api/fs/rename

Rename a file or directory. Both source and destination must be within the vault.

Authentication: Required

Request Body:

Response: 200 OK

{
  "data": {
    "oldPath": "/notes/draft.md",
    "newPath": "/notes/published.md"
  }
}

Errors:

Delete

POST /api/fs/delete

Delete a file or directory. Directories are removed recursively.

Authentication: Required

Request Body:

Response: 200 OK

{
  "data": {
    "path": "/notes/old-note.md",
    "deleted": true
  }
}

Errors:

Move

POST /api/fs/move

Move a file or directory into a destination directory. The destination must be an existing directory -- the source filename is preserved.

Authentication: Required

Request Body:

Response: 200 OK

{
  "data": {
    "oldPath": "/inbox/todo.md",
    "newPath": "/projects/webapp/todo.md",
    "moved": true
  }
}

Errors:

Type Reference

See Database Schema for the full FileEntry type definition.

interface FileEntry {
  name: string
  path: string            // Relative to vault root
  type: 'file' | 'directory'
  size?: number           // Bytes, files only
  modifiedAt?: Date
  children?: FileEntry[]  // Recursive listings only
}