Skip to main content
The Files API provides secure file operations with path-based access control. Files can be read and written only within allowed paths, and virtual roots provide access to Asta knowledge and user memories.

​
Virtual Roots

Asta provides special virtual paths:
  • asta:knowledge — Access to README.md, CHANGELOG.md, and docs/*.md
  • user:memories — Access to user-specific memories (User.md)

​
List Files

curl -X GET "http://localhost:8000/api/files/list?directory=asta:knowledge" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "root": "asta:knowledge",
  "entries": [
    {
      "name": "README.md",
      "path": "asta:knowledge/README.md",
      "dir": false,
      "size": null
    },
    {
      "name": "CHANGELOG.md",
      "path": "asta:knowledge/CHANGELOG.md",
      "dir": false,
      "size": null
    }
  ]
}

​
Endpoint

GET /api/files/list

​
Query Parameters

​
directory
string
Path to list files from. Use asta:knowledge for Asta docs, user:memories for user memories, or any allowed directory path.

​
Response

​
root
string
The root directory being listed
​
roots
string[]
Available root paths when no directory is specified
​
entries
object[]
List of files and directories
​
entries[].name
string
File or directory name
​
entries[].path
string
Full path to the file/directory
​
entries[].dir
boolean
Whether this is a directory
​
entries[].size
number | null
File size in bytes (null for directories)

​
Read File

curl -X GET "http://localhost:8000/api/files/read?path=asta:knowledge/README.md" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "path": "asta:knowledge/README.md",
  "content": "# Asta\n\nYour personal AI workspace...\n"
}

​
Endpoint

GET /api/files/read

​
Query Parameters

​
path
string
required
Path to the file to read. Can be a virtual path (asta:knowledge/..., user:memories/User.md) or a real path within allowed directories.

​
Response

​
path
string
The requested file path
​
content
string
File contents as UTF-8 text

​
Access Control

If the requested path is not in the allowlist, returns 403 with: 
{
  "error": "Path not in allowed list. You can grant access in Settings → Allowed paths or use the Grant access button.",
  "code": "PATH_ACCESS_REQUEST",
  "requested_path": "/absolute/path/to/file"
}
Clients can display a “Grant access” button and call /api/files/allow-path to add the path.

​
Write File

curl -X PUT "http://localhost:8000/api/files/write?path=workspace/notes.txt" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "My notes for today..."
  }'

{
  "path": "/home/user/workspace/notes.txt",
  "ok": true
}

​
Endpoint

PUT /api/files/write

​
Query Parameters

​
path
string
required
Path to write to. Can be workspace-relative (e.g., workspace/notes.txt) or absolute. Must be within allowed paths.

​
Request Body

​
content
string
required
Content to write to the file (UTF-8)

​
Response

​
path
string
Absolute path where the file was written
​
ok
boolean
Success indicator

​
Special Cases

  • Writing to user:memories/User.md saves user memories
  • Workspace-relative paths are normalized (e.g., ~/workspace/file → workspace/file)
  • Parent directories are created automatically

​
Manage Allowed Paths

​
Get Allowed Paths

curl -X GET "http://localhost:8000/api/files/allowed-paths" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "paths": [
    "/home/user/workspace",
    "/home/user/Documents"
  ]
}

GET /api/files/allowed-paths
Returns the list of allowed base paths (from env + user allowlist).

​
Grant Path Access

curl -X POST "http://localhost:8000/api/files/allow-path" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/home/user/Documents"
  }'

{
  "path": "/home/user/Documents",
  "ok": true
}

POST /api/files/allow-path
​
path
string
required
Path to add to the allowlist (file or directory). If a file, its parent directory is also added.

Build docs developers (and LLMs) love

Get started for freeTalk to us