> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localmind.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Dateien und Ordner

> Raw-File-Storage eines Space verwalten und Dokumente über die Folder-Resource-API strukturieren und schachteln.

Diese Seite behandelt den **Raw-File-Layer** eines Space — pfad-basierte, pro Organisation verschlüsselte Rohdateien — sowie die **Folder-Resource-API** zum Strukturieren von Dokumenten. Den durchsuchbaren Documents-Layer (Knowledge-Base, Hybrid Search) beschreibt [Dokumente und Suche](/api-reference/Dokumente-und-Suche).

<Note>
  Localmind hat zwei Storage-Layer. Ein Upload über den File-Endpunkt `POST /v1/spaces/{space_id}/data/upload` legt **beides** an: die Rohdatei **und** ein durchsuchbares Document. Die beiden Delete-Pfade unterscheiden sich jedoch in der Wirkung — siehe [Konventionen und Fehler](/api-reference/Konventionen-und-Fehler#querschnittsthemen).
</Note>

Alle Beispiele nutzen die Base-URL `https://<deine-instanz>-api.localmind.ai/v1`. Ersetzen Sie `<deine-instanz>` durch den Host Ihrer Instanz (beachten Sie das `-api`-Suffix). Jeder Request trägt den Header `Authorization: Bearer sk-…`.

## Raw Files

Die Raw-File-Endpunkte liegen unter `/v1/spaces/{space_id}/data/*` und arbeiten **pfad-basiert**: Sie adressieren Dateien über ihren Pfad innerhalb des Space-Storage.

| Methode & Pfad                                  | Zweck                                                                                 |
| ----------------------------------------------- | ------------------------------------------------------------------------------------- |
| `POST /v1/spaces/{space_id}/data/upload`        | Datei hochladen (`file` + `path`) → `201`; wird **auch** ein durchsuchbares Document. |
| `GET /v1/spaces/{space_id}/data/files?prefix=`  | Dateien auflisten, optional nach Pfad-Präfix gefiltert.                               |
| `GET /v1/spaces/{space_id}/data/download?path=` | Download über eine Proxy-URL — braucht den Key (kein öffentlicher Link).              |
| `PATCH /v1/spaces/{space_id}/data/rename`       | Datei umbenennen oder verschieben (`old_path` → `new_path`) → `204`.                  |
| `DELETE /v1/spaces/{space_id}/data/files?path=` | Rohdatei physisch löschen → `204`; entfernt auch Vektoren und abgeleiteten Record.    |

### Datei hochladen

<ParamField body="file" type="file" required>
  Die hochzuladende Datei. Das aktuelle Größenlimit pro Datei zeigt Ihnen das Upload-Feld in der Web-App; für Details kontaktieren Sie den Support.
</ParamField>

<ParamField body="path" type="string" required>
  Zielpfad der Datei innerhalb des Space-Storage.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://<deine-instanz>-api.localmind.ai/v1/spaces/{space_id}/data/upload" \
    -H "Authorization: Bearer sk-…" \
    -F "path=vertraege/2026/" \
    -F "file=@vertrag.pdf"
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  { "object_name": "spaces/{space_id}/data/vertraege/2026/vertrag.pdf" }
  ```
</ResponseExample>

Da der Upload auch ein Document anlegt, läuft anschließend die Verarbeitungs-Pipeline. Wie Sie ihren Status verfolgen, beschreibt [Dokumente und Suche](/api-reference/Dokumente-und-Suche).

### Dateien auflisten, herunterladen, umbenennen, löschen

```bash Auflisten theme={null}
curl "https://<deine-instanz>-api.localmind.ai/v1/spaces/{space_id}/data/files?prefix=vertraege/" \
  -H "Authorization: Bearer sk-…"
```

```bash Umbenennen / Verschieben theme={null}
curl -X PATCH "https://<deine-instanz>-api.localmind.ai/v1/spaces/{space_id}/data/rename" \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{ "old_path": "vertraege/2026/vertrag.pdf", "new_path": "archiv/vertrag.pdf" }'
```

```bash Löschen theme={null}
curl -X DELETE "https://<deine-instanz>-api.localmind.ai/v1/spaces/{space_id}/data/files?path=archiv/vertrag.pdf" \
  -H "Authorization: Bearer sk-…"
```

<Warning>
  Der Download läuft über eine **Proxy-URL** des Backends, nicht über einen öffentlichen vorsignierten Link. Ein Download-Aufruf **ohne** gültigen `Authorization`-Header wird mit `403` abgelehnt, da die Inhalte pro Organisation verschlüsselt sind. Senden Sie den Key auch beim Download mit.
</Warning>

## Folders (Resource-API)

Ordner verwalten Sie über die **Resource-API** unter `/v1/folders`. Diese Ordner sind eigenständige Ressourcen mit eigener UUID und lassen sich beliebig schachteln — abzugrenzen von den pfad-basierten Datei-Ordnern (siehe Sicherheits-Hinweis unten).

| Methode & Pfad                         | Zweck                                                                                      |
| -------------------------------------- | ------------------------------------------------------------------------------------------ |
| `POST /v1/folders`                     | Ordner anlegen. Root: `{"name","space_id"}`; verschachtelt: zusätzlich `parent_folder_id`. |
| `GET /v1/folders/space/{space_id}`     | Alle Ordner eines Space auflisten (optional `?parent_folder_id=` für Kinder).              |
| `GET /v1/folders/{folder_id}`          | Einzelnen Ordner abrufen.                                                                  |
| `PATCH /v1/folders/{folder_id}`        | Umbenennen (`{"name"}`) oder verschieben (`{"parent_folder_id"}`).                         |
| `GET /v1/folders/{folder_id}/contents` | Unterordner **und** Dokumente in einem Call.                                               |
| `DELETE /v1/folders/{folder_id}`       | `204` — löscht den Ordner samt allen Kindern (Cascade).                                    |

### Ordner anlegen und schachteln

<ParamField body="name" type="string" required>
  Anzeigename des Ordners.
</ParamField>

<ParamField body="space_id" type="string" required>
  UUID des Space. **Auch beim Verschachteln Pflicht** — fehlt das Feld, antwortet die API mit `422`.
</ParamField>

<ParamField body="parent_folder_id" type="string">
  UUID des übergeordneten Ordners. Weglassen, um einen Ordner auf Root-Ebene anzulegen.
</ParamField>

<RequestExample>
  ```bash Root-Ordner theme={null}
  curl -X POST "https://<deine-instanz>-api.localmind.ai/v1/folders" \
    -H "Authorization: Bearer sk-…" \
    -H "Content-Type: application/json" \
    -d '{ "name": "Verträge", "space_id": "{space_id}" }'
  ```

  ```bash Unterordner theme={null}
  curl -X POST "https://<deine-instanz>-api.localmind.ai/v1/folders" \
    -H "Authorization: Bearer sk-…" \
    -H "Content-Type: application/json" \
    -d '{ "name": "2026", "parent_folder_id": "{folder_id}", "space_id": "{space_id}" }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "{folder_id}",
    "name": "Verträge",
    "parent_folder_id": null,
    "org_id": "{org_id}",
    "home_space_id": "{space_id}",
    "from_system": false,
    "created_by": { "id": "{user_id}", "name": "Beispiel Nutzer", "avatar_url": null }
  }
  ```
</ResponseExample>

<Warning>
  `space_id` ist beim Anlegen **immer** Pflicht — auch dann, wenn Sie über `parent_folder_id` verschachteln. Fehlt es, liefert die API `422` mit `loc: ["body", "space_id"]`.
</Warning>

### Ordnerinhalt in einem Call abrufen

`GET /v1/folders/{folder_id}/contents` liefert Unterordner und Dokumente gemeinsam — Sie sparen sich zwei separate Aufrufe.

<ResponseExample>
  ```json 200 theme={null}
  {
    "folder_id": "{folder_id}",
    "sub_folders": [],
    "documents": [],
    "sub_folder_count": 0,
    "document_count": 0
  }
  ```
</ResponseExample>

<ResponseField name="sub_folders" type="array">
  Direkte Unterordner.
</ResponseField>

<ResponseField name="documents" type="array">
  Dokumente direkt in diesem Ordner.
</ResponseField>

<ResponseField name="sub_folder_count" type="integer">
  Anzahl der direkten Unterordner.
</ResponseField>

<ResponseField name="document_count" type="integer">
  Anzahl der Dokumente in diesem Ordner.
</ResponseField>

### Umbenennen, verschieben, löschen

`PATCH /v1/folders/{folder_id}` benennt um oder hängt den Ordner unter einen anderen Eltern-Ordner (`parent_folder_id`). `DELETE /v1/folders/{folder_id}` löscht den Ordner **kaskadierend** — alle enthaltenen Unterordner und ihre Verweise verschwinden mit; ein anschließender Zugriff auf ein Kind liefert `404`.

```bash Umbenennen theme={null}
curl -X PATCH "https://<deine-instanz>-api.localmind.ai/v1/folders/{folder_id}" \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Verträge (Archiv)" }'
```

```bash Cascade-Delete theme={null}
curl -X DELETE "https://<deine-instanz>-api.localmind.ai/v1/folders/{folder_id}" \
  -H "Authorization: Bearer sk-…"
