---
title: "Ask the documentation a natural-language question (NLWeb)"
method: POST
path: "/api/ask"
---

# Ask the documentation a natural-language question (NLWeb)

`POST /api/ask`

## Request

- Base URL: `https://app.atisbo.dev`
- URL: `https://app.atisbo.dev/api/ask`
- Auth: none declared

Microsoft NLWeb ask endpoint over the Atisbo documentation. Send {"query": "…"} and get `_meta` plus an array of matching doc pages (url, name, site, score, description). Set `streaming: true` for the v0.55 SSE event framing (start → result per hit → complete); an `Accept: text/event-stream` header opts GET-style clients in too. RETRIEVAL ONLY: mode=list semantics always apply — asking for summarize/generate returns the same ranked list with _meta.limitations stating that nothing is generated.

## Request body

- object
  - `query` string, required
  - `streaming` boolean: Respond with NLWeb v0.55 SSE events instead of one JSON object.
  - `mode` 'list' | 'summarize' | 'generate': Only list does anything; the other values are answered honestly with list output.
  - `max_results` integer
  - `query_id` string: Client-supplied correlation id; generated when omitted.

## Response `200`

The answer — one JSON object, or an SSE stream when streaming was requested.

- object
  - `_meta` object, required
    - `version` string, required
    - `response_type` string, required
    - `mode` string
    - `site` string
    - `limitations` string: Always states retrieval-only.
    - `streaming` boolean
  - `query_id` string
  - `results` object[], required
    - `url` string, uri, required
    - `name` string, required
    - `site` string, required
    - `score` number, required: Keyword-overlap count, comparable only within one response.
    - `description` string

## Other responses

- `400`: Missing query or malformed JSON.
- `413`: Query exceeded 500 characters.
- `429`: Per-IP rate limit reached (20 requests per minute; fail-closed).

---

[API](https://skmtc.dev/atisbo/apis/atisbo-api.md) · [All operations](https://skmtc.dev/atisbo/apis/atisbo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/atisbo/apis/atisbo-api/revisions/708d199a2378?raw)