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: 
https://<deine-instanz>-api.localmind.ai/v1
Für die Staging-/Testumgebung lautet der Host beispielsweise https://v3-api.localmind.dev/v1.
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: 
curl "https://<deine-instanz>-api.localmind.ai/health"
# -> {"status":"ok"}

​
Paginierung

Such-Endpunkte (POST /v1/*/search) liefern ihre Ergebnisse in einem Pagination-Envelope: 
{
  "items": [],
  "total_items": 142,
  "total_pages": 15,
  "page": 1,
  "page_size": 10
}
​
items
array
Die Ergebnisse der aktuellen Seite.
​
total_items
integer
Gesamtanzahl der Treffer über alle Seiten.
​
total_pages
integer
Gesamtanzahl der Seiten.
​
page
integer
Aktuelle Seitennummer (1-basiert).
​
page_size
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: 
curl -X POST "https://<deine-instanz>-api.localmind.ai/v1/data/search?page=1&limit=20" \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": { "file_type__exact": "MARKDOWN" },
    "order_by": ["-created_at"]
  }'

​
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.
BeispielBedeutung
"agent_id__exact": "<uuid>"Exakte Übereinstimmung auf agent_id
"file_type__exact": "PDF"Exakte Übereinstimmung auf file_type
"space_id__in": ["<uuid>", "<uuid>"]space_id ist in der Liste enthalten
"order_by": ["-created_at"]Absteigend nach Erstellungsdatum sortieren
{
  "filters": {
    "agent_id__exact": "<agent-uuid>",
    "space_id__in": ["<space-a>", "<space-b>"]
  },
  "order_by": ["-created_at"]
}
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: 
{ "detail": "Model 'x' not found" }

{ "detail": "Permission denied: documents:create" }
Validierungsfehler (Statuscode 422) liefern detail als Array mit Feld-Position, Meldung und Typ: 
{
  "detail": [
    {
      "loc": ["body", "space_id"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
​
loc
array
Pfad zum fehlerhaften Feld, z. B. ["body", "space_id"].
​
msg
string
Menschenlesbare Beschreibung des Fehlers.
​
type
string
Maschinenlesbarer Fehlertyp, z. B. missing.

​
Statuscodes

CodeBedeutung
200Erfolg
201Ressource erstellt
202Asynchron angenommen (Pipeline läuft)
204Erfolgreich, kein Inhalt (z. B. gelöscht)
400Bad Request — z. B. überschrittenes Größenlimit
401Auth fehlt/ungültig oder Endpunkt nicht für den Key freigeschaltet
403Keine Berechtigung, falsche Org oder Download ohne Auth
404Ressource nicht gefunden
405Method Not Allowed — häufig fehlender Trailing-Slash
422Request-Validierung fehlgeschlagen
Der 405 ist eine typische Stolperfalle: Einige Endpunkte verlangen einen abschließenden Schrägstrich. So erwartet POST /v1/conversations/ zwingend den Trailing-Slash — ohne ihn antwortet die API mit 405.

​
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.