# Request & Response

## Endpoint

`POST`

```text
https://api.webz.io/api/news/answers
```

## Authentication

Use your Webz API token in one of these ways:

- Recommended: send `Authorization: Bearer YOUR_API_KEY`.
- Alternative: add `?token=YOUR_API_KEY` to the endpoint URL.

Your account must have the `api_news` permission and enough credits or PAYG balance for the selected answer type.

## Request body

Send both parameters in a JSON body.

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `query` | string | Yes | — | Natural-language question. Maximum 750 characters and 100 words. |
| `detailed` | boolean | No | `false` | Set to `true` for a longer answer based on more evidence. |

The API infers the searches, filters, time window, language, and sort order from `query`. You do not send News Search filters or result-count parameters.

### Standard answer

```bash
curl -s -X POST "https://api.webz.io/api/news/answers" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "query": "Why has Nvidia been under regulatory scrutiny in the past week?",
    "detailed": false
  }'
```

### Detailed answer

```bash
curl -s -X POST "https://api.webz.io/api/news/answers" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "query": "Why has Nvidia been under regulatory scrutiny in the past week?",
    "detailed": true
  }'
```

## Response

A successful request returns HTTP `200`.

```json
{
  "query": "Why has Nvidia been under regulatory scrutiny in the past week?",
  "detailed": true,
  "answer": {
    "text": "Regulators have focused on Nvidia's market position and business practices [1].",
    "citations": [
      {
        "id": "article-uuid_0",
        "title": "Regulators examine Nvidia's market position",
        "url": "https://news.example.com/nvidia-regulatory-review",
        "published": "2026-10-18T09:30:00Z",
        "supporting_text": "Regulators are examining Nvidia's market position and business practices."
      }
    ],
    "insufficient_evidence": false
  },
  "total_results": 1,
  "results": [
    {
      "score": 8.7,
      "article": {
        "article_id": "article-uuid",
        "url": "https://news.example.com/nvidia-regulatory-review",
        "title": "Regulators examine Nvidia's market position",
        "published_at": "2026-10-18T09:30:00Z"
      },
      "chunk": {
        "chunk_id": "article-uuid_0",
        "chunk_index": 0,
        "text": "Regulators are examining Nvidia's market position and business practices."
      },
      "metadata": {
        "language": "english",
        "domain": "news.example.com",
        "site_type": "news"
      }
    }
  ],
  "credits_used": 8,
  "requests_left": 992
}
```

| Field | Description |
| --- | --- |
| `query` | The submitted question after surrounding whitespace is removed. |
| `detailed` | The answer mode used for this request. |
| `answer.text` | Generated answer. Markers such as `[1]` refer to citations. |
| `answer.citations` | Sources cited by the answer, in marker order. |
| `answer.citations[].id` | Supporting chunk ID. |
| `answer.citations[].title` | Source article title. |
| `answer.citations[].url` | Source article URL. |
| `answer.citations[].published` | Source publication time. |
| `answer.citations[].supporting_text` | Source excerpt supporting the answer. |
| `answer.insufficient_evidence` | `true` when the available news does not support an answer. |
| `total_results` | Number of unique supporting chunks returned. |
| `results` | Supporting News Search results. Cited chunks come first, followed by uncited results. |
| `credits_used` | Credits charged for a subscription request. |
| `requests_left` | Remaining subscription credit balance. |
| `cost` | Amount charged for a PAYG request. |
| `balance` | PAYG balance after the charge. |

Citation `[n]` corresponds to `answer.citations[n - 1]` and `results[n - 1]`. Each citation's `id` matches the corresponding `results[].chunk.chunk_id`.

The objects in `results` use the same article, chunk, and metadata fields documented in [News Search Response Format](news-search-api-response-format).