Base-URL und /v1-Prefix
Jede Localmind-Instanz hat einen eigenen API-Host mit dem Suffix -api. Alle Pfade tragen den Prefix /v1:
<deine-instanz> durch den Host Ihrer Instanz (beachten Sie das -api-Suffix).
Health-Check
Ob die API erreichbar ist, prüfen Sie ohne Authentifizierung über den Health-Endpunkt:Paginierung
Such-Endpunkte (POST /v1/*/search) liefern ihre Ergebnisse in einem Pagination-Envelope:
array
Die Ergebnisse der aktuellen Seite.
integer
Gesamtanzahl der Treffer über alle Seiten.
integer
Gesamtanzahl der Seiten.
integer
Aktuelle Seitennummer (1-basiert).
integer
Anzahl der Einträge pro Seite.
page und limit. Zusätzlich senden Sie filters und order_by im Request-Body:
Filter-DSL
Imfilters-Objekt verwenden Sie Schlüssel im Format feld__operator. Sortiert wird über order_by als Array von Feldnamen; ein vorangestelltes Minus kehrt die Reihenfolge um.
Filter können den Zugriff nur eingrenzen, nie erweitern. Ein Filter auf einen Space, den Ihr Key nicht erreicht, liefert 0 Treffer statt eines Fehlers — siehe Authentifizierung und Rollen.
Fehlermodell
Die API kennt zwei Fehlerformate. Allgemeine Fehler liefern eindetail als String:
422) liefern detail als Array mit Feld-Position, Meldung und Typ:
array
Pfad zum fehlerhaften Feld, z. B.
["body", "space_id"].string
Menschenlesbare Beschreibung des Fehlers.
string
Maschinenlesbarer Fehlertyp, z. B.
missing.Statuscodes
Wie Sie
422, 403 und das stille 404 in der Praxis diagnostizieren — Symptom, Ursache, Lösung — zeigt HTTP-Fehlercodes verstehen.Querschnittsthemen
Einige Eigenschaften der API betreffen mehrere Endpunkte und sind beim Aufbau einer Integration wichtig.Zwei Storage-Layer
Zwei Storage-Layer
Localmind trennt Raw Files (pfad-basierte Rohdateien im Space, per Organisation verschlüsselt) von Documents (Dateien, die die Pipeline durchlaufen haben und per Hybrid Search durchsuchbar sind). Ein Upload über
POST /v1/data/upload befüllt beide Layer: die Rohdatei und das durchsuchbare Document. Details und Endpunkte siehe Dateien und Ordner sowie Dokumente und Suche.Zwei Delete-Pfade
Zwei Delete-Pfade
Es gibt zwei Wege zu löschen, mit unterschiedlicher Wirkung:
DELETE /v1/data/{id}entfernt den Knowledge-Base-Record samt Chunks. Das Dokument verschwindet binnen Sekunden aus der Suche; die Rohdatei und die Vektoren im Storage bleiben bestehen.DELETE /v1/spaces/{space_id}/data/filesentfernt die Rohdatei physisch — samt Vektoren und abgeleitetem Record.
Asynchrone Pipeline
Asynchrone Pipeline
Upload und Reprocessing laufen asynchron. Der Status ist über das Feld
processing_state abfragbar (z. B. via GET /v1/data/{id}): Die Flags parsed, chunked und embedded werden nacheinander true, abgeschlossen ist die Verarbeitung bei pipeline_status: "completed". Pollen Sie dieses Feld, bevor Sie ein frisch hochgeladenes Dokument durchsuchen.Download über Proxy-URL
Download über Proxy-URL
Downloads laufen über eine Proxy-URL des Backends — es gibt keinen öffentlichen, vorsignierten Link. Ein Download-Aufruf ohne gültigen
Authorization-Header wird mit 403 abgelehnt (die Inhalte sind pro Organisation verschlüsselt). Mit gültigem Key erhalten Sie 200.Verwandte Seiten
Authentifizierung und Rollen
Bearer-Token, Scopes und welche Rechte ein API-Key hat.
OpenAI-kompatibel
Agenten per
GET /v1/models und POST /v1/chat/completions ansprechen.Dokumente und Suche
Upload, Pipeline-Status und Hybrid Search über eigene Dokumente.
Dateien und Ordner
Raw-File-Storage und die Resource-Ordner unter
/v1/folders.