Dateien und Ordner

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.

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.

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

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.

string

required

Zielpfad der Datei innerhalb des Space-Storage.

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"

{ "object_name": "spaces/{space_id}/data/vertraege/2026/vertrag.pdf" }

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

Dateien auflisten, herunterladen, umbenennen, löschen

Auflisten

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

Umbenennen / Verschieben

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" }'

Löschen

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

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.

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

string

required

Anzeigename des Ordners.

string

required

UUID des Space. Auch beim Verschachteln Pflicht — fehlt das Feld, antwortet die API mit 422.

string

UUID des übergeordneten Ordners. Weglassen, um einen Ordner auf Root-Ebene anzulegen.

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}" }'

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}" }'

{
  "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 }
}

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"].

Ordnerinhalt in einem Call abrufen

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

{
  "folder_id": "{folder_id}",
  "sub_folders": [],
  "documents": [],
  "sub_folder_count": 0,
  "document_count": 0
}

array

Direkte Unterordner.

array

Dokumente direkt in diesem Ordner.

integer

Anzahl der direkten Unterordner.

integer

Anzahl der Dokumente in diesem Ordner.

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.

Umbenennen

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)" }'

Cascade-Delete

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.

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.

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.

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.

Dokumente und Suche

Knowledge-Base, Pipeline-Status und Hybrid Search.

Authentifizierung und Rollen

Welche Rechte ein API-Key hat und wie Narrowing wirkt.

Konventionen und Fehler

Base-URL, Statuscodes und die zwei Storage-Layer im Querschnitt.

Library (Plattform)

Dokumente und Ressourcen aus der UI-Perspektive.

Übersicht

Authentifizierung & Konventionen

Endpoint-Referenz

Raw Files

Datei hochladen

Dateien auflisten, herunterladen, umbenennen, löschen

Folders (Resource-API)

Ordner anlegen und schachteln

Ordnerinhalt in einem Call abrufen

Umbenennen, verschieben, löschen

Sicherheits-Verhalten

Verwandte Seiten

Dokumente und Suche

Authentifizierung und Rollen

Konventionen und Fehler

Library (Plattform)

​Raw Files

​Datei hochladen

​Dateien auflisten, herunterladen, umbenennen, löschen

​Folders (Resource-API)

​Ordner anlegen und schachteln

​Ordnerinhalt in einem Call abrufen

​Umbenennen, verschieben, löschen

​Sicherheits-Verhalten

​Verwandte Seiten

Dokumente und Suche

Authentifizierung und Rollen

Konventionen und Fehler

Library (Plattform)

Raw Files

Datei hochladen

Dateien auflisten, herunterladen, umbenennen, löschen

Folders (Resource-API)

Ordner anlegen und schachteln

Ordnerinhalt in einem Call abrufen

Umbenennen, verschieben, löschen

Sicherheits-Verhalten

Verwandte Seiten