---
title: "NLWeb /ask: a natural-language question, answered as matching items"
method: GET
path: "/ask"
tags: ["read"]
---

# NLWeb /ask: a natural-language question, answered as matching items

`GET /ask`

## Request

- Base URL: `https://cotal.ai`
- URL: `https://cotal.ai/ask`
- Auth: none declared

Implements the NLWeb protocol (github.com/nlweb-ai/NLWeb) in `list` mode: keyword retrieval over the build log, docs links and site pages, each result with its schema.org object. `summarize` and `generate` are answered as lists and say so in `_meta`. Streams as Server-Sent Events (`start`, `result`, `complete`) when `streaming=true`, `prefer.streaming=true`, or `Accept: text/event-stream`; plain JSON otherwise. POST accepts the same parameters as a JSON body.

## Query parameters

- `query` string, required
- `mode` 'list' | 'summarize' | 'generate'
- `streaming` boolean
- `query_id` string
- `prev` string

## Response `200`

Matching items (JSON), or an SSE stream when streaming was requested.

- AskResponse
  - `query_id` string, required
  - `_meta` object, required
    - `response_type` 'list', required
    - `version` string, required
    - `site` string
    - `mode` string
    - `requested_mode` string
    - `note` string
    - `query` string
    - `count` integer
  - `results` object[], required
    - `url` string, uri, required
    - `name` string, required
    - `site` string, required
    - `score` number, required
    - `description` string, required
    - `schema_object` object, required: schema.org JSON-LD for the item.

## Other responses

- `400`: Malformed body or validation error (`code`: bad_request | validation_error).
- `429`: Rate limited (`code`: rate_limited). Retry after `Retry-After` seconds.
- `default`: Any other failure. The body is always the Error object, with a stable `code` and a `hint`.

---

[API](https://skmtc.dev/cotal/apis/cotal-ai-public-api.md) · [All operations](https://skmtc.dev/cotal/apis/cotal-ai-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cotal/apis/cotal-ai-public-api/revisions/34ab992f2172?raw)