Search or Ask

Search or ask lets one search field answer questions too: a judge reads what is typed on each pause and offers to answer it, and an answer is written, on request, from the dataset's own records. The Search or Ask guide explains the settings and the front end; this page is the API.

The routes answer 404 until the instance shows Search or ask (the console's Admin > Settings > Experimental) and a team admin shows it on the dataset (its Options tab). They answer 409 searchOrAskDisabled while the dataset's settings have it switched off, and 409 searchOrAskUnavailable where the instance has no model key.

All routes are under /api/teams/{teamName}/datasets/{dataSetName}/search-or-ask. A Search key is enough for everything a visitor's page calls: the settings, intent, filters and ask.

Judge what is typed

Call intent on a pause in typing, beside the search the page already runs.

To have the judgement ready when the pause comes, also call it while the visitor types, with "prefetch": true and one call in flight at a time: when one returns, send the next for whatever the field holds by then. The judge reads the text ahead and keeps its answer, so the pause's own call comes back at once. Only the pause's call counts as a judgement in the statistics, and calls made ahead never use the last fifth of the day's budget, which stays for the pauses. useSearchOrAsk() does this for you.

POST /api/teams/{teamName}/datasets/{dataSetName}/search-or-ask/intent?session={pageLoadId}&queryId={searchQueryId}
Content-Type: application/json

{ "text": "how do i set up boost rules" }

{
  "p": 0.91,
  "answerable": 0.84,
  "criteria": null,
  "offer": "strong",
  "thresholds": { "strong": 0.65, "strongHide": 0.45, "invite": 0.4, "inviteHide": 0.3 },
  "cached": false,
  "ms": 312,
  "searchText": "set up boost rules",
  "refocusWhileTyping": true,
  "inviteOnAskPhrase": true,
  "cutWhileAsking": true,
  "cutShareOfTop": 0.5,
  "cutTopFloor": 0.2,
  "strictCoverageWhileAsking": true,
  "filtersWhileTyping": "off",
  "mode": "soft"
}

The other fields are the dataset's While asking settings, sent with every judgement so a change applies on the next pause. A front end keeps an offer up while p stays above the …Hide threshold, so it does not blink as the visitor types on. Text is 1 to 300 characters.

Answer a question

POST /api/teams/{teamName}/datasets/{dataSetName}/search-or-ask/ask?session={pageLoadId}
Content-Type: application/json

{ "question": "how do i set up boost rules", "history": [] }

The answer streams as server-sent events:

event: status
data: {"step":"Searching"}

event: sources
data: [{"n":1,"documentKey":42,"title":"Boost Rules"},{"n":2,"documentKey":57,"title":"Schedule Boost Rules for Campaigns"}]

event: text
data: {"delta":"Open the dataset's Boost rules tab and choose New boost rule [1]."}

event: done
data: {"model":"anthropic/claude-sonnet-5.5","askId":"9b1c…","latencyMs":3480}

history carries the conversation for a follow-up: up to three earlier turns of { question, answer }. A question is 1 to 1,000 characters. Send "proactive": true when the page starts the answer on its own, in the proactive mode, rather than the visitor asking: it counts against the day's proactive answers, and a dataset in another mode answers 429. The response's Indx-Ask-Id header names the answer from the first byte: send it as the queryId of a select when the visitor opens a cited source.

Turn a description into filters

On a catalogue, when intent reports a strong criteria, filters turns the text into filters on the dataset's own fields: a value or a number range on a Filterable field, checked against the values it holds. text is what no filter covers, to search for.

POST /api/teams/{teamName}/datasets/{dataSetName}/search-or-ask/filters
Content-Type: application/json

{ "text": "funny space movies from the 80s" }

{
  "filters": [
    { "field": "genres", "value": "Comedy" },
    { "field": "release_year", "min": 1980, "max": 1989 }
  ],
  "text": "space",
  "sort": null,
  "ms": 1460
}

Settings

GET returns the dataset's settings, what it runs with after defaults (effective: the site description, the fields the judge reads, the Ask phrases in effect, the model the answers are written with, how a catalogue's questions are searched, and the models the instance offers as answerModels) and whether the instance can run it (available). A Search key reads them without knowledge. PUT replaces them (a Full key) and applies from the next call; DELETE puts every value back to its default. PUT …/shown with { "shown": true } is the team admin's switch.

Limits

A call over the per-address limit, or over the dataset's daily budget, answers 429 with Retry-After and retryAfterSeconds; the budget's code is searchOrAskBudgetSpent, and it resets at midnight UTC.

Statistics

GET /api/teams/{teamName}/datasets/{dataSetName}/statistics/search-or-ask?days=30

A Read key. Offers shown and taken, questions asked and how they ended, the answers the proactive mode wrote on its own (proactiveAnswers, apart from asks), cited sources opened, what it cost, and the calls against the budget, with the questions the content did not answer first. Pass ?session=, ?source= and ?queryId= on intent and ask as on searches, so the statistics tie them to the searches they came from.