/ask endpoint: answering questions in plain words

01What it does, and why you need it.

A person or an AI agent sends a question to /ask. Your site searches its indexed content, ranks the matches and returns them as structured JSON using Schema.org, either as a list, a summary or a written answer.

It offers people and AI agents a structured way to question your content rather than scraping pages. If your site holds catalogues, listings or documentation that assistants should answer from directly, this is one route to that.

02Who should deal with this.

This is a web engineering and product decision, not a marketing one. Building it means indexing your content, connecting a language model and hosting an endpoint, so it needs an engineering owner, a content owner who decides what is in scope, and a budget owner, because each query can trigger multiple model calls. Where a site is already on Cloudflare, the hosted option reduces the engineering work to configuration.

Level of importance

Moderate for sites whose value is in structured content, such as products, courses, events, documentation or listings. Low for a site that is mainly a brochure.

03Where it comes from.

NLWeb, short for Natural Language Web, was announced at Microsoft Build in May 2025. Microsoft describes it as an open project that aims to make it simple to create a rich, natural language interface for websites using the model of their choice and their own data. The project was created by R.V. Guha, who previously worked on RSS, RDF and Schema.org, and Microsoft has said it believes NLWeb can play a similar role to HTML in the emerging agentic web.

Microsoft has named TripAdvisor and O’Reilly Media as customers that added NLWeb functionality to their sites.

04The 2 endpoints.

NLWeb defines 2 endpoints, and the arguments are the same for both:

/ask

The conversational endpoint. It returns JSON that a website or app can render for a person.

/mcp

The same functionality exposed as a Model Context Protocol server, so AI agents can call the site as a tool. The /mcp endpoint also supports the core MCP methods list_tools, list_prompts, call_tool and get_prompt.

In Microsoft’s words, MCP is to NLWeb what HTTP is to HTML: the transport underneath, with NLWeb as the content format on top. Each NLWeb instance is also an MCP server.

05How a request works.

The required argument is query, the current question in natural language. The optional arguments defined in the NLWeb REST API documentation are:

site

A token for a subset of the backend’s data, so 1 backend can serve several sites.

decontextualized_query

The full rewritten query, if the client has already resolved references such as “it” or “that one”; if supplied, no rewriting is done server side.

streaming

Defaults to true; set to 0 or false to turn off.

query_id

Auto-generated if not supplied.

mode

list (default), summarize or generate.

The 3 modes matter for cost and behaviour:

list

Returns the top matches from the backend most relevant to the query.

summarize

Returns a summary of those matches along with the list.

generate

Closer to traditional retrieval-augmented generation: the list is built, then 1 or more calls are made to a language model to try to answer the question.

The reference implementation holds no state on the server. Context from earlier turns has to be sent back with each request, which is what prev and decontextualized_query are for.

A request looks like this:

GET

GET https://ask.example.com/ask?query=which+courses+run+in+October&mode=generate&streaming=false

Or as a POST body:

POST body

{
  "query": "Does it reference ISO/IEC 42001?",
  "prev": "AI compliance overview?,Policy scope?,Risk management process?",
  "mode": "summarize"
}

The response is JSON using the Schema.org vocabulary, so a result about a product comes back typed as a Product, a recipe as a Recipe, and so on. That is why NLWeb works best on sites that can be described as lists of items: products, recipes, events, attractions, reviews, documentation pages.

06What it costs to run.

The reference implementation makes several model calls per query. It runs pre-processing steps in parallel, including a relevance check and decontextualisation, then retrieves candidates from a vector index and ranks them with a language model before returning a response. 1 developer analysis of the pipeline reports that a single query may trigger 50 or more targeted model calls. That is the design of the reference implementation, not a fixed property of the protocol; lighter implementations exist.

07How to create one.

There are 3 practical routes.

1 · Cloudflare hosted

Least engineering.
Cloudflare offers NLWeb as a template in its AI Search product. It crawls your site, indexes the content and deploys the /ask and /mcp endpoints. The documented steps: log in to the Cloudflare dashboard; go to Compute & AI > AI Search; select Create AI Search, then choose the NLWeb Website option; select your domain from your Cloudflare account; click Start indexing.

To put it on your own domain, find the deployed Worker under AI Search > Connect > NLWeb tab > Go to Worker, add a custom domain such as ask.example.com, and use ask.example.com/ask.

2 · Self-hosted

The reference implementation.
The NLWeb repository on GitHub contains the core service, connectors for popular language models and vector databases, tools to ingest data (Schema.org JSONL and RSS) into a vector database, and a web server with a sample UI. There is an official .NET 9 implementation, nlweb-net, and a formal TypeSpec definition from which OpenAPI, TypeScript and Go types can be generated.

