---
title: "Natural language search (NLWeb, structured body)"
method: POST
path: "/api/v1/ask"
tags: ["Search"]
---

# Natural language search (NLWeb, structured body)

`POST /api/v1/ask`

## Request

- Base URL: `https://www.adadiamonds.com`
- URL: `https://www.adadiamonds.com/api/v1/ask`
- Auth: none required

Same as GET; accepts the NLWeb 0.55 structured body or the legacy flat body.

## Request body

- object: NLWeb 0.55 structured request. The legacy flat body {query, site, mode, streaming, prev, query_id} is also accepted.
  - `query` object, required
    - `text` string, required
    - `site` string
  - `context` object
    - `prev` string[]
  - `prefer` object
    - `streaming` boolean
    - `mode` 'list' | 'summarize' | 'generate'
    - `response_format` 'conversational_search' | 'chatgpt_app'
  - `meta` object
    - `version` string

## Response `200`

Answer (or an application-level failure with HTTP 200).

- object
  - `_meta` object, required
    - `response_type` 'answer' | 'failure', required
    - `version` string, required
    - `response_format` 'conversational_search' | 'chatgpt_app'
    - `query_id` string
  - `results` object[]
    - `@type` string, required
    - `@context` 'https://schema.org'
    - `url` string, uri, required
    - `name` string, required
    - `site` 'adadiamonds.com', required
    - `siteUrl` string, uri
    - `score` integer, required
    - `description` string
    - `schema_object` object, required: Full schema.org JSON-LD (Product with offers in USD, or Article).
  - `summary` string: Present for mode=summarize or generate; built deterministically from the top results.
  - `content` object[]: chatgpt_app format only.
    - `type` 'text'
    - `text` string
  - `structuredData` object[]: chatgpt_app format only.
    - `@type` string, required
    - `@context` 'https://schema.org'
    - `url` string, uri, required
    - `name` string, required
    - `site` 'adadiamonds.com', required
    - `siteUrl` string, uri
    - `score` integer, required
    - `description` string
    - `schema_object` object, required: Full schema.org JSON-LD (Product with offers in USD, or Article).
  - `error` object: Present when response_type is failure.
    - `code` 'NO_RESULTS' | 'INVALID_QUERY' | 'UNSUPPORTED_FORMAT' | 'UNSUPPORTED_MODE' | 'RATE_LIMITED' | 'INTERNAL_ERROR' | 'TIMEOUT' | 'TOKEN_LIMIT'
    - `message` string

## Other responses

- `400`: Malformed request (missing query, invalid JSON).
- `429`: Rate limited; `Retry-After` is set.

---

[API](https://skmtc.dev/adadiamonds/apis/ada-diamonds-agent-api.md) · [All operations](https://skmtc.dev/adadiamonds/apis/ada-diamonds-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adadiamonds/apis/ada-diamonds-agent-api/revisions/2b2ed3201815?raw)