--- title: NLWeb Documentation Answers description: Deterministic, cited answers from published Agent Community documentation through an NLWeb-compatible endpoint. --- # NLWeb documentation answers Endpoint: `https://agentcommunity.org/ask` `/ask` is a public-documentation answer endpoint. It uses the same deterministic extractive retrieval as the Documentation MCP: it does not call an LLM, and it returns an answer assembled from published documentation with Schema.org `Article` citations. PAGE's JSON response has a stable schema plus a newly generated `query_id` for each response; its SSE stream follows the observed serializers at the pinned NLWeb reference commit described below. This endpoint is separate from the product MCP at `/mcp` and the Documentation MCP at `/mcp/docs`. It never reads members, registrations, authenticated pages, Supabase, private lists, or other non-public data. ## Flat request ```bash curl --get "https://agentcommunity.org/ask" \ --data-urlencode "query=What is AID?" \ --data-urlencode "top_k=5" ``` `query` is the preferred flat field and is required to be 2–500 characters after trimming. `top_k` is optional, with a range of 1–10 and default of 5. PAGE also accepts `q` as a compatibility alias for flat GET and POST clients: ```bash curl --get "https://agentcommunity.org/ask" \ --data-urlencode "q=What is AID?" ``` Send exactly one of `query` or `q`; a request carrying both is invalid. `q` is a PAGE compatibility alias, **not** an NLWeb v0.55 field. The canonical NLWeb structured form remains `query.text`. ## NLWeb v0.55 structured request ```bash curl -X POST "https://agentcommunity.org/ask" \ -H "Content-Type: application/json" \ -d '{ "query": { "text": "What is AID?", "site": "agentcommunity.org" }, "prefer": { "streaming": false, "response_format": "conversational_search", "mode": "list" }, "meta": { "version": "0.55" } }' ``` The optional structured `query.site` must be `agentcommunity.org`; the optional `meta.version` must be `0.55`. `prefer` accepts the v0.55 conversational-search fields `streaming`, `response_format`, `mode`, `accept-language`, and `user-agent`. This endpoint supports `response_format: conversational_search` and `mode: list`. POST bodies must be JSON and are limited to 64 KiB. ## JSON response and citations Successful JSON responses preserve PAGE's answer-object contract: ```json { "query_id": "ask_550e8400-e29b-41d4-a716-446655440000", "query": "What is AID?", "site": "agentcommunity.org", "mode": "list", "total_results": 1, "results": [ { "@type": "Article", "url": "https://agentcommunity.org/docs/aid", "site": "agentcommunity.org", "name": "AID", "description": "Published AID documentation.", "score": 13, "schema_object": { "@context": "https://schema.org", "@type": "Article", "@id": "https://agentcommunity.org/docs/aid", "name": "AID", "description": "Published AID documentation.", "url": "https://agentcommunity.org/docs/aid" } } ], "_meta": { "version": "0.55", "response_type": "answer", "response_format": "conversational_search", "mode": "list", "site": "agentcommunity.org" }, "answer": "Extractive text from published documentation.", "content": [ { "@context": "https://schema.org", "@type": "Article", "@id": "https://agentcommunity.org/docs/aid", "name": "AID", "description": "Published AID documentation.", "url": "https://agentcommunity.org/docs/aid" } ] } ``` `query_id`, `site`, `mode`, and `total_results` are additive compatibility fields used by the NLWeb reference REST API. They remain alongside the v0.55 `_meta` and `results` envelope: the [current v0.55 specification](https://nlweb.ai/docs/specification) defines that envelope, while the [reference implementation's REST guide](https://github.com/nlweb-ai/NLWeb/blob/b423f15d9aeaa023ce75993ac9deed2354597043/docs/nlweb-rest-api.md) documents `query_id` and result attributes. `total_results` always equals `results.length`, and `query_id` is newly generated for each JSON response. Each result is itself a typed Schema.org-compatible `Article`, carries the deterministic backend relevance `score` used for ordering, and retains `schema_object` for reference-REST compatibility. Each item in `content` is a citation to the documentation source used for the answer. When no published source matches, the endpoint returns its deterministic no-answer text with `total_results: 0` and empty `results` and `content` lists. ## Streaming Request streaming with `streaming=true`, `prefer.streaming: true`, or `Accept: text/event-stream`. The successful stream uses only these pinned-reference-compatible event names, in order: 1. `start` 2. `result` (once for each cited `Article`) 3. `complete` There is no custom `answer` or `error` SSE event. Invalid requests and rate limits use ordinary JSON error responses instead. The successful `complete` event contains exactly the version metadata; it does not repeat `response_type`, `mode`, or `site`, and it adds no top-level query or answer: ```text event: complete data: {"_meta":{"version":"0.55"}} ``` ## Access limits `/ask` is a public read endpoint: it serves `access-control-allow-origin: *`, so any browser origin — not just `agentcommunity.org` — may call it directly, alongside no-origin server requests. It sets no cookies and accepts no credentials, so there is nothing origin-scoping would protect. Abuse control is the shared `RL_DOCS_AGENT` public read budget of 60 requests per IP per 60 seconds; a limited request returns `429` with `Retry-After: 60`. The SSE compatibility target is the observed serializer at upstream commit [`b423f15d9aeaa023ce75993ac9deed2354597043`](https://github.com/nlweb-ai/NLWeb/tree/b423f15d9aeaa023ce75993ac9deed2354597043). The pinned repository's current non-streaming handler returns its internal message array, while its REST guide still documents the older flat response family. PAGE therefore carries the flat metadata additively on its v0.55 answer object. This is practical reference compatibility, not a claim that the flat fields are normative v0.55 requirements. Update the target only after deliberately reviewing a newer upstream release.