# `POST /vfs/upload`

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

Upload files to virtual filesystem

Uploads one or more files to the virtual filesystem for the authenticated user's selected company.
Files are written to the company's VFS root directory and saved to the database.
An optional `targetDir` form field specifies a subfolder within the VFS.

Writing to read-only database paths (`image/*` or filenames containing 8-character image hashes) is
forbidden and automatically skipped during upload.


## Body (`multipart/form-data`)

| Field | Required | Type | Description |
|-------|----------|------|-------------|
| `files` | yes | file | One or more files to upload (form field name `files`) |
| `targetDir` | no | string | Optional destination subdirectory within VFS (e.g. `reports` or `charts/q1`) |

## Signals

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

## Response `200`

Successfully uploaded files

```json
{
  "success": true,
  "uploaded": [
    {
      "name": "…",
      "size": 1,
      "mime": "…"
    }
  ]
}
```

## Errors

| Status | Description |
|--------|-------------|
| 400 | No files uploaded, invalid path, or no company selected — `{"error":"…"}` |
| 401 | Unauthorized — `{"error":"…"}` |
| 403 | Not authorized — `{"error":"…"}` |

---

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