POST
/
trpc
/
datasets.search
Search Dataset
curl --request POST \
  --url https://api.kontext.dev/trpc/datasets.search \
  --header 'x-api-key: <x-api-key>'

​
Overview

  • Embeds your query and retrieves the topK nearest snippets.
  • User dataset → requires userId; searches the user namespace.
  • Population dataset → omit userId; searches the dataset namespace.

​
Authentication

​
x-api-key
string
required
Your API key

​
Request (tRPC HTTP)

Body (JSON): { "input": { datasetId, query, userId?, topK? } }
  • datasetId (string, required)
  • query (string, required)
  • userId (string, required for user datasets; omit for population)
  • topK (number, optional; default 10, max 100)

​
Response (tRPC envelope)

200 OK 
{
  "result": {
    "data": {
      "namespace": "string|null",
      "rows": [
        {
          "id": "string|number",
          "score": 0.83,
          "attributes": {
            "text": "...",
            "datasetItemId": "it_...",
            "userId": "user_...",
            "developerId": "dev_..."
          }
        }
      ]
    }
  }
}
Note: SDK and tRPC clients return the inner object directly (no wrapper).

​
Namespaces

  • User dataset: kontext.dev.{developerId}.user.{userId}
  • Population dataset: kontext.dev.{developerId}.ds.{datasetId}

​
Errors

  • 400 BAD_REQUEST — userId missing for a user‑anchored dataset
  • 401 UNAUTHORIZED — invalid API key
  • 403 FORBIDDEN — dataset doesn’t belong to your developer
  • 404 NOT_FOUND — dataset not found
  • 500 INTERNAL_SERVER_ERROR

​
Examples

curl -X POST https://api.kontext.dev/trpc/datasets.search \
  -H "x-api-key: ktext_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "datasetId": "ds_123",
      "query": "Show key takeaways",
      "topK": 10
    }
  }'

​
Notes

  • rows[].score may be a similarity or distance score depending on backend configuration; treat it as a relevance indicator only.
  • Use Facts‑first QA (/trpc/datasets.query) for answers strictly from extracted facts.