File API: Read, Write, List, and Manage App Layer Files

The file API provides authenticated access to every app-layer file through a consistent set of logical path operations. All endpoints delegate to server/lib/customware/file_access.js for permission checks, quota enforcement, and layer inheritance — endpoint handlers stay intentionally thin. Every mutating endpoint validates all targets before any write begins, and in clustered mode each worker commits changed logical paths back to the primary before the response finishes.

Path Conventions

The file API accepts logical app paths rather than raw disk paths. The server resolves these at request time regardless of where CUSTOMWARE_PATH has relocated writable storage.

Path form	Resolves to
`~/note.txt`	Authenticated user’s `L2/<username>/note.txt`
`~/folder/`	Trailing slash identifies a directory
`L2/alice/note.txt`	Explicit user layer path
`L1/team/shared.md`	Group layer path
`L0/app/config.yaml`	Base firmware layer path
`/app/L2/alice/note.txt`	Absolute logical path form

.git metadata paths are reserved. The API blocks direct reads, writes, fetches, and path-index entries for .git/ subtrees in every owner root.

GET or POST /api/file_read

Reads one file or a batch of files from the app layer. Returns base64-encoded content by default for binary files; use encoding: "utf8" for text. The frontend client coalesces same-tick reads into a single backend request and retries entries individually on failure. Accepts both GET (with query params) and POST (with a JSON body).

Request — single file

path

string

required

Logical app path to the file, e.g. ~/notes.md or L1/team/config.yaml.

encoding

string

default:"utf8"

"utf8" or "base64". Applied to the returned content.

Request — batch read

files

array

Array of file descriptors. When present, single-file fields are ignored.

Show File descriptor fields

files[].path

string

required

Logical path to the file.

files[].encoding

string

default:"utf8"

Per-entry encoding override.

Response

files

array

Array of read results.

Show Result fields

files[].path

string

Resolved logical path.

files[].content

string

File content in the requested encoding.

files[].encoding

string

Encoding used (utf8 or base64).

{ "path": "~/readme.md", "encoding": "utf8" }

POST /api/file_write

Writes content to a file. Defaults to full replacement but supports incremental mutations via the operation field. Batch writes are supported via the files array. When USER_FOLDER_SIZE_LIMIT_BYTES is set, quota is checked before any write.

Request — single write

path

string

required

Logical app path to the destination file.

content

string

required

Content to write. Text or base64 string depending on encoding.

encoding

string

default:"utf8"

"utf8" or "base64".

operation

string

default:"replace"

Mutation mode. One of "replace", "append", "prepend", or "insert". Insert mode requires exactly one of line, before, or after.

line

number

1-based line number for insert operations. 1 inserts at the top; one past the last line appends at the end.

before

string

Literal string anchor for insert; content is inserted before the first match.

after

string

Literal string anchor for insert; content is inserted after the first match.

Request — batch write

files

array

Array of write descriptors. Top-level operation, line, before, and after act as defaults for each entry.

Show Write descriptor fields

files[].path

string

required

Destination path.

files[].content

string

required

Content to write.

files[].encoding

string

Per-entry encoding.

files[].operation

string

Per-entry operation override.

Response

path

string

Resolved logical path of the written file.

action

string

Always "written".

{ "path": "~/log.txt", "content": "new entry\n", "operation": "append" }

GET or POST /api/file_list

Lists the contents of a directory. Accepts optional access filters for permission-aware discovery. Pass gitRepositories: true with access: "write" to discover writable owner roots eligible for Git history operations. Accepts both GET (with query params) and POST (with a JSON body).

Request

path

string

required

Logical directory path to list. Use a trailing / for directories.

recursive

boolean

default:"false"

Recursively list all nested entries.

access

string

"write" limits results to paths the authenticated user can write.

writableOnly

boolean

default:"false"

Equivalent shorthand for access: "write".

gitRepositories

boolean

default:"false"

When true, returns writable layer owner roots (e.g. L2/alice/) rather than exposing .git metadata paths.

Response

path

string

Resolved directory path.

entries

array

Directory entries.

Show Entry fields

entries[].name

string

Entry name.

entries[].path

string

Full logical path.

entries[].type

string

"file" or "directory".

{ "path": "~/", "recursive": false }

POST or DELETE /api/file_delete

Deletes a single file or folder, or a batch of paths. All targets are validated before any deletion begins. Quota metrics are updated after the delete. Accepts both POST (with a JSON body) and DELETE.

Request — single delete

path

string

required

Logical path to delete.

Request — batch delete

paths

array

Array of logical path strings. When present, path is ignored.

Response

path

string

The deleted path.

action

string

Always "deleted".

{ "path": "~/old-notes.md" }

POST /api/file_move

Moves or renames a file or folder. Supports a batch form via entries. All source and destination paths are validated before any move begins.

Request — single move

fromPath

string

required

Source logical path.

toPath

string

required

Destination logical path.

Request — batch move

entries

array

Array of move pairs. When present, top-level fromPath/toPath are ignored.

Show Move entry fields

entries[].fromPath

string

required

Source path.

entries[].toPath

string

required

Destination path.

Response

fromPath

