src/backend/doc/modules/filesystem/API_SPEC.md

Filesystem API

Filesystem endpoints allow operations on files and directories in the Puter filesystem.

POST /mkdir (auth required)

Description

Creates a new directory in the filesystem. Currently support 2 formats:

• Full path: {"path": "/foo/bar", args ...} — this API is used by apitest (./tools/api-tester/apitest.js) and aligns more closely with the POSIX spec (https://linux.die.net/man/3/mkdir)
• Parent + path: {"parent": "/foo", "path": "bar", args ...} — this API is used by puter-js via puter.fs.mkdir

A future work would be use a unified format for all filesystem operations.

Parameters

• path - required

  • accepts: string
  • description: The path where the directory should be created
  • notes: Cannot be empty, null, or undefined

• parent - optional

  • accepts: string | UUID
  • description: The parent directory path or UUID
  • notes: If not provided, path is treated as full path

• overwrite - optional

  • accepts: boolean
  • default: false
  • description: Whether to overwrite existing files/directories

• dedupe_name - optional

  • accepts: boolean
  • default: false
  • description: Whether to automatically rename if name exists

• create_missing_parents - optional

  • accepts: boolean
  • default: false
  • description: Whether to create parent directories if they don't exist
  • aliases: create_missing_ancestors

• shortcut_to - optional

  • accepts: string | UUID
  • description: Creates a shortcut/symlink to the specified target

Example

{
  "path": "/user/Desktop/new-directory"
}

{
  "parent": "/user",
  "path": "Desktop/new-directory"
}

Response

Returns the created directory's metadata including name, path, uid, and any parent directories created.

Other Filesystem Endpoints

[Additional endpoints would be documented here...]