> ## Documentation Index
> Fetch the complete documentation index at: https://evalgate.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# NLWeb /ask

> Authenticated deterministic search over EvalGate's published documentation.

# NLWeb /ask

EvalGate exposes an authenticated NLWeb-compatible `/ask` endpoint for agents
that need to find published documentation. It performs bounded deterministic
search over EvalGate's published documentation catalog. It does not call a
model, read repositories, access customer data, or summarize private content.

Every request requires an organization-scoped EvalGate API key with the
`docs:read` scope:

```bash theme={null}
curl 'https://www.evalgate.com/ask?q=MCP&streaming=false' \
  -H "Authorization: Bearer $EVALGATE_API_KEY"
```

The endpoint also accepts the modern POST shape:

```json theme={null}
{
  "query": { "text": "How do I connect MCP?" },
  "prefer": { "streaming": false }
}
```

The legacy POST shape `{ "query": "How do I connect MCP?", "streaming":
true }` remains accepted. `GET` uses `query`, `q`, or `text` as the query
parameter. Results are list/search results only; `summarize` and `generate`
modes return a truthful unsupported-mode error.

## JSON response

Non-streaming requests return `query_id`, the normalized query, a deterministic
`results` list, and NLWeb metadata:

```json theme={null}
{
  "query_id": "nlweb-…",
  "query": "How do I connect MCP?",
  "results": [
    {
      "name": "MCP integration",
      "identifier": "platform/mcp-integration",
      "title": "MCP integration",
      "url": "https://www.evalgate.com/docs/platform/mcp-integration",
      "site": "evalgate.com",
      "description": "Configure Claude, coding agents, and other MCP clients.",
      "text": "…",
      "score": 9,
      "schema_object": {
        "@context": "https://schema.org",
        "@type": "TechArticle",
        "name": "MCP integration",
        "description": "Configure Claude, coding agents, and other MCP clients.",
        "url": "https://www.evalgate.com/docs/platform/mcp-integration"
      }
    }
  ],
  "_meta": { "response_type": "answer", "version": "0.2" }
}
```

## Streaming response

Set `prefer.streaming` to `true` (or use the legacy `streaming` field) to
receive `text/event-stream`. Events are emitted in this order:

1. `start` — identifies the query.
2. `result` — one event per matching published document.
3. `complete` — reports the result count.

The `WWW-Authenticate` challenge on a `401` points agents to EvalGate's
protected-resource metadata. A key with no `docs:read` grant receives `403`.