> For the complete documentation index, see [llms.txt](https://docs.webz.io/llms.txt). Any docs page is also available as markdown at `https://docs.webz.io/markdown/<environment>/<slug>`.

# Request & Response

## Endpoint

`POST`

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

## Authentication

Use your **main** 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.

Additional (secondary) tokens are not accepted and return `401`. Pay-as-you-go accounts need enough balance for one answer; contract plans need the Dark Web API permission and a Dark Web Answers credit left - see [Errors, Limits & Credits](https://docs.webz.io/docs/webz/dark-web-answers-api-errors-limits).

## Request body

Send a JSON body with `Content-Type: application/json`.

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `query` | string | Yes | — | Your question in plain language. |
| `lookback_days` | integer | No | auto | How far back to search, `1`-`730`. When omitted the search starts at 90 days and widens if too little is found. |

The API infers the searches, sources, time window, and language from `query`. You do not send Dark Web API filters.

```bash
curl -X POST "https://api.webz.io/api/cyber/answers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Which ransomware groups are targeting healthcare organizations, and what tactics are they using?", "lookback_days": 90}'
```

## Unmasked answers

Answers are masked by default. To request the unmasked version, add `?mask=false` to the URL:

```text
https://api.webz.io/api/cyber/answers?mask=false
```

`mask=false` is honored only for accounts with the unmasked-answers permission. Any other account still receives a masked answer, plus an `unmask_denied` field explaining why. Contact sales@webz.io to enable unmasked answers.

## Response

```json
{
  "query": "Which ransomware groups are targeting healthcare organizations, and what tactics are they using?",
  "answer": {
    "text": "Several groups have claimed healthcare victims in the period, most actively ... [S1][S3]. Their posts describe initial access through exposed RDP and phishing ... [S2].",
    "insufficient_evidence": false
  },
  "sources": [
    {
      "id": "S1",
      "uuid": "e2a9c1f0b4d6...",
      "title": "New victim announced",
      "site": "ransomware-blog",
      "site_type": "blogs",
      "network": "tor",
      "language": "english",
      "published": "2026-10-02T14:21:00.000+00:00",
      "crawled": "2026-10-02T14:40:12.000+00:00",
      "authors": ["admin"],
      "risk": 8,
      "relevance": 3,
      "evidence_note": "Names the victim organization and the sector.",
      "supporting_text": "..."
    }
  ],
  "warnings": [],
  "cost": 0.63,
  "balance": 4.37
}
```

### Root fields

| Field | Type | Description |
| --- | --- | --- |
| `query` | string | The question as received. |
| `answer.text` | string | The answer. `[Sn]` markers cite the matching entry in `sources`. |
| `answer.insufficient_evidence` | boolean | `true` when the sources found do not support a confident answer. |
| `sources` | array | The cited posts - see below. |
| `warnings` | array of strings | Notes about the run, for example a widened time window. |
| `unmask_denied` | string | Present only when `mask=false` was requested without the permission. |
| `credits_used` | integer | Contract plans: Dark Web Answers credits charged for this request. |
| `requests_left` | integer | Contract plans: Dark Web Answers credits left this month. |
| `cost` | number | Pay as you go: amount charged for this request, in USD. |
| `balance` | number | Pay as you go: your balance after the charge, in USD. |

Each account receives only its own billing fields: `credits_used` and `requests_left` on contract plans, `cost` and `balance` on pay as you go.

### Source fields

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | `S1`, `S2`... - matches the markers in `answer.text`. |
| `uuid` | string | Post id in the Dark Web API. |
| `parent_uuid` | string | Id of the thread's first post, when the source is a reply. |
| `title` | string | Post or thread title. |
| `site` | string | Site name. |
| `site_type` | string | Site type, as in the Dark Web API `site.type` field. |
| `network` | string | `telegram`, `openweb`, `tor`, `public_chat`, or `discord`. |
| `language` | string | Post language. |
| `published`, `crawled` | string | ISO 8601 timestamps. |
| `authors` | array of strings | Author names. |
| `risk` | integer | Cyber risk score, `1`-`10`. |
| `relevance` | integer | `3` directly supports the answer, `2` partly. |
| `evidence_note` | string | Why this post was cited. |
| `supporting_text` | string | The passage the answer relies on. |
| `url`, `thread_url`, `site_domain` | string | **Unmasked answers only.** Where the post was found. |

## Timeouts

An answer can take up to two minutes. Set your client timeout to at least three minutes; the request is not streamed.

## Related documentation

- [Introduction](https://docs.webz.io/docs/webz/dark-web-answers-api)
- [Errors, Limits & Credits](https://docs.webz.io/docs/webz/dark-web-answers-api-errors-limits)
- [Dark Web API](https://docs.webz.io/docs/webz/dark-web-api-what-is) - the posts the answers are built from.

