# NLWeb: The /ask Endpoint That Makes Your Site Queryable

> NLWeb lets agents ask your site questions and get schema.org JSON back. How it differs from MCP, why adoption is stuck in pilots, and how to test yours.

URL: https://llmagnet.com/blog/nlweb-ask-endpoint  
Author: Ben Cohen, Founder & CEO at LLMagnet  
Published: 2026-11-03  
Updated: 2026-11-10  
Category: Guides

NLWeb is an open project from Microsoft that adds an /ask endpoint to a site, so an agent can send a plain-language question and get structured JSON back instead of parsing HTML. The deployments that trackers name are a few pilots and launch partners, and no public count exists, so treat it as an experiment and not as a way to win AI visibility. It does a different job from MCP: /ask answers questions about your content, while MCP tools let an agent take actions.

## Contents

1. What NLWeb Actually Does: The /ask Endpoint
2. What Happens to a Question Inside NLWeb
3. How NLWeb Differs From MCP
4. Where Adoption Actually Stands: Early Pilots, No Public Count
5. What AI Agents Do When /ask Isn’t Available
6. How to Check Whether Your Site Has an /ask Endpoint
7. The Schema.org Dependency: Why NLWeb Alone Isn’t Enough
8. Three Ways to Run a Test
9. The Early-Mover Case, and Its Limits
10. FAQ

## What NLWeb Actually Does: The /ask Endpoint

An NLWeb deployment exposes two endpoints, `/ask` and `/mcp`, and [the project’s REST API document](https://github.com/nlweb-ai/NLWeb/blob/main/docs/nlweb-rest-api.md) says the arguments are the same for both. One argument is required: `query`, the question in natural language. The optional ones include `prev` (earlier questions in the conversation), `mode` (`list`, `summarize` or `generate`) and `streaming`, which is on by default.

The response is a JSON object with a `query_id` and an array of results. Each result has a `url`, `name`, `site`, `score`, `description` and `schema_object`, which is the original item from your data store. The `description` is written by an LLM, so the answer is structured but not fully deterministic.

NLWeb is software you run, not a file you upload. [The repository](https://github.com/nlweb-ai/NLWeb) lists the LLM providers it works with (OpenAI, Anthropic, Gemini and others) and the vector stores it needs (Qdrant, Milvus, Elasticsearch, Postgres, Cloudflare AutoRAG and others). It also says that “every NLWeb instance also acts as an MCP server,” so one deployment can serve both REST and MCP clients.

## What Happens to a Question Inside NLWeb

[The project’s query walkthrough](https://github.com/nlweb-ai/NLWeb/blob/main/docs/life-of-a-chat-query.md) describes a chain of LLM calls wrapped around a database lookup.

![Five stages of an NLWeb query: the question arrives, parallel LLM calls analyze and rewrite it, an LLM picks a tool, and the search tool typically queries a vector database, LLM calls score each item, and JSON results come back. One query can involve more than 50 LLM calls.](https://llmagnet.com/images/blog/charts/nlweb-query-stages.png)

*Source: NLWeb project documentation, life of a chat query.*

**Cost follows questions, not pages.** The walkthrough says one query can involve “over 50 LLM API calls.” Estimate spend per question, and set a rate limit before the endpoint goes public.

**The mode decides how far you can trust the output.** In `list`, the default, results are items from your database. `generate` works like conventional RAG, with LLM calls attempting an answer. If you publish prices or specifications, start with `list` and read any generated answer against the stored items.

## How NLWeb Differs From MCP

Coverage of “agent-ready websites” often lumps these together. They answer different questions.

| Protocol | Question it answers | What comes back | Typical use |
| --- | --- | --- | --- |
| NLWeb /ask | “What does this site say about X?” | JSON results carrying schema.org items | Research, comparison, lookup |
| MCP tools | “What can this site do for me?” | Tool call results | Bookings, inventory checks, transactions |
| llms.txt | “Where is the useful content on this site?” | A plain-text index | [Used on demand](https://llmstxt.org/) by an agent helping a user |
| robots.txt | “May this crawler fetch this path?” | Access rules | Crawl permissions |

The two are not rivals, because NLWeb’s `/mcp` endpoint exposes the same ask function to MCP clients. The real limit is scope. A site with only `/ask` can answer questions but can’t take a booking. A site with only action tools can take a booking but gives an agent no general way to query its content.

## Where Adoption Actually Stands: Early Pilots, No Public Count

Microsoft announced NLWeb at Build in May 2025. [Presenc AI’s September 2026 status page](https://presenc.ai/research/nlweb-adoption-2026) lists the launch partners as Chicago Public Media, Allrecipes, Eventbrite, Hearst (Delish), O’Reilly Media, Tripadvisor, Shopify, Snowflake and Inception Labs. It also states that “no public count of NLWeb deployments exists,” and that any “X thousand sites” figure is an estimate. Its only hard adoption numbers are for the GitHub repository: about 6,300 stars and 700 forks. Presenc sells agent-traffic monitoring, so read its framing with that in mind.

[Lumar’s capability tracker](https://agentic-readiness.lumar.io/docs/capabilities/nl-web.md), from another vendor in this market, goes further. It rates NLWeb as “early pilots” and marked the direction as receding on 15 September 2026, citing no substantive change to the project since June against 65 open issues. By its count, O’Reilly Media is in production, Tripadvisor is in production on an internal frontend rather than a public `/ask` endpoint, and Shopify, Snowflake, Eventbrite and Hearst are announced only. Its summary: “Nothing has been independently measured yet.”

![Named NLWeb deployments in Lumar’s tracker, from weakest to strongest: announced only for Shopify, Snowflake, Eventbrite and Hearst; production on an internal frontend for Tripadvisor; production for O’Reilly Media; and independently measured for none.](https://llmagnet.com/images/blog/charts/nlweb-adoption-ladder.png)

*Source: Lumar capability tracker, trajectory marked 15 September 2026, checked against published documents 20 October 2026. Vendor data.*

Lumar also notes that the reference code has never shipped a tagged release, so a team deploying it has to pin a commit and track changes by hand.

WordPress is the one route to scale, and it needs careful reading. [Yoast announced a collaboration with NLWeb](https://yoast.com/press/yoast-nlweb-microsoft-251125/) on 25 November 2025 and cites more than 13 million users. [Its 3 March 2026 release post](https://yoast.com/yoast-seo-march-3-2026) introduced Schema Aggregation for sites updated to 27.1, an opt-in feature that combines a site’s structured data into one site-level feed. That post describes a schema feed. It doesn’t describe an `/ask` endpoint, so don’t count Yoast’s user base as NLWeb deployments.

## What AI Agents Do When /ask Isn’t Available

They do what they already do: crawl and fetch pages. [OpenAI’s crawler documentation](https://developers.openai.com/api/docs/bots) describes OAI-SearchBot surfacing sites in ChatGPT search and ChatGPT-User visiting pages when a user asks. [Perplexity](https://docs.perplexity.ai/guides/bots) and [Anthropic](https://support.claude.com/en/articles/8896518-does-anthropic-crawl-data-from-the-web-and-how-can-site-owners-block-the-crawler) describe the same split between search crawlers and user-triggered fetchers.

We couldn’t find a mainstream assistant that documents checking for `/ask` before it fetches your pages. So an `/ask` endpoint doesn’t replace crawlable HTML today. If your content only appears after client-side rendering, or your CDN blocks these fetchers, fix that first.

## How to Check Whether Your Site Has an /ask Endpoint

Send a test question with any HTTP client. The REST document lists the arguments but not the HTTP method, so try a query string first and switch to POST if you get a 405:

```
curl "https://yourdomain.com/ask?query=What+does+this+website+offer&streaming=false"
```

A working NLWeb endpoint returns JSON with a `query_id` and results. A 404 or an HTML page means it isn’t implemented. [Lumar’s agentic-readiness checks](https://agentic-readiness.lumar.io/docs/capabilities/nl-web.md) test the `/ask` endpoint for error and malformed responses and the MCP ask tool for a description and query input, and only run when the technology is detected.

A valid response doesn’t prove the answers are good. For each test question, check four things. The URL opens and is the right page. The top result is the one a person would pick. The `description` agrees with `schema_object`, since an LLM wrote it and it can drift. And a question your site can’t answer comes back with few or no results, not a stretch.

On WordPress, check Yoast first. Update the plugin, then turn on the NLWeb integration or the Schema Aggregation toggle in its settings. The release post’s example link points to `/wp-json/yoast/v1/schema-aggregator/get-xml`, which is a schema feed and not `/ask`. If you try a third-party NLWeb plugin, confirm what it exposes with the request above instead of trusting the listing.

## The Schema.org Dependency: Why NLWeb Alone Isn’t Enough

NLWeb works from what you feed it. The repository describes it as using “Schema.org and related semi-structured formats like RSS,” and each result returns the stored item as `schema_object`. Thin markup or a partial feed means thin answers.

This is a requirement of NLWeb and not of Google. [Google’s AI optimization guide](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide) says structured data “isn’t required for generative AI search, and there’s no special schema.org markup you need to add.”

Before you deploy anything, list the content an agent would ask about (products, articles, events, locations). Check that each type has complete markup or a clean feed. Then load it into a test instance and run 20 real customer questions against it. The failures will show you which fields are missing.

## Three Ways to Run a Test

| Route | What you do | What you get | Watch out for |
| --- | --- | --- | --- |
| **Local reference code** | Follow the [hello world guide](https://github.com/nlweb-ai/NLWeb/blob/main/docs/nlweb-hello-world.md): Python 3.10 or later, an LLM key and an embedding provider, then load an RSS feed with `db_load`. | A private test on your own feed. A local Qdrant database is preconfigured. | The README says “CI/CD pipelines are not yet included,” so a production setup is your own build. |
| **Cloudflare AI Search** | Create an instance with Website as the source, then [enable the NLWeb Worker](https://developers.cloudflare.com/ai-search/how-to/nlweb) in its settings. | A Worker serving `/ask` and `/mcp`, built from a crawl of your rendered pages. | Cloudflare calls it a “public preview ideal for experimentation.” Its documentation doesn’t mention Schema.org. |
| **Yoast on WordPress** | Update the plugin and turn on Schema Aggregation. | A site-level schema feed. | It isn’t an `/ask` endpoint. |

**If you self-host, treat it as a public API.** In 2025, security researcher Aonan Guan found a path traversal bug in the reference code that let a request read server files, including AI model API keys, [iTnews reported](https://www.itnews.com.au/news/serious-path-traversal-bug-found-in-microsofts-nlweb-agentic-web-tool-619469). He reported it on 28 May, and Microsoft committed a patch on 30 June. Run a current build behind a reverse proxy. The REST document doesn’t cover authentication, so plan access control yourself.

## The Early-Mover Case, and Its Limits

Agent-facing standards are barely deployed anywhere. [Cloudflare’s scan, published in April 2026](https://blog.cloudflare.com/agent-readiness/), which started from the 200,000 most visited domains, found MCP Server Cards and API Catalogs together on fewer than 15 sites. That doesn’t measure `/ask`, but it shows how early this is.

Being early only pays if agents use the endpoint, and no study we could find shows that `/ask` raises citations or agent traffic. With development reported as slowing, here is what we would do:

- **WordPress with Yoast:** turn on the feature. The cost is a settings change, so little is lost if agents ignore it.
- **Large catalogs or publishers that want conversational search for their own visitors:** run a pilot. The human use case justifies it, and agent access comes along with it.
- **Everyone else:** wait, and check the project’s activity again in six months. Spend the time on crawl access and on content that answers real questions.

If you run a pilot, set the pass mark before launch. Track four numbers each week: requests to `/ask` and `/mcp` by user agent, the share of test questions with a correct top result, the share returning nothing, and LLM cost per question. If agent requests stay near zero after a quarter, treat it as site search.

LLMagnet measures AI visibility across seven engines, and its agent prepares fixes for your approval. The [free audit](https://ai-visibility.llmagnet.com) shows where you stand before you invest in new infrastructure.

## FAQ

### What does the NLWeb /ask endpoint do?

It takes a natural-language question in a required query argument and returns JSON results from your own content. Each result includes a URL, name, score, an LLM-written description and the original schema.org item.

### Where does the endpoint live?

NLWeb’s REST API document defines two endpoints, /ask and /mcp, which take the same arguments. Yoast’s WordPress feature is different: its release post describes a schema feed, not an /ask endpoint.

### Is /ask better than letting agents fetch pages?

It gives cleaner structured results where it exists, but we found no mainstream assistant that documents checking for /ask first. Crawlable HTML still matters more today.

### How is NLWeb different from MCP?

NLWeb’s ask function answers what a site says about a topic. MCP tools perform actions such as bookings or inventory checks. Every NLWeb instance also acts as an MCP server, so the two can run together.

### Where does NLWeb adoption stand?

No public count of deployments exists. Lumar’s tracker rates it as early pilots and marked it as receding in September 2026, with O’Reilly Media and an internal Tripadvisor frontend in production and Shopify, Snowflake, Eventbrite and Hearst announced only.

### Does NLWeb work without Schema.org markup?

It needs structured input. NLWeb works from Schema.org and related formats like RSS, so thin markup or a partial feed limits what it can return. Google Search itself doesn’t require special markup for AI features.

### How much does NLWeb cost to run?

There’s no license fee, since the code is MIT-licensed, but the running costs are yours. The project’s walkthrough says one query can involve over 50 LLM API calls, and you also pay for a vector store and hosting. Estimate spend per question and set a rate limit.

### Is it safe to expose an NLWeb endpoint publicly?

Treat it as any public API. A 2025 path traversal bug in the reference code could expose files including AI model API keys. Microsoft patched it, so run a current build behind a reverse proxy. The REST document doesn’t cover authentication.