> ## Documentation Index > Fetch the complete documentation index at: https://docs.localmind.ai/llms.txt > Use this file to discover all available pages before exploring further. # Use Cases > Praxis-Rezepte für die v1-API: OpenAI-Drop-in, RAG, Chatbot, n8n und Dokumenten-Organisation. 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 die Base-URL `https://-api.localmind.ai/v1`. Ersetzen Sie `` durch den Host Ihrer Instanz (beachten Sie das `-api`-Suffix) 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). ```python theme={null} from openai import OpenAI client = OpenAI(base_url="https://-api.localmind.ai/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](/api-reference/OpenAI-Kompatibel). ## B) RAG über eigene Dokumente Jeder Nutzer ist Owner seines [Privaten Space](/api-reference/Authentifizierung-und-Rollen) und darf dort per Key Dokumente verwalten. Der Ablauf: Space finden, Dokument hochladen, auf die Pipeline warten, semantisch suchen. ```python theme={null} import httpx client = httpx.Client( base_url="https://-api.localmind.ai/v1", headers={"Authorization": "Bearer sk-…"}, ) # 1) Privaten Space finden spaces = client.post("/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( "/data/upload", data={"space_id": space_id}, files={"file": ("handbuch.pdf", open("handbuch.pdf", "rb"))}, ).json() # 3) Auf Fertigstellung pollen: client.get(f"/data/{doc['id']}") # bis processing_state.pipeline_status == "completed" # 4) Semantisch suchen hits = client.post( "/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](/api-reference/Dokumente-und-Suche). Als Alternative zum direkten `hybrid-search`-Aufruf können Sie einen [Agent](/api-reference/Agenten) 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. ```python theme={null} 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](/api-reference/OpenAI-Kompatibel). ## D) n8n und Automatisierung In n8n rufen Sie die API über einen **HTTP-Request-Node** auf: Methode `POST`, URL `https://-api.localmind.ai/v1/chat/completions`, Header `Authorization: Bearer sk-…`, Body als JSON. ```json theme={null} { "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](/automate/Localmind-Agent). ## E) Dokumenten-Organisation Strukturieren Sie Dokumente in Ordnern über die Folder-Resource-API. Ordner lassen sich beliebig schachteln; `space_id` ist beim Anlegen Pflicht. ```python theme={null} import httpx client = httpx.Client( base_url="https://-api.localmind.ai/v1", headers={"Authorization": "Bearer sk-…"}, ) # space_id wie in Rezept B über POST /spaces/search ermitteln # Ordner anlegen (Root) folder = client.post( "/folders", json={"name": "Verträge", "space_id": space_id}, ).json() # Unterordner anlegen — space_id ist auch beim Verschachteln Pflicht sub = client.post( "/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"/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](/api-reference/Dateien-und-Ordner). ## F) Externes System (Formular/DMS/Fachanwendung) anbinden Ein externes Formular-, DMS- oder Fachsystem ruft einen Localmind-Agenten über einen **persönlichen API-Key mit passendem Space-Scope** auf. Der Aufruf ist ein einzelner `POST /v1/chat/completions` gegen `https://-api.localmind.ai/v1` mit `Authorization: Bearer `; als `model` senden Sie die Agent-UUID aus `GET /v1/models`. Der Agent verarbeitet die übergebenen Feld- oder Dokumentinhalte (z. B. Klassifikation, Zusammenfassung, Extraktion) und liefert die Antwort **synchron** zurück — das externe System wartet auf die Response und verarbeitet sie direkt weiter. ```bash theme={null} curl -X POST "https://-api.localmind.ai/v1/chat/completions" \ -H "Authorization: Bearer sk-…" \ -H "Content-Type: application/json" \ -d '{ "model": "{agent_id}", "messages": [ { "role": "user", "content": "Klassifiziere die folgende Anfrage und begründe kurz: …" } ], "response_format": { "type": "json_object" } }' ``` Für strukturierte Rückgaben, die Ihr Fachsystem maschinell weiterverarbeitet, setzen Sie `response_format: { "type": "json_object" }` — der Agent antwortet dann mit einem JSON-Objekt statt Fließtext. `response_format` ist **modellabhängig** — nicht jedes Modell unterstützt den JSON-Mode. Prüfen Sie das Verhalten mit dem Modell, das dem Ziel-Agenten zugewiesen ist, bevor Sie sich in der Integration darauf verlassen. Scopen Sie den Key für solche Integrationen auf **ausgewählte Spaces**: Das externe System erreicht dann nur den Space des Ziel-Agenten — mehr Reichweite braucht es nicht. Verwenden Sie dafür den Key eines **org-eigenen Users**: In Multi-Org-Setups funktioniert der Key eines org-fremden Users nicht, da er nur in dessen Heimat-Org wirkt. Wie Scopes wirken, beschreibt [Authentifizierung und Rollen](/api-reference/Authentifizierung-und-Rollen). ## Weiterführend `/v1/models` und `/v1/chat/completions` mit allen Parametern. Upload, Pipeline-Status und Hybrid Search im Detail. Folder-Resource-API und Raw-File-Storage. Agenten per API auflisten und ihre Konfiguration lesen.