Referenz der Suchanfrage | Tuix RAG Service

Eine Suchanfrage ist ein POST mit JSON-Body, sowohl mit dem npm-Client als auch mit fetch. Die resourceGroupId ist Teil der URL.

POST {API_BASE_URL}/api/resource-groups/{resourceGroupId}/search

Request

Feld	Typ	Pflicht	Beschreibung
`resourceGroupId`	string	Ja	ID der zu durchsuchenden Knowledge Group (Teil des Pfads).
`query`	string	Ja	Der Text, nach dem gesucht wird.
`limit`	number	Nein	Maximale Anzahl zurückgegebener Chunks, von `1` bis `20`. Standard `3`.
`role`	string	Nein	Findet nur Resources mit dieser Role oder ganz ohne Role, siehe Role Filter.

{
    "query": "What is your return policy?",
    "limit": 5,
    "role": "customer"
}

query ist das einzige Pflichtfeld. Lässt du limit weg, erhältst du standardmässig 3 Ergebnisse, und lässt du role weg, wird über alle Resources gesucht, unabhängig davon, wie sie markiert sind.

Response

200 OK mit den passenden Chunks:

Feld	Typ	Beschreibung
`query`	string	Die gesendete `query`, zurückgespiegelt.
`count`	number	Anzahl der Chunks in `results`.
`results`	array	Die passenden Chunks, sortiert nach `score`, höchster zuerst.
`results[].id`	string	ID des Chunks.
`results[].resource_id`	string	ID der Resource, aus der der Chunk stammt.
`results[].content`	string	Der Text des Chunks.
`results[].added_at`	string	Wann der Chunk erstellt wurde, ISO 8601.
`results[].score`	number	Relevanz dieses Chunks für die Anfrage, siehe Suche und Ranking.
`notes`	array	Erklärungen zur Suche selbst, siehe Notes weiter unten. Kann leer sein.

{
    "query": "What is your return policy?",
    "count": 2,
    "notes": [],
    "results": [
        {
            "id": "3b7f1c9e-2d4a-4b8c-9e1f-0a2b3c4d5e6f",
            "resource_id": "f2c1a0d4-7c2e-4e1a-9a9b-3d5f6c7b8a90",
            "content": "Items can be returned within 30 days of delivery…",
            "added_at": "2026-01-14T09:32:00Z",
            "score": 0.8123
        }
    ]
}

Jeder Eintrag ist ein Chunk, keine ganze Resource, siehe Chunks verstehen. Eine Resource kann mehrfach in results auftauchen, wenn mehrere ihrer Chunks passen.

Notes

notes erklärt etwas über die Suche selbst, statt über einen einzelnen Chunk, siehe Ergebnisse verstehen dazu, wie du es nutzen kannst. Jeder Eintrag hat einen reason-Code und eine verständliche message:

{
    "reason": "LOW_RELEVANCE",
    "message": "No relevant results. Some content matched your query, but none is relevant to the question; try a more specific query."
}

`reason`	Bedeutung
`EMPTY_SCOPE`	Die Knowledge Group, oder die Role, nach der gefiltert wurde, hat keinerlei Inhalt.
`PHRASE_NOT_FOUND`	Eine zitierte Phrase in `query` kommt in keiner Resource vor.
`NO_LEXICAL_MATCH`	Nichts passte nah genug zu einer der beiden Techniken, um zurückgegeben zu werden.
`LOW_RELEVANCE`	Es wurden einige Chunks gefunden, aber keiner war relevant genug.
`SEMANTIC_ONLY`	`results` basieren nur auf Bedeutung; nichts teilte sich Wörter mit deiner Anfrage.
`LEXICAL_ONLY`	`results` teilen sich Wörter mit deiner Anfrage, passen inhaltlich aber womöglich nicht.
`RANKING_DEGRADED`	Die Ergebnisse konnten nicht neu bewertet werden und sind weniger präzise als sonst.

notes ist ein Array, weil mehrere Hinweise gleichzeitig zutreffen können, und es ist leer, wenn es nichts Erwähnenswertes gibt.

Statuscodes

Status	Bedeutung
`200`	Die Suche lief, `results` kann trotzdem leer sein, wenn nichts passte.
`400`	Fehlerhafte `resourceGroupId` oder fehlerhafter Body, z. B. fehlende `query`.
`402`	Der Testzugang ist abgelaufen.
`403`	Kein `x-api-key`-Header gesendet, oder der Key ist unbekannt oder wurde gelöscht.
`404`	Es existiert keine Knowledge Group mit dieser `resourceGroupId`.
`500`	Die Suche ist auf dem Server fehlgeschlagen.

Jede Antwort ausser 200 liefert einen JSON-Body:

{ "message": "Resource group not found" }

Request-Referenz

Request

Response

Notes

Statuscodes

Auf dieser Seite