The published REST API documentation notes that most production deployments use their own user interface and integrate NLWeb directly into their application environment rather than using the sample UI.

3 · Static site

Lightweight implementation.
jdevalk/ask-endpoint is an open source /ask endpoint for static sites on Cloudflare Pages. It adds question answering to any Markdown-based site using Cloudflare Workers AI, is compatible with the NLWeb protocol, and needs no database or vector store. Setup is: copy the functions directory into the project, configure nlweb.config.mjs with the site name and description, generate the index at build time, and add a Workers AI binding in the Pages project settings. Its /ask accepts q or query, mode, site, prev, decontextualized_query and query_id.

4 · Publisher-hosted

Via TollBit.
TollBit hosts NLWeb endpoints for publishers at tollbit.<yoursite>/ask and tollbit.<yoursite>/mcp, which places the endpoint behind their licensing and access controls.

Cloudflare also provides an embeddable search snippet:

Embeddable snippet

<!-- Add css on head -->
<link rel="stylesheet" href="https://ask.example.com/nlweb-dropdown-chat.css">
<link rel="stylesheet" href="https://ask.example.com/common-chat-styles.css">

<!-- Add container on body -->
<div id="docs-search-container"></div>

08Testing an endpoint.

Test

curl "https://ask.example.com/ask?query=opening+hours&mode=list&streaming=false"

For /mcp, Anthropic’s MCP Inspector can be pointed at the endpoint to list the tools and prompts it exposes.

09Sources.

01Microsoft’s own introduction to NLWeb, including the statement that each instance is also an MCP server and the comparison with HTML. news.microsoft.com/source/features/company-news/introducing-nlweb-bringing-conversational-interfaces-directly-to-the-web/
02The main reference implementation in Python, with connectors, ingestion tools and the sample UI. github.com/nlweb-ai/NLWeb
03The NLWeb REST API documentation defining the /ask and /mcp endpoints, all arguments and the 3 modes. github.com/microsoft/NLWeb/blob/main/docs/nlweb-rest-api.md
04Formal TypeSpec specification of the protocol, from which OpenAPI and language types can be generated. github.com/nlweb-ai/nlweb-typespec
05The official .NET 9 implementation with List, Summarize and Generate modes and MCP integration. github.com/nlweb-ai/nlweb-net
06Cloudflare’s guide to deploying NLWeb through AI Search, including custom domain setup and the embeddable snippet. developers.cloudflare.com/autorag/how-to/nlweb
07TollBit’s documentation for hosting NLWeb /ask and /mcp endpoints for publishers. docs.tollbit.com/nlweb/
08Open source NLWeb-compatible /ask endpoint for static sites on Cloudflare Pages, no database required. github.com/jdevalk/ask-endpoint
09Earlier version of the same project, with a clear API parameter table. github.com/jdevalk/nlweb-cloudflare
10InfoWorld’s explanation of NLWeb, the stateless design and the types of site it suits. www.infoworld.com/article/4019814/nlweb-tapping-mcp-for-natural-language-web-search.html
11Computerworld analysis of why Microsoft released NLWeb and its place in the agentic web strategy. www.computerworld.com/article/3990399/why-is-microsoft-offering-to-turn-websites-into-ai-apps-with-nlweb.html
12Forbes coverage of the Build 2025 launch. www.forbes.com/sites/janakirammsv/2025/05/21/microsoft-launches-nlweb-to-simplify-website-agent-interactions/
13Coverage of the Build 2025 announcements, naming TripAdvisor and O’Reilly Media as NLWeb adopters. www.cio.inc/microsoft-pronounces-age-open-scalable-agentic-web-a-28445
14A practitioner’s working build, with request examples for /ask and /mcp. medium.com/@dave-patten/nlweb-mcp-why-every-website-will-soon-need-an-ask-endpoint-92c8bac9d4da
15Step-by-step account of how a query moves through the reference implementation. www.iunera.com/kraken/nlweb/nlwebs-ai-demystified-how-an-example-query-is-processed-in-nlweb/
16Developer overview of the protocol and implementation layers, including the observation on the number of model calls per query. dev.to/punkpeye/nlweb-microsofts-protocol-for-ai-powered-website-search-ng8
17Description of the language model and vector database components in the reference code. dev.to/martinrojas/rethinking-front-end-ux-microsofts-nlweb-and-natural-language-interfaces-2l8a

/ask endpoint: how a website answers questions in plain language.