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

# Konventionen und Fehler

> Base-URL, Pagination, Filter-DSL, das Fehlermodell und alle Statuscodes der Localmind API auf einen Blick.

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
```

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

<Warning>
  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.
</Warning>

### Health-Check

Ob die API erreichbar ist, prüfen Sie ohne Authentifizierung über den Health-Endpunkt:

```bash theme={null}
curl "https://<deine-instanz>-api.localmind.ai/health"
# -> {"status":"ok"}
```

## Paginierung

Such-Endpunkte (`POST /v1/*/search`) liefern ihre Ergebnisse in einem **Pagination-Envelope**:

```json theme={null}
{
  "items": [],
  "total_items": 142,
  "total_pages": 15,
  "page": 1,
  "page_size": 10
}
```

<ResponseField name="items" type="array">
  Die Ergebnisse der aktuellen Seite.
</ResponseField>

<ResponseField name="total_items" type="integer">
  Gesamtanzahl der Treffer über alle Seiten.
</ResponseField>

<ResponseField name="total_pages" type="integer">
  Gesamtanzahl der Seiten.
</ResponseField>

<ResponseField name="page" type="integer">
  Aktuelle Seitennummer (1-basiert).
</ResponseField>

<ResponseField name="page_size" type="integer">
  Anzahl der Einträge pro Seite.
</ResponseField>

Seite und Seitengröße steuern Sie über `page` und `limit`. Zusätzlich senden Sie `filters` und `order_by` im **Request-Body**:

```bash theme={null}
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.

| Beispiel                               | Bedeutung                                  |
| -------------------------------------- | ------------------------------------------ |
| `"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 |

```json theme={null}
{
  "filters": {
    "agent_id__exact": "<agent-uuid>",
    "space_id__in": ["<space-a>", "<space-b>"]
  },
  "order_by": ["-created_at"]
}
```

<Note>
  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](/api-reference/Authentifizierung-und-Rollen).
</Note>

## Fehlermodell

Die API kennt zwei Fehlerformate.

**Allgemeine Fehler** liefern ein `detail` als String:

```json theme={null}
{ "detail": "Model 'x' not found" }
```

```json theme={null}
{ "detail": "Permission denied: documents:create" }
```

**Validierungsfehler** (Statuscode `422`) liefern `detail` als Array mit Feld-Position, Meldung und Typ:

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "space_id"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
```

<ResponseField name="loc" type="array">
  Pfad zum fehlerhaften Feld, z. B. `["body", "space_id"]`.
</ResponseField>

<ResponseField name="msg" type="string">
  Menschenlesbare Beschreibung des Fehlers.
</ResponseField>

<ResponseField name="type" type="string">
  Maschinenlesbarer Fehlertyp, z. B. `missing`.
</ResponseField>

## Statuscodes

| Code  | Bedeutung                                                                                                                                                                                                                                                             |
| ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | Erfolg                                                                                                                                                                                                                                                                |
| `201` | Ressource erstellt                                                                                                                                                                                                                                                    |
| `202` | Asynchron angenommen (Pipeline läuft)                                                                                                                                                                                                                                 |
| `204` | Erfolgreich, kein Inhalt (z. B. gelöscht)                                                                                                                                                                                                                             |
| `400` | Bad Request — z. B. überschrittenes Größenlimit                                                                                                                                                                                                                       |
| `401` | Auth fehlt/ungültig oder Endpunkt nicht für den Key freigeschaltet                                                                                                                                                                                                    |
| `403` | Keine Berechtigung, falsche Org oder Download ohne Auth                                                                                                                                                                                                               |
| `404` | Ressource nicht gefunden — oder der API-Key hat keinen Zugriff auf die Ressource (stilles 404 bei Direkt-ID-Zugriff; Such-Endpunkte liefern stattdessen `200` mit leerem Ergebnis, siehe [Authentifizierung und Rollen](/api-reference/Authentifizierung-und-Rollen)) |
| `405` | Method Not Allowed — häufig **fehlender Trailing-Slash**                                                                                                                                                                                                              |
| `422` | Request-Validierung fehlgeschlagen                                                                                                                                                                                                                                    |

<Note>
  Wie Sie `422`, `403` und das stille `404` in der Praxis diagnostizieren — Symptom, Ursache, Lösung — zeigt [HTTP-Fehlercodes verstehen](/troubleshooting/HTTP-Fehlercodes).
</Note>

<Tip>
  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.
</Tip>

## Querschnittsthemen

Einige Eigenschaften der API betreffen mehrere Endpunkte und sind beim Aufbau einer Integration wichtig.

<AccordionGroup>
  <Accordion title="Zwei Storage-Layer" icon="layers">
    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](/api-reference/Dateien-und-Ordner) sowie [Dokumente und Suche](/api-reference/Dokumente-und-Suche).
  </Accordion>

  <Accordion title="Zwei Delete-Pfade" icon="trash">
    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.
  </Accordion>

  <Accordion title="Asynchrone Pipeline" icon="clock">
    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.
  </Accordion>

  <Accordion title="Download über Proxy-URL" icon="download">
    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`.
  </Accordion>
</AccordionGroup>

## Verwandte Seiten

<CardGroup cols={2}>
  <Card title="Authentifizierung und Rollen" icon="shield-check" href="/api-reference/Authentifizierung-und-Rollen">
    Bearer-Token, Scopes und welche Rechte ein API-Key hat.
  </Card>

  <Card title="OpenAI-kompatibel" icon="plug" href="/api-reference/OpenAI-Kompatibel">
    Agenten per `GET /v1/models` und `POST /v1/chat/completions` ansprechen.
  </Card>

  <Card title="Dokumente und Suche" icon="search" href="/api-reference/Dokumente-und-Suche">
    Upload, Pipeline-Status und Hybrid Search über eigene Dokumente.
  </Card>

  <Card title="Dateien und Ordner" icon="folder" href="/api-reference/Dateien-und-Ordner">
    Raw-File-Storage und die Resource-Ordner unter `/v1/folders`.
  </Card>
</CardGroup>