Search Request Reference | Tuix RAG Service

A search request is a POST with a JSON body, both with the npm client and with fetch. The resourceGroupId is part of the URL.

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

Request

Field	Type	Required	Description
`resourceGroupId`	string	Yes	ID of the Knowledge Group to search (part of the path).
`query`	string	Yes	The text to search for.
`limit`	number	No	Maximum number of chunks to return, from `1` to `20`. Defaults to `3`.
`role`	string	No	Only match resources tagged with this role, or with none, see Role Filter.

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

query is the only required field. Omit limit to get the default of 3 results, and omit role to search across every resource regardless of how it is tagged.

Response

200 OK with the matching chunks:

Field	Type	Description
`query`	string	The `query` you sent, echoed back.
`count`	number	Number of chunks in `results`.
`results`	array	The matching chunks, sorted by `score`, highest first.
`results[].id`	string	ID of the chunk.
`results[].resource_id`	string	ID of the resource the chunk was cut from.
`results[].content`	string	The chunk's text.
`results[].added_at`	string	When the chunk was created, ISO 8601.
`results[].score`	number	Relevance of this chunk to the query, see Search and ranking.
`notes`	array	Explanations about the search itself, see Notes below. May be empty.

{
    "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
        }
    ]
}

Each entry is one chunk, not a whole resource, see Understanding chunks. A resource can appear more than once in results if several of its chunks matched.

Notes

notes explains something about the search itself, rather than about a specific chunk, see Understanding results for how to use it. Each entry has a reason code and a human readable 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`	Meaning
`EMPTY_SCOPE`	The Knowledge Group, or the role you filtered by, has no content at all.
`PHRASE_NOT_FOUND`	A quoted phrase in `query` does not appear in any resource.
`NO_LEXICAL_MATCH`	Nothing matched either technique closely enough to return.
`LOW_RELEVANCE`	Some chunks were found, but none scored high enough to be relevant.
`SEMANTIC_ONLY`	`results` are based on meaning only; nothing shared any of your query's words.
`LEXICAL_ONLY`	`results` share words with your query but may not be close in meaning.
`RANKING_DEGRADED`	Results could not be reranked and are less precise than usual.

notes is an array because more than one can apply at once, and it is empty when there is nothing noteworthy to report.

Status codes

Status	Meaning
`200`	Search ran, `results` may still be empty if nothing matched.
`400`	Malformed `resourceGroupId` or request body, e.g. missing `query`.
`402`	Trial access has expired.
`403`	No `x-api-key` header sent, or the key is unknown or was deleted.
`404`	No Knowledge Group exists with that `resourceGroupId`.
`500`	Search failed on the server.

Every non-200 response answers with a JSON body:

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

Request reference

Request

Response

Notes

Status codes

On this page