Skip to main content
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 den Staging-Host https://v3-api.localmind.dev/v1 — ersetzen Sie ihn durch den Host Ihrer Instanz (https://<ihre-instanz>-api.localmind.ai/v1). 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 & PfadZweck
POST /v1/spaces/{space_id}/data/uploadDatei 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/renameDatei 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
file
required
Die hochzuladende Datei. Maximale Größe: 50 MB pro Datei.
​
path
string
required
Zielpfad der Datei innerhalb des Space-Storage.
curl -X POST "https://v3-api.localmind.dev/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://v3-api.localmind.dev/v1/spaces/{space_id}/data/files?prefix=vertraege/" \
  -H "Authorization: Bearer sk-…"
Umbenennen / Verschieben
curl -X PATCH "https://v3-api.localmind.dev/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://v3-api.localmind.dev/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 & PfadZweck
POST /v1/foldersOrdner 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}/contentsUnterordner und Dokumente in einem Call.
DELETE /v1/folders/{folder_id}204 — löscht den Ordner samt allen Kindern (Cascade).

​
Ordner anlegen und schachteln

​
name
string
required
Anzeigename des Ordners.
​
space_id
string
required
UUID des Space. Auch beim Verschachteln Pflicht — fehlt das Feld, antwortet die API mit 422.
​
parent_folder_id
string
UUID des übergeordneten Ordners. Weglassen, um einen Ordner auf Root-Ebene anzulegen.
curl -X POST "https://v3-api.localmind.dev/v1/folders" \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Verträge", "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
}
​
sub_folders
array
Direkte Unterordner.
​
documents
array
Dokumente direkt in diesem Ordner.
​
sub_folder_count
integer
Anzahl der direkten Unterordner.
​
document_count
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://v3-api.localmind.dev/v1/folders/{folder_id}" \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Verträge (Archiv)" }'
Cascade-Delete
curl -X DELETE "https://v3-api.localmind.dev/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. Standardmäßig 50 MB pro Datei; größere Uploads werden mit 400 abgelehnt (File size … exceeds maximum allowed (50.0MB)).
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.

​
Verwandte Seiten

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.