Dokumente und Suche - Localmind Docs

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 den Staging-Host https://v3-api.localmind.dev/v1 — ersetzen Sie ihn durch den Host Ihrer Instanz (https://<ihre-instanz>-api.localmind.ai/v1). 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. Maximale Größe: 50 MB pro Datei (größere Dateien → 400).

space_id

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://v3-api.localmind.dev/v1/data/upload" \
  -H "Authorization: Bearer sk-…" \
  -F "space_id={space_id}" \
  -F "file=@reisekostenrichtlinie.md"

{
  "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:

processing_state

object

Status der Verarbeitungs-Pipeline.

Show Felder

parsed

boolean

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

chunked

boolean

true, sobald der extrahierte Text in Chunks zerlegt wurde.

embedded

boolean

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

pipeline_status

string

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

chunk_count

integer

Anzahl der erzeugten Chunks.

embedding_model

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://v3-api.localmind.dev/v1/data/{document_id}/reprocess" \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{ "chunker_name": "page_based" }'

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 sparsamer BM25-Keyword-Suche. Das Ergebnis ist eine nach score sortierte Liste relevanter Chunks mit Quellenangabe. Dieselbe Suche nutzen Agenten intern für RAG-Retrieval.

query

string

required

Die Suchanfrage in natürlicher Sprache.

space_id

string

required

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

document_ids

array

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

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

results

array

Nach score absteigend sortierte Treffer.

Show Felder pro Treffer

chunk_id

string

UUID des Chunks.

document_id

string

UUID des Quell-Dokuments.

document_name

string

Dateiname des Quell-Dokuments.

score

number

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

dense_score

number | null

Anteil der Vektor-Suche am Score.

sparse_score

number | null

Anteil der BM25-Keyword-Suche am Score.

text

string

Der Chunk-Text — die eigentliche Beleg-Passage.

metadata

object

Chunk-Metadaten wie heading_text, format und word_count.

curl -X POST "https://v3-api.localmind.dev/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 real durchgespielt (RC1 1.0.0, role-aware QA). 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 Private 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://v3-api.localmind.dev/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://v3-api.localmind.dev/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://v3-api.localmind.dev/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://v3-api.localmind.dev/v1/data/hybrid-search" \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Hotelübernachtung Erstattung pro Nacht",
    "space_id": "{space_id}"
  }'

In der Beispiel-QA 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)

Integrationen finden alle IDs über Such-Endpunkte — es gibt keine UI für den API-Zugriff. 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.

curl -X POST "https://v3-api.localmind.dev/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.

​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