NLWeb natural-language ask endpoint
NLWeb-conformant natural-language query endpoint. Accepts a plain-language question and returns schema.org-typed product answers, backed by Closient’s shared grounded-retrieval + LLM conversational core (the same core that powers the chat UI).
Modes: list returns ranked schema.org product items only; summarize (default) additionally returns the LLM’s conversational answer in summary.
Streaming: set streaming: true to receive a text/event-stream (SSE) instead of a single JSON document — a start envelope, one result event per ranked schema.org item, summary events pacing the LLM prose (non-list modes), then done. This is the same SSE transport the /search/chat/ chat UI uses (C-3223).
Auth: unauthenticated (anonymous IP-throttled at 60 requests/minute). Every NLWeb instance is also an MCP server — Closient’s MCP endpoint is at /mcp/http (see /.well-known/mcp.json).
Body
Request body for the NLWeb POST /ask endpoint.
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.
1 - 500Response 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.
list, summarize, generate 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).
Optional NLWeb site identifier, echoed back for multi-site clients. Closient serves a single catalog, so this does not change retrieval.
255Response
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.
The query that was answered (echoed back for correlation).
The response mode that was applied.
list, summarize, generate schema.org type of the envelope. Always SearchResultsPage.
The NLWeb site identifier from the request, echoed back.
The agent's natural-language answer in summarize mode; empty string in list mode.
Ranked schema.org product result items (best first).