Skip to main content
POST
NLWeb natural-language ask endpoint

Body

application/json

Request body for the NLWeb POST /ask endpoint.

query
string
required

The natural-language question to answer, e.g. 'organic almond milk under $5' or 'gluten-free pasta near me'. Routed to Closient's hybrid-retrieval conversational-search agent.

Required string length: 1 - 500
mode
enum<string>
default:summarize

Response mode. list returns ranked schema.org product items only (no generated prose). summarize (default) additionally returns the agent's conversational answer in summary. generate is reserved and currently aliases summarize.

Available options:
list,
summarize,
generate
streaming
boolean
default:false

NLWeb streaming flag. false (default) returns a single JSON SearchResultsPage document. true returns a text/event-stream (SSE): a start envelope event, one result event per ranked schema.org item, summary events pacing the LLM prose (summarize/generate modes only — list is LLM-free), then a terminal done event. The SSE transport is the same one the /search/chat/ chat UI uses (C-3223).

site
string
default:""

Optional NLWeb site identifier, echoed back for multi-site clients. Closient serves a single catalog, so this does not change retrieval.

Maximum string length: 255

Response

OK

NLWeb /ask response — a schema.org SearchResultsPage envelope.

The top-level object is a schema.org SearchResultsPage: it echoes the query and carries the ranked results. In summarize mode the agent's natural-language answer is in summary; in list mode summary is an empty string.

query
string
required

The query that was answered (echoed back for correlation).

mode
enum<string>
required

The response mode that was applied.

Available options:
list,
summarize,
generate
@type
string
required
read-only

schema.org type of the envelope. Always SearchResultsPage.

site
string
default:""

The NLWeb site identifier from the request, echoed back.

summary
string
default:""

The agent's natural-language answer in summarize mode; empty string in list mode.

results
AskResultItem · object[]

Ranked schema.org product result items (best first).