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

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:

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

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:

{
  "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 defines that envelope, while the reference implementation's REST guide 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:

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