Dokumente und Suche

Localmind trennt zwei Storage-Layer: Raw Files sind pfad-basierte Rohdateien in einem Space, Documents sind Dateien, die die Verarbeitungs-Pipeline durchlaufen haben und per Hybrid Search durchsuchbar sind. Diese Seite behandelt den Documents-Layer — die Knowledge-Base, aus der RAG-Retrieval gespeist wird. Den Raw-File-Layer und die Ordner-Verwaltung beschreibt Dateien und Ordner.

Ein Upload über POST /v1/data/upload befüllt beide Layer gleichzeitig: Die Rohdatei wird gespeichert und ein durchsuchbares Document angelegt. Sie müssen nicht separat hochladen.

Alle Beispiele nutzen die Base-URL https://<deine-instanz>-api.localmind.ai/v1. Ersetzen Sie <deine-instanz> durch den Host Ihrer Instanz (beachten Sie das -api-Suffix). Jeder Request trägt den Header Authorization: Bearer sk-…. Die geltenden Konventionen zu Base-URL, Paginierung und Statuscodes beschreibt Konventionen und Fehler.

Documents verwalten

Die folgenden Endpunkte decken den Lebenszyklus eines Dokuments in der Knowledge-Base ab — vom Upload über die Inspektion bis zum Neuverarbeiten.

Methode & Pfad	Zweck
`POST /v1/data/upload`	Datei (multipart) hochladen → `201` + `processing_state`; triggert die Pipeline automatisch.
`GET /v1/data/{document_id}`	Metadaten und `processing_state` lesen. Unbekannte ID → `404`.
`PATCH /v1/data/{document_id}`	Metadaten schreiben (`doc_metadata`) — kein Reprocess.
`DELETE /v1/data/{document_id}`	`204` — entfernt den Knowledge-Base-Record samt Chunks; das Dokument verschwindet binnen Sekunden aus der Suche.
`GET /v1/data/{document_id}/text`	Extrahierte Content-Units (markdown-aware) abrufen.
`GET /v1/data/{document_id}/chunks`	Chunks samt Embedding-Metadaten abrufen.
`GET /v1/data/{document_id}/versions`	Reprocess-Historie eines Dokuments.
`POST /v1/data/{document_id}/reprocess`	`202` + `pipeline_run_id`; verarbeitet die bestehende Originaldatei neu.
`POST /v1/data/batch-reprocess`	Mehrere Dokumente in einem Aufruf neu verarbeiten.

Dokument hochladen

Senden Sie die Datei und die Ziel-space_id als multipart/form-data. Die Pipeline (parse → chunk → embed) startet automatisch im Hintergrund.

file

required

Die hochzuladende Datei. Das aktuelle Größenlimit pro Datei zeigt Ihnen das Upload-Feld in der Web-App; für Details kontaktieren Sie den Support. Dateien über dem Limit lehnt die API mit 400 ab.

string

required

UUID des Ziel-Space. Sie benötigen Schreibrechte in diesem Space — andernfalls antwortet die API mit 403. Fehlt das Feld, ist die Antwort 422.

curl -X POST "https://<deine-instanz>-api.localmind.ai/v1/data/upload" \
  -H "Authorization: Bearer sk-…" \
  -F "space_id={space_id}" \
  -F "file=@reisekostenrichtlinie.md"

import requests

resp = requests.post(
    "https://<deine-instanz>-api.localmind.ai/v1/data/upload",
    headers={"Authorization": "Bearer sk-…"},
    data={"space_id": "{space_id}"},
    files={"file": ("reisekostenrichtlinie.md", open("reisekostenrichtlinie.md", "rb"))},
)
document = resp.json()
print(document["id"], document["processing_state"])

{
  "id": "{document_id}",
  "file_type": "MARKDOWN",
  "file_size": 412,
  "file_path": "spaces/{space_id}/documents/{document_id}/original/reisekostenrichtlinie.md",
  "doc_metadata": {
    "original_filename": "reisekostenrichtlinie.md",
    "content_type": "text/markdown"
  },
  "processing_state": { "parsed": false, "chunked": false, "embedded": false },
  "space_id": "{space_id}",
  "organization_id": "{org_id}",
  "created_by": "{user_id}"
}