```

## Sicherheits-Verhalten

Das Zugriffsmodell ist role-aware und fail-closed verifiziert. Ein API-Key erbt die Rolle seines Besitzers 1:1 und kann den Zugriff nur **verengen**, nie erweitern — Details unter [Authentifizierung und Rollen](/api-reference/Authentifizierung-und-Rollen).

<Warning>
  **Schreiben braucht Schreibrechte.** Ein Viewer-Key darf lesen und suchen, aber nicht schreiben: Folder- oder Document-Anlegen, Upload und Löschen werden mit `403` abgelehnt (`Permission denied: write on folders` bzw. `documents:create`). Schreiben gelingt nur in Spaces, in denen der Besitzer Schreibrechte hat — etwa im eigenen Private Space.
</Warning>

<Note>
  Weitere verifizierte Eigenschaften des Zugriffsmodells:

  * **Download ohne Auth → `403`.** Inhalte sind pro Organisation verschlüsselt; es gibt keinen öffentlichen Link.
  * **Narrowing ist wasserdicht.** Ein Filter auf einen fremden oder unerreichbaren Space liefert `200` mit 0 Treffern (kein Leak); fremde Spaces tauchen in `spaces/search` gar nicht erst auf.
  * **Fail-closed.** Eine ungültige (Nicht-UUID-)ID führt zu `422` aus der Pfad-Validierung — nie zu `500` und nie zu einem Datenleck.
  * **Dateigrößen-Limit.** Zu große Uploads werden mit `400` abgelehnt (`File size … exceeds maximum allowed`). Das aktuelle Limit pro Datei zeigt Ihnen das Upload-Feld in der Web-App; für Details kontaktieren Sie den Support.
</Note>

<Warning>
  **Für Integrationen `/v1/folders` verwenden — nicht die Path-Folders.** Die pfad-basierten Ordner-Endpunkte `POST /v1/spaces/{space_id}/data/folders` sind **JWT-only**: Ein API-Key wird dort mit `401` abgelehnt (`GET` darauf liefert `405`). Die hier dokumentierte Resource-API `/v1/folders` ist der key-fähige Weg für programmatische Ordner-Verwaltung.
</Warning>

## Verwandte Seiten

<CardGroup cols={2}>
  <Card title="Dokumente und Suche" icon="search" href="/api-reference/Dokumente-und-Suche">
    Knowledge-Base, Pipeline-Status und Hybrid Search.
  </Card>

  <Card title="Authentifizierung und Rollen" icon="shield-check" href="/api-reference/Authentifizierung-und-Rollen">
    Welche Rechte ein API-Key hat und wie Narrowing wirkt.
  </Card>

  <Card title="Konventionen und Fehler" icon="list-checks" href="/api-reference/Konventionen-und-Fehler">
    Base-URL, Statuscodes und die zwei Storage-Layer im Querschnitt.
  </Card>

  <Card title="Library (Plattform)" icon="library-big" href="/library/overview">
    Dokumente und Ressourcen aus der UI-Perspektive.
  </Card>
</CardGroup>