---
title: "The same question, in the NLWeb request shape"
method: POST
path: "/ask"
tags: ["Ask"]
---

# The same question, in the NLWeb request shape

`POST /ask`

## Request

- Base URL: `https://youspot.com`
- URL: `https://youspot.com/ask`
- Auth: none required

Identical to `GET /ask`, for callers that would rather send a body than a query string. Answers a question about YouSpot from its own public pages and returns the passages that say it, each with the URL it came from. No credential, and nothing here touches a member's data.

## Request body

- AskRequest: Either `{"query": "text"}` or the NLWeb `{"query": {"text": "..."}}`.
  - `query` union
    - string
    - object
      - `text` string
  - `prefer` object
    - `streaming` boolean

## Response `200`

The matching pages, best first.

- AskResponse
  - `_meta` object, required
    - `query` string
    - `query_id` string
    - `site` string
    - `generated_at` string, date-time
    - `retrieval` 'keyword'
    - `results_returned` integer
  - `@context` 'https://schema.org'
  - `query_id` string
  - `results` AskResult[], required
    - `url` string, uri, required: A page on this site.
    - `name` string, required
    - `site` 'youspot.com', required
    - `score` number, required: Relative, within one response. Not comparable across queries.
    - `description` string, required: The passage that matched, or the page description when the match was in the title.
    - `schema_object` object: schema.org for the page, including the markdown twin under `encoding.contentUrl`.

## Other responses

- `400`: The request was refused. `error` is stable; read `error_description` for the reason.

---

[API](https://skmtc.dev/youspot/apis/youspot-http-api.md) · [All operations](https://skmtc.dev/youspot/apis/youspot-http-api/llms.txt) · [OpenAPI document](https://skmtc.dev/youspot/apis/youspot-http-api/revisions/6615ad5d017d?raw)