Skip to main content
Diese Seite fasst die Konventionen zusammen, die für alle Endpunkte der Localmind API gelten: wie Sie die richtige Base-URL bilden, wie Paginierung und Filter funktionieren, wie Fehler aussehen und was die einzelnen Statuscodes bedeuten.

Base-URL und /v1-Prefix

Jede Localmind-Instanz hat einen eigenen API-Host mit dem Suffix -api. Alle Pfade tragen den Prefix /v1:
Ersetzen Sie <deine-instanz> durch den Host Ihrer Instanz (beachten Sie das -api-Suffix).
Verwenden Sie nicht den -app-Host — der bedient nur das Frontend. Und es gibt keinen geteilten Host https://api.localmind.ai/…: Die API ist immer instanz-spezifisch unter der -api-Subdomain mit /v1-Prefix erreichbar.

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.
Seite und Seitengröße steuern Sie über page und limit. Zusätzlich senden Sie filters und order_by im Request-Body:

Filter-DSL

Im filters-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 ein detail als String:
Validierungsfehler (Statuscode 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.
Der 405 ist eine typische Stolperfalle: Einige Erstellungs-Endpunkte verlangen den abschließenden Schrägstrich — achten Sie auf die exakte Pfadangabe in der jeweiligen Referenz.

Querschnittsthemen

Einige Eigenschaften der API betreffen mehrere Endpunkte und sind beim Aufbau einer Integration wichtig.
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.
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/files entfernt die Rohdatei physisch — samt Vektoren und abgeleitetem Record.
Aus Sicht der Suche verhalten sich beide gleich (das Dokument ist weg). Welcher Pfad der richtige ist, hängt davon ab, ob Sie die Rohdatei behalten wollen.
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.
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.