Direkt nach dem Upload stehen alle drei processing_state-Flags auf false — die Pipeline läuft noch. Wie Sie auf den Abschluss warten, zeigt der nächste Abschnitt.

Auf den Pipeline-Abschluss warten

Der Upload ist asynchron. Fragen Sie GET /v1/data/{document_id} ab, bis die Verarbeitung abgeschlossen ist. Maßgeblich ist das Feld processing_state:

object

Status der Verarbeitungs-Pipeline.

Show Felder

boolean

true, sobald die Datei geparst (Text extrahiert) wurde.

boolean

true, sobald der extrahierte Text in Chunks zerlegt wurde.

boolean

true, sobald die Chunks eingebettet (Embeddings berechnet) wurden.

string

Gesamtstatus. Bei Abschluss "completed" — dann ist das Dokument durchsuchbar.

integer

Anzahl der erzeugten Chunks.

string

Verwendetes Embedding-Modell, z. B. localmind-embeddings.

{
  "processing_state": {
    "parsed": true,
    "chunked": true,
    "embedded": true,
    "parser_name": "markdown",
    "chunker_name": "page_based",
    "chunk_count": 1,
    "embedding_model": "localmind-embeddings",
    "embedded_chunk_count": 1,
    "pipeline_status": "completed"
  }
}

Pollen Sie processing_state.pipeline_status so lange, bis es "completed" ist, bevor Sie ein frisch hochgeladenes Dokument durchsuchen. Vorher liefert die Suche es nicht zurück.

Dokumente neu verarbeiten

Wenn sich die Parser- oder Chunker-Konfiguration geändert hat, verarbeiten Sie ein bestehendes Dokument neu. Die Originaldatei bleibt dabei erhalten. POST /v1/data/{document_id}/reprocess antwortet mit 202 und einer pipeline_run_id, über die Sie den neuen Lauf verfolgen können. Für mehrere Dokumente nutzen Sie POST /v1/data/batch-reprocess mit einem Objekt, das die IDs unter dem Schlüssel document_ids enthält:

curl -X POST "https://<deine-instanz>-api.localmind.ai/v1/data/{document_id}/reprocess" \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{ "chunker_name": "page_based" }'

curl -X POST "https://<deine-instanz>-api.localmind.ai/v1/data/batch-reprocess" \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{ "document_ids": ["{document_id}", "{document_id}"] }'

Der Body von batch-reprocess ist ein Objekt mit dem Schlüssel document_ids — kein rohes Array. Eine ungültige ID bricht den Batch nicht ab; die Antwort listet pro Dokument den Erfolg unter results[].

Semantische Suche

POST /v1/data/hybrid-search durchsucht die Documents eines Space mit Hybrid Search — einer Kombination aus dichter Vektor-Suche und lexikalischer BM25-Keyword-Suche (sparse). Das Ergebnis ist eine nach score sortierte Liste relevanter Chunks mit Quellenangabe. Dieselbe Suche nutzen Agenten intern für RAG-Retrieval.

string

required

Die Suchanfrage in natürlicher Sprache.

string

required

UUID des zu durchsuchenden Space. Die Suche ist space-scoped.

array

Optionale Liste von Document-UUIDs, auf die der Suchraum eingegrenzt wird.

Die Antwort enthält das Feld results mit den Treffern:

array

Nach score absteigend sortierte Treffer.

Show Felder pro Treffer

string

UUID des Chunks.

string

UUID des Quell-Dokuments.

string

Dateiname des Quell-Dokuments.

number

Kombinierter Relevanz-Score (Hybrid). Höher = relevanter.

number | null

Anteil der Vektor-Suche am Score.

number | null

Anteil der BM25-Keyword-Suche am Score.

string

Der Chunk-Text — die eigentliche Beleg-Passage.

