# `POST /vfs/{*path}`

Protected. Requires a valid session cookie (`credentials: 'include'`).

Execute a virtual filesystem applet

Runs a `.applet.js` file from the virtual filesystem for the authenticated user's selected company
and returns the exported function's result.

The applet file must begin with three metadata lines:
`// @applet-input-schema {JSON Schema}` followed by
`// @applet-output-schema {name:type;name:type}` and
`// @applet-description "description"`. The input schema describes the GUI form posted as
`input`. The output line declares the RESULT COLUMNS as typed CSV — `name:type` pairs separated by `;`
(e.g. `id:integer;name:string;active:boolean`); allowed types are `string`, `integer`, `number`,
`boolean` and `date`. The applet exports a function that receives the posted `input` as `applet_input`
and returns a row object (or an array of row objects) keyed by those columns.

Applets return typed CSV, not JSON: `result` is a `;`-separated CSV string with a header row, and the
response also carries `columns` (name/type) and `rows` (data row count). Only declared columns are
emitted, in header order; missing values become empty cells. Execution runs in the same isolated worker
sandbox as the `javascript_execute` tool — including authenticated `fetch()` against this API,
`fs`/`vfs`, `sharp`, ExcelJS, PDFKit and WebCrypto globals.

The path is taken from the URL (like `DELETE /vfs/{*path}`); the run arguments are the JSON body.
Path traversal (`..`), null bytes, and backslashes are rejected with HTTP 400, as is a path that does
not end in `.applet.js`. Read-only database paths are rejected with HTTP 403.


## Path parameters

| Param | Required | Type | Description |
|-------|----------|------|-------------|
| `path` | yes | string | VFS-relative path to the applet file (e.g. `demo.applet.js`, `apps/report.applet.js`) |

## Body (JSON) — _optional_

| Field | Required | Type | Description |
|-------|----------|------|-------------|
| `input` | no | object | Input values passed to the exported applet function as `applet_input`. Defaults to an empty object. |
| `timeout` | no | integer | Execution timeout in milliseconds, clamped to 1000…60000. Default 20000. |
| `max_output` | no | integer | Maximum stdout characters before truncation. Default 20000. |

```json
{
  "input": {},
  "timeout": 1,
  "max_output": 1
}
```

## Signals

On success, emits SSE signal: `vfs` (see [`GET /events`](../events.md)).

## Response `200`

Applet executed successfully

```json
{
  "ok": true,
  "description": "…",
  "result": "id;name\n1;Kaffee",
  "columns": [
    {
      "name": "…",
      "type": "string"
    }
  ],
  "rows": 1,
  "warnings": [
    "…"
  ],
  "stdout": "…",
  "consoleLines": 1,
  "durationMs": 1,
  "truncated": true,
  "truncationNote": "…"
}
```

## Errors

| Status | Description |
|--------|-------------|
| 400 | No company selected, invalid path, not a .applet.js file, invalid input, invalid applet metadata, or applet runtime error — `{"error":"…"}` |
| 401 | Unauthorized — `{"error":"…"}` |
| 403 | Not authorized, or cannot execute read-only database paths — `{"error":"…"}` |
| 404 | Applet not found — `{"error":"…"}` |
| 500 | Sandbox worker harness failure — `{"error":"…"}` |
| 504 | The applet exceeded the execution timeout and was terminated — `{"error":"…"}` |

---

_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._