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

# API-Einführung

> Überblick über die Localmind v1-API: Agenten programmatisch nutzen, RAG über eigene Dokumente, OpenAI-SDK-Drop-in.

Die Localmind v1-API gibt Ihnen programmatischen Zugriff auf die KI-Funktionen Ihrer Localmind-Instanz. Sie sprechen Ihre konfigurierten Agenten direkt an, durchsuchen Ihre eigenen Dokumente per Hybrid Search und automatisieren Abläufe — alles über eine **OpenAI-kompatible** Schnittstelle.

## Was Sie mit der API tun können

<CardGroup cols={2}>
  <Card title="Agenten programmatisch nutzen" icon="bot">
    Senden Sie Anfragen an einen Agent und erhalten Sie dessen Antwort — Tools und Wissensquellen nutzt der Agent dabei serverseitig; die Antwort enthält das Endergebnis.
  </Card>

  <Card title="RAG über eigene Dokumente" icon="search">
    Laden Sie Dokumente in einen Space, lassen Sie die Pipeline sie verarbeiten und durchsuchen Sie sie semantisch per Hybrid Search.
  </Card>

  <Card title="OpenAI-SDK-Drop-in" icon="code">
    Stellen Sie eine bestehende OpenAI-Codebasis auf Localmind um — nur `base_url`, `api_key` und `model` ändern.
  </Card>

  <Card title="n8n und Automatisierung" icon="bolt">
    Rufen Sie die API aus n8n-Workflows oder eigenen Diensten auf, etwa für Chatbots oder geplante Verarbeitungen.
  </Card>
</CardGroup>

## Plattform-Modell

Die API spiegelt die Hierarchie der Localmind-Plattform wider:

* **Instance** — die vollständige Localmind-Installation (multi-tenant).
* **Organization (Org)** — Tenant-Einheit mit Mitgliedern, Audit-Logs, Library und Billing. Ein API-Key ist immer an **genau eine** Org gebunden.
* **Space** — Arbeits- und Berechtigungs-Container. Ein Space enthält **Agents**, **Documents**, **Files**, **Folders** und **Conversations**.

Es gibt zwei Space-Typen: Ihr **Privater Space** (jeder Nutzer ist automatisch dessen Owner und darf dort per API alles verwalten) und **Shared Spaces** (geteilt, rollenbasiert). Der Private Space ist der natürliche Ort, um per API eigene Dokumente zu verwalten.

<Note>
  Welche Spaces und Agenten ein Key sieht, bestimmt die Rolle seines Besitzers. Ein Key kann den Zugriff nur *verengen*, nie *erweitern*. Details finden Sie unter [Authentifizierung und Rollen](/api-reference/Authentifizierung-und-Rollen).
</Note>

## Zwei Storage-Layer

Hochgeladene Dateien existieren in zwei Schichten: als **Files** (pfad-basierte Rohdateien, per-Org verschlüsselt) und als **Documents** (durch die Pipeline verarbeitet — parse, chunk, embed — und damit per Hybrid Search durchsuchbar). Ein Upload über den Daten-Endpunkt befüllt beide Layer gleichzeitig. Die Details und alle Endpunkte beschreibt [Dokumente und Suche](/api-reference/Dokumente-und-Suche).

## Base-URL

Jede Localmind-Instanz hat einen eigenen **API-Host** mit `-api`-Suffix. Alle Pfade tragen den **`/v1`**-Prefix:

```
https://<deine-instanz>-api.localmind.ai/v1
```

Ersetzen Sie `<deine-instanz>` durch den Host Ihrer Instanz (beachten Sie das `-api`-Suffix).

<Warning>
  Es gibt **keinen** geteilten Host `https://api.localmind.ai`. Die API läuft ausschließlich auf der instanz-spezifischen Subdomain mit `-api`-Suffix und `/v1`-Prefix.
</Warning>

## Authentifizierung (Kurzfassung)

Authentifizieren Sie jeden Request mit einem persönlichen **User-API-Key** (`sk-…`) im `Authorization`-Header:

```bash theme={null}
curl "https://<deine-instanz>-api.localmind.ai/v1/models" \
  -H "Authorization: Bearer sk-…"
```

Den Key erstellen Sie in den **Benutzereinstellungen → API-Schlüssel** (Admins über **Einstellungen → Sicherheit → API-Schlüssel**). Beim Anlegen wählen Sie den Scope „alle Spaces" oder „ausgewählte Spaces". Das vollständige Rollen- und Zugriffsmodell beschreibt [Authentifizierung und Rollen](/api-reference/Authentifizierung-und-Rollen).

## OpenAI-Kompatibilität

Localmind bietet eine OpenAI-kompatible Oberfläche. Sie listen verfügbare Agenten mit `GET /v1/models` und chatten mit `POST /v1/chat/completions`. Wichtig: Der `model`-Parameter ist immer eine **Agent-UUID** (aus `GET /v1/models`), kein Modellname wie `gpt-4`.

```python theme={null}
from openai import OpenAI

client = OpenAI(base_url="https://<deine-instanz>-api.localmind.ai/v1", api_key="sk-…")
resp = client.chat.completions.create(
    model="{agent_id}",                       # Agent-UUID, kein Modellname
    messages=[{"role": "user", "content": "Hallo"}],
)
print(resp.choices[0].message.content)
```

Mehr dazu unter [OpenAI-kompatibel](/api-reference/OpenAI-Kompatibel).

## Nächste Schritte

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/api-reference/Quickstart">
    API-Key erstellen, Agenten auflisten und die erste Anfrage senden — in wenigen Minuten.
  </Card>

  <Card title="OpenAI-kompatibel" icon="code" href="/api-reference/OpenAI-Kompatibel">
    Die Endpunkte `/v1/models` und `/v1/chat/completions` mit allen Parametern und Responses.
  </Card>

  <Card title="Dokumente und Suche" icon="search" href="/api-reference/Dokumente-und-Suche">
    Dokumente hochladen, die Pipeline verfolgen und per Hybrid Search abfragen.
  </Card>

  <Card title="Authentifizierung und Rollen" icon="shield-check" href="/api-reference/Authentifizierung-und-Rollen">
    Wie ein API-Key Rollen erbt, an die Org gebunden ist und den Zugriff verengt.
  </Card>
</CardGroup>