object

Chunk-Metadaten wie heading_text, format und word_count.

curl -X POST "https://<deine-instanz>-api.localmind.ai/v1/data/hybrid-search" \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Hotelübernachtung Erstattung pro Nacht",
    "space_id": "{space_id}"
  }'

{
  "query": "Hotelübernachtung Erstattung pro Nacht",
  "space_id": "{space_id}",
  "total_results": 10,
  "results": [
    {
      "chunk_id": "{chunk_id}",
      "document_id": "{document_id}",
      "document_name": "reisekostenrichtlinie.md",
      "file_type": "MARKDOWN",
      "folder_path": null,
      "chunk_index": 0,
      "score": 0.913,
      "dense_score": null,
      "sparse_score": null,
      "text": "## Übernachtung\nHotelübernachtungen werden bis 120 EUR pro Nacht erstattet. …",
      "metadata": { "heading_text": "Übernachtung", "format": "markdown", "word_count": 11 }
    }
  ]
}

Ein in document_ids oder über Folder-Pfade gesetzter Filter wird mit der für Ihren Key erreichbaren Menge geschnitten, nie erweitert. Ein Filter auf ein Dokument außerhalb Ihres Zugriffs liefert keine Treffer statt eines Fehlers — siehe Authentifizierung und Rollen.

End-to-End: eigenes Dokument hochladen und abfragen

Das folgende Beispiel ist end-to-end verifiziert. Es zeigt den vollständigen RAG-Ablauf: vom Auffinden des eigenen Private Space über den Upload bis zur semantischen Suche.

Private Space finden

Jeder Nutzer ist Owner seines Privaten Space und darf dort per Key hochladen. Listen Sie Ihre Spaces auf und wählen Sie den Eintrag mit "is_private": true.

curl -X POST "https://<deine-instanz>-api.localmind.ai/v1/spaces/search" \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{}'

Antwort (gekürzt)

{
  "items": [
    { "name": "Private Space", "id": "{space_id}", "is_private": true, "owner_id": "{user_id}" }
  ],
  "total_items": 2, "total_pages": 1, "page": 1, "page_size": 10
}

Sie haben die id des Private Space — das ist Ihr {space_id} für die nächsten Schritte.

Dokument hochladen

Laden Sie die Datei per multipart hoch. Die Antwort ist 201; die Pipeline läuft asynchron an.

curl -X POST "https://<deine-instanz>-api.localmind.ai/v1/data/upload" \
  -H "Authorization: Bearer sk-…" \
  -F "space_id={space_id}" \
  -F "file=@reisekostenrichtlinie.md"

Notieren Sie die id aus der Antwort — das ist Ihr {document_id}. Alle processing_state-Flags stehen zunächst auf false.

Auf den Abschluss pollen

Fragen Sie das Dokument ab, bis pipeline_status den Wert "completed" hat.

curl "https://<deine-instanz>-api.localmind.ai/v1/data/{document_id}" \
  -H "Authorization: Bearer sk-…"

processing_state.parsed, chunked und embedded sind alle true, pipeline_status ist "completed" — das Dokument ist durchsuchbar.

Semantisch abfragen

Stellen Sie die Suchanfrage an hybrid-search. Der passende Chunk steht mit dem höchsten score oben.

curl -X POST "https://<deine-instanz>-api.localmind.ai/v1/data/hybrid-search" \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Hotelübernachtung Erstattung pro Nacht",
    "space_id": "{space_id}"
  }'

Im verifizierten Beispiel lieferte diese präzise Frage den Ziel-Chunk auf Platz 1 mit score 0.91.

Retrieval scopen: In einem Space mit vielen oder großen Dokumenten kann ein großes Dokument die Top-Treffer dominieren. Beobachtet: Dieselbe Frage präzise gestellt → Ziel-Chunk auf Platz 1; umgangssprachlich gestellt → nur auf Platz 4. Verwenden Sie präzise Begriffe und/oder grenzen Sie den Suchraum per document_ids ein:

