Search API over HTTP or npm | Tuix RAG Service

Search a Knowledge Group from your own backend, straight over HTTP or with the npm client.

The RAG Service exposes one endpoint for external integrations: search. It is plain HTTP with JSON, so any backend that can make a request can use it, and the x-api-key header is the only requirement, see Prerequisites.

Endpoint

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

resourceGroupId is the Group ID of the Knowledge Group to search.

Request body

Field	Type	Required	Description
`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"
}

Response

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

results is already sorted by score, highest first. Each entry is one chunk, not a whole resource, see Understanding chunks. notes can carry short explanations about the search itself, e.g. that nothing matched closely, see Search and ranking. Every field and status code is listed in the Request reference.

An API key is a credential for your account. Never call this endpoint straight from the browser with your key, keep it on a server you control, see API keys.

Example

const searchKnowledge = async (query: string, role?: string) => {
    const response = await fetch(
        `${process.env.API_BASE_URL}/api/resource-groups/${process.env.TUIX_RAG_GROUP_ID}/search`,
        {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'x-api-key': process.env.TUIX_RAG_API_KEY!,
            },
            body: JSON.stringify({ query, limit: 5, role }),
        },
    )
 
    if (!response.ok) {
        throw new Error(`RAG search failed: ${response.status}`)
    }
 
    const { results } = await response.json()
    return results
}

Client package

Our npm client package wraps the same endpoint with generated types.

npm i tuix-rag-service-client

Configure it with your base URL and API key:

import { ClientApi, Configuration } from 'tuix-rag-service-client'
 
export const ragClient = new ClientApi(
    new Configuration({
        basePath: process.env.API_BASE_URL,
        apiKey: process.env.TUIX_RAG_API_KEY,
    }),
)

Then search with apiSearchResourceGroup:

const response = await ragClient.apiSearchResourceGroup({
    resourceGroupId: process.env.TUIX_RAG_GROUP_ID!,
    searchRequestDTO: {
        query: 'What is your return policy?',
        limit: 5,
        role: 'customer',
    },
})
 
console.log(response.results)

External integrations

Endpoint

Example

Client package

On this page