string

Original path.

toPath

string

New path.

action

string

Always "moved".

{ "fromPath": "~/draft.md", "toPath": "~/published.md" }

POST /api/file_copy

Copies a file or folder. Supports a batch form via entries. When USER_FOLDER_SIZE_LIMIT_BYTES is set, the projected size growth is quota-checked before the copy.

Request — single copy

fromPath

string

required

Source logical path.

toPath

string

required

Destination logical path.

Request — batch copy

entries

array

Array of copy pairs.

Show Copy entry fields

entries[].fromPath

string

required

Source path.

entries[].toPath

string

required

Destination path.

Response

fromPath

string

Source path.

toPath

string

Destination path.

action

string

Always "copied".

{ "fromPath": "~/template.md", "toPath": "~/projects/new-project.md" }

GET or POST /api/file_info

Returns metadata for a single logical path without reading file content. Useful for checking whether a path exists, its type, and layer ownership before a read or write. Accepts both GET (with query params) and POST (with a JSON body).

Request

path

string

required

Logical path to inspect.

Response

path

string

Resolved logical path.

exists

boolean

Whether the path exists.

type

string

"file" or "directory" if it exists.

readable

boolean

Whether the current user can read the path.

writable

boolean

Whether the current user can write the path.

sizeBytes

number

File size in bytes (files only).

{ "path": "~/notes.md" }

GET or POST /api/file_paths

Resolves one or more glob patterns against the indexed file tree. This is the recommended endpoint for catalog and panel discovery; it reads from shared file_index shards rather than walking the filesystem. Supports the same access filters as file_list. Accepts both GET (with query params) and POST (with a JSON body).

Request

patterns

array

required

Array of glob pattern strings to match, e.g. ["mod/*/*/ext/panels/*.yaml"].

access

string

"write" to return only writable matches.

writableOnly

boolean

default:"false"

Shorthand for access: "write".

gitRepositories

boolean

default:"false"

Return writable layer owner roots when combined with a **/.git/ pattern.

maxLayer

number

Cap resolution to a specific layer: 0 = L0 only, 1 = L0 + L1. Omit to include all readable layers.

Response

results

array

One result group per input pattern.

Show Result group fields

pattern

string

The input pattern.

paths

array

Matched logical paths as strings.

{
  "patterns": ["mod/*/*/ext/panels/*.yaml"],
  "access": "write"
}

GET /api/folder_download

Downloads a readable folder as a streaming ZIP attachment. The server creates the archive in server/tmp/ using the Node ZIP helper and streams it without buffering the archive in memory.

This endpoint is GET-only for actual downloads. Send a HEAD request to the same URL to validate permissions without triggering the download.

Query Parameters

path

string

required

Logical path to the folder to download, e.g. ~/projects/.

Response

Returns a binary application/zip response with:

Content-Disposition: attachment; filename="<folder-name>.zip"
Content-Length set to the archive file size
Content-Type: application/zip
Cache-Control: no-store

# Download ~/projects/ as a ZIP
curl -b "space_session=<token>" \
  "https://your-space-agent.example/api/folder_download?path=~/projects/" \
  -o projects.zip

In browser code, use space.api.folderDownloadUrl(path) to get a link URL rather than fetching the blob into memory.

Server API

File API: Read, Write, List, and Manage App Layer Files

Path Conventions

GET or POST /api/file_read

Request — single file

Request — batch read

Response

POST /api/file_write

Request — single write

Request — batch write

Response

GET or POST /api/file_list

Request

Response

POST or DELETE /api/file_delete

Request — single delete

Request — batch delete

Response

POST /api/file_move

Request — single move

Request — batch move

Response

POST /api/file_copy

Request — single copy

Request — batch copy

Response

GET or POST /api/file_info

Request

Response

GET or POST /api/file_paths

Request

Response

GET /api/folder_download

Query Parameters

Response

Build docs developers (and LLMs) love

Server API

Documentation Index

​Path Conventions

​GET or POST /api/file_read

​Request — single file

​Request — batch read

​Response

​POST /api/file_write

​Request — single write

​Request — batch write

​Response

​GET or POST /api/file_list

​Request

​Response

​POST or DELETE /api/file_delete

​Request — single delete

​Request — batch delete

​Response

​POST /api/file_move

​Request — single move

​Request — batch move

​Response

​POST /api/file_copy

​Request — single copy

​Request — batch copy

​Response

​GET or POST /api/file_info

​Request

​Response

​GET or POST /api/file_paths

​Request

​Response

​GET /api/folder_download

​Query Parameters

​Response

Build docs developers (and LLMs) love

Path Conventions

GET or POST /api/file_read

Request — single file

Request — batch read

Response

POST /api/file_write

Request — single write

Request — batch write

Response

GET or POST /api/file_list

Request

Response

POST or DELETE /api/file_delete

Request — single delete

Request — batch delete

Response

POST /api/file_move

Request — single move

Request — batch move

Response

POST /api/file_copy

Request — single copy

Request — batch copy

Response

GET or POST /api/file_info

Request

Response

GET or POST /api/file_paths

Request

Response

GET /api/folder_download

Query Parameters

Response