{ "query": "Hotel Erstattung", "space_id": "{space_id}", "document_ids": ["{document_id}"] }

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. Der direkte hybrid-search-Aufruf oben ist der explizit verifizierte Weg.

IDs finden (Discovery)

IDs ermitteln Sie ausschließlich über diese Such-Endpunkte — die Web-App zeigt sie nicht an. Alle drei Endpunkte sind paginiert und auto-narrowing: Sie liefern nur, was Ihr Key erreicht.

Methode & Pfad	Zweck
`POST /v1/spaces/search`	Spaces auflisten (Body `{}` für alle erreichbaren). `is_private` markiert den Private Space.
`POST /v1/data/search`	Documents eines Space auflisten — mit `filters` und `order_by` im Body, `page`/`limit` als Query.
`POST /v1/agents/search`	Agenten samt vollständiger Konfiguration auflisten — siehe Agenten.

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": { "space_id__exact": "{space_id}", "file_type__exact": "PDF" },
    "order_by": ["-created_at"]
  }'

Die Antwort ist ein Pagination-Envelope (items, total_items, total_pages, page, page_size); jedes Element enthält die Document-Metadaten samt processing_state. Das Envelope-Format und die Filter-DSL beschreibt Konventionen und Fehler.

Dateien und Ordner

Der Raw-File-Layer und die Resource-Ordner unter /v1/folders.

Use Cases

RAG, Chatbot und n8n als fertige Rezepte.

Konventionen und Fehler

Base-URL, Paginierung, Filter-DSL und Statuscodes.

Dokumente (Plattform)

Dieselbe Knowledge-Base aus der UI-Perspektive.

Dateien und OrdnerRaw-File-Storage eines Space verwalten und Dokumente über die Folder-Resource-API strukturieren und schachteln.

curl -X POST "https://<deine-instanz>-api.localmind.ai/v1/data/upload" \
  -H "Authorization: Bearer sk-…" \
  -F "space_id={space_id}" \
  -F "file=@reisekostenrichtlinie.md"

import requests

resp = requests.post(
    "https://<deine-instanz>-api.localmind.ai/v1/data/upload",
    headers={"Authorization": "Bearer sk-…"},
    data={"space_id": "{space_id}"},
    files={"file": ("reisekostenrichtlinie.md", open("reisekostenrichtlinie.md", "rb"))},
)
document = resp.json()
print(document["id"], document["processing_state"])

{
  "id": "{document_id}",
  "file_type": "MARKDOWN",
  "file_size": 412,
  "file_path": "spaces/{space_id}/documents/{document_id}/original/reisekostenrichtlinie.md",
  "doc_metadata": {
    "original_filename": "reisekostenrichtlinie.md",
    "content_type": "text/markdown"
  },
  "processing_state": { "parsed": false, "chunked": false, "embedded": false },
  "space_id": "{space_id}",
  "organization_id": "{org_id}",
  "created_by": "{user_id}"
}

Übersicht

Authentifizierung & Konventionen

Endpoint-Referenz

Documents verwalten

Dokument hochladen

Auf den Pipeline-Abschluss warten

Dokumente neu verarbeiten

Semantische Suche

End-to-End: eigenes Dokument hochladen und abfragen

IDs finden (Discovery)

Verwandte Seiten

Dateien und Ordner

Use Cases

Konventionen und Fehler

Dokumente (Plattform)

​Documents verwalten

​Dokument hochladen

​Auf den Pipeline-Abschluss warten

​Dokumente neu verarbeiten

​Semantische Suche

​End-to-End: eigenes Dokument hochladen und abfragen

​IDs finden (Discovery)

​Verwandte Seiten

Dateien und Ordner

Use Cases

Konventionen und Fehler

Dokumente (Plattform)

Documents verwalten

Dokument hochladen

Auf den Pipeline-Abschluss warten

Dokumente neu verarbeiten

Semantische Suche

End-to-End: eigenes Dokument hochladen und abfragen

IDs finden (Discovery)

Verwandte Seiten