Skip to main content
Diese Rezepte zeigen, wie die Localmind v1-API real eingesetzt wird. Jedes Beispiel ist eigenständig und verweist auf die passende Referenz-Page. 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) und authentifizieren Sie jeden Request mit Authorization: Bearer sk-….

​
A) OpenAI-Drop-in

Stellen Sie eine bestehende OpenAI-Codebasis auf Localmind um, ohne die Logik zu ändern: Sie setzen nur base_url, api_key und model (= Agent-UUID). 
from openai import OpenAI

client = OpenAI(base_url="https://v3-api.localmind.dev/v1", api_key="sk-…")
resp = client.chat.completions.create(
    model="{agent_id}",                       # Agent-UUID aus GET /v1/models
    messages=[{"role": "user", "content": "Fasse den Quartalsbericht zusammen."}],
)
print(resp.choices[0].message.content)
Die verfügbaren Agent-UUIDs finden Sie über GET /v1/models. Alle Parameter und das Streaming-Format beschreibt OpenAI-kompatibel.

​
B) RAG über eigene Dokumente

Jeder Nutzer ist Owner seines Private Space und darf dort per Key Dokumente verwalten. Der Ablauf: Space finden, Dokument hochladen, auf die Pipeline warten, semantisch suchen. 
# 1) Private Space finden
spaces = client.post("/v1/spaces/search", json={}).json()["items"]
space_id = next(s["id"] for s in spaces if s["is_private"])

# 2) Dokument hochladen — die Pipeline läuft automatisch an (parse → chunk → embed)
doc = client.post(
    "/v1/data/upload",
    data={"space_id": space_id},
    files={"file": ("handbuch.pdf", open("handbuch.pdf", "rb"))},
).json()

# 3) Auf Fertigstellung pollen: GET /v1/data/{id} bis pipeline_status == "completed"
# 4) Semantisch suchen
hits = client.post(
    "/v1/data/hybrid-search",
    json={"query": "Wie kündige ich?", "space_id": space_id},
).json()["results"]

for hit in hits:
    print(hit["score"], hit["document_name"], hit["text"][:80])
Die hybrid-search-Treffer kommen mit score-Werten sortiert zurück. Den vollständigen Upload-, Polling- und Such-Ablauf — inklusive Response-Feldern und dem Eingrenzen des Suchraums per document_ids — beschreibt Dokumente und Suche.
Als Alternative zum direkten hybrid-search-Aufruf können Sie einen Agent mit Daten-Tool ansprechen — dann genügt POST /v1/chat/completions, und der Agent zieht die Belege selbst aus seinem Space.

​
C) Chatbot und WhatsApp

Für Chatbots (z. B. eine WhatsApp-Anbindung) nutzen Sie den statelessen Weg über POST /v1/chat/completions. Localmind persistiert hier keinen Verlauf — den Gesprächsverlauf hält Ihr Client und sendet ihn bei jeder Anfrage vollständig im messages-Array mit. 
def antwort(verlauf: list[dict], frage: str) -> str:
    verlauf.append({"role": "user", "content": frage})
    resp = client.chat.completions.create(model="{agent_id}", messages=verlauf)
    antwort_text = resp.choices[0].message.content
    verlauf.append({"role": "assistant", "content": antwort_text})  # Verlauf wächst im Client
    return antwort_text

# Pro Nutzer einen eigenen Verlauf halten (z. B. in Ihrem Backend / Cache)
verlauf: list[dict] = []
print(antwort(verlauf, "Welche Öffnungszeiten hat das Bürgeramt?"))
print(antwort(verlauf, "Und am Samstag?"))   # Kontext kommt aus dem mitgesendeten Verlauf
In einer WhatsApp-Integration verbinden Sie das eingehende Nachrichten-Webhook mit diesem Aufruf — typischerweise über einen n8n-Workflow (siehe nächstes Rezept). Speichern Sie das messages-Array pro Nutzer in Ihrem eigenen Speicher. Mehr zum Request-Aufbau unter OpenAI-kompatibel.

​
D) n8n und Automatisierung

In n8n rufen Sie die API über einen HTTP-Request-Node auf: Methode POST, URL https://<ihre-instanz>-api.localmind.ai/v1/chat/completions, Header Authorization: Bearer sk-…, Body als JSON. 
{
  "model": "{agent_id}",
  "messages": [
    { "role": "user", "content": "={{ $json.text }}" }
  ]
}
Da chat/completions stateless ist, hält der Workflow den Gesprächskontext selbst — etwa indem er das messages-Array zwischen den Node-Ausführungen mitführt. So bauen Sie Chatbots, geplante Verarbeitungen oder Event-getriggerte Abläufe. Die Plattform-Sicht auf die n8n-Anbindung beschreibt Localmind-Agent in Automate.

​
E) Dokumenten-Organisation

Strukturieren Sie Dokumente in Ordnern über die Folder-Resource-API. Ordner lassen sich beliebig schachteln; space_id ist beim Anlegen Pflicht. 
# Ordner anlegen (Root)
folder = client.post(
    "/v1/folders",
    json={"name": "Verträge", "space_id": space_id},
).json()

# Unterordner anlegen — space_id ist auch beim Verschachteln Pflicht
sub = client.post(
    "/v1/folders",
    json={"name": "2026", "parent_folder_id": folder["id"], "space_id": space_id},
).json()

# Inhalte eines Ordners in einem Call browsen
contents = client.get(f"/v1/folders/{folder['id']}/contents").json()
print(contents["sub_folder_count"], contents["document_count"])
Alle Folder-Endpunkte (Anlegen, Schachteln, Umbenennen, Verschieben, Cascade-Delete) und die Abgrenzung zu pfad-basierten Datei-Ordnern beschreibt Dateien und Ordner.

​
Weiterführend

OpenAI-kompatibel

/v1/models und /v1/chat/completions mit allen Parametern.

Dokumente und Suche

Upload, Pipeline-Status und Hybrid Search im Detail.

Dateien und Ordner

Folder-Resource-API und Raw-File-Storage.

Agenten

Agenten per API auflisten und ihre Konfiguration lesen.