NLWeb: The /ask Endpoint That Makes Your Site Queryable

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 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 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 describes a chain of LLM calls wrapped around a database lookup.

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.

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 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, 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.”

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 on 25 November 2025 and cites more than 13 million users. Its 3 March 2026 release post 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 describes OAI-SearchBot surfacing sites in ChatGPT search and ChatGPT-User visiting pages when a user asks. Perplexity and Anthropic 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 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 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

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. 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, 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 shows where you stand before you invest in new infrastructure.