Workspace API

The workspace API provides file operations for managing files within the configured workspace root directory.

All paths are relative to the workspace root. Path traversal (..) and absolute paths are rejected.

Read File

POST /api/v1/workspace/read

{ "path": "src/main.erl" }

Response:

{
  "path": "src/main.erl",
  "content": "-module(main).\n",
  "size": 15
}

Write File

POST /api/v1/workspace/write

Atomic write (write to temp, then rename). Creates parent directories automatically.

{ "path": "src/new_file.erl", "content": "-module(new_file).\n" }

Edit File

POST /api/v1/workspace/edit

Find-and-replace with exact match. Rejects if old_text appears more than once.

{
  "path": "src/main.erl",
  "old_text": "-module(old_name)",
  "new_text": "-module(new_name)"
}

Response on multiple matches:

{ "error": "multiple matches", "matches": 3 }

Search Files

POST /api/v1/workspace/search

{ "query": "*.erl", "max_results": 50 }

Response:

{
  "results": [
    { "path": "src/main.erl", "size": 256, "modified": "2026-05-18T14:30:45Z" }
  ],
  "count": 1
}

List Files

GET /api/v1/workspace/list?path=.&recursive=true

Response:

{
  "path": ".",
  "entries": [
    { "path": "src/main.erl", "type": "file", "size": 256, "modified": "2026-05-18T14:30:45Z" },
    { "path": "src", "type": "directory", "size": 4096, "modified": "2026-05-18T12:00:00Z" }
  ],
  "count": 2
}