# Website Antibot

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/website/antibot` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 1 credit per call |
| **Documentation** | https://www.piloterr.com/library/website-antibot |

## Description

Detect which anti-bot protection protects a website before you scrape. Get the vendor, confidence level, and matching clues from a single URL check.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/website/antibot' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Cloudflare on crunchbase.com

```json
{
  "status": 200,
  "vendor": "cloudflare",
  "final_url": "https://www.crunchbase.com/",
  "confidence": "high",
  "detections": [
    {
      "vendor": "cloudflare",
      "evidence": [
        "Header cf-ray: a1da70864ed39e6f-CDG",
        "Header cf-cache-status: HIT",
        "Header server: cloudflare",
        "Cookie __cf_bm present (Bot Management)"
      ],
      "confidence": "high"
    }
  ],
  "requested_url": "https://www.crunchbase.com/"
}
```

### DataDome on allegro.pl (403 challenge)

```json
{
  "status": 403,
  "vendor": "datadome",
  "final_url": "https://allegro.pl/",
  "confidence": "high",
  "detections": [
    {
      "vendor": "datadome",
      "evidence": [
        "Cookie datadome present",
        "Header x-datadome-cid: AHrlqAAAAAMAbMO5pDBn7PQAJac65Q==",
        "Body marker: geo.captcha-delivery.com",
        "Body marker: captcha-delivery.com"
      ],
      "confidence": "high"
    }
  ],
  "requested_url": "https://allegro.pl"
}
```

### Akamai + PerimeterX on walmart.com

```json
{
  "status": 200,
  "vendor": "akamai",
  "final_url": "https://www.walmart.com/",
  "confidence": "high",
  "detections": [
    {
      "vendor": "akamai",
      "evidence": [
        "Header x-akamai-transformed: 0 - 0 -",
        "Cookie ak_bmsc present",
        "Cookie bm_mi present"
      ],
      "confidence": "high"
    },
    {
      "vendor": "perimeterx",
      "evidence": [
        "Body marker: window._pxAppId"
      ],
      "confidence": "high"
    }
  ],
  "requested_url": "https://www.walmart.com"
}
```

### No protection detected

```json
{
  "status": 200,
  "vendor": "none",
  "final_url": "https://example.org/",
  "confidence": null,
  "detections": [],
  "requested_url": "https://example.org"
}
```

## Documentation

## Overview
Before scraping a website, it helps to know **what kind of bot protection** stands in your way. The Website Antibot API answers that question: send a URL and get back the protection vendor Piloterr recognizes (Cloudflare, DataDome, Akamai, a captcha, and more).

Piloterr loads the page once, like a normal browser visit, and looks at the response: HTTP headers, cookies, and page content. It reports what it finds, how sure it is, and the clues that matched.

**This is detection only.** It does not solve captchas, bypass WAFs, or scrape protected pages. Use it to decide your next step: Website Crawler, Rendering, or WebUnlocker.

Costs **1 credit** per call.

## When to use it
- You tried to crawl a site and got blocked: find out **who** is blocking you.
- You are building a pipeline and want a quick pre-check before picking an endpoint.
- You monitor competitors or prospects and want to know if they added bot protection.
- You need a simple answer for a client or teammate: "This site runs on Cloudflare Bot Management."

## Quickstart
```
GET https://api.piloterr.com/v2/website/antibot?query=https://www.example.com&timeout=15
```

## Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `query` | string | yes | - | Full URL or domain name to analyze |
| `timeout` | integer | no | `15` | How long to wait for the site to respond (seconds) |

## Response example
```json
{
  "requested_url": "https://www.example.com",
  "final_url": "https://www.example.com/",
  "status": 200,
  "vendor": "cloudflare",
  "confidence": "high",
  "detections": [
    {
      "vendor": "cloudflare",
      "confidence": "high",
      "evidence": [
        "Header cf-ray: abc123-LHR",
        "Cookie __cf_bm present (Bot Management)"
      ]
    }
  ]
}
```

When nothing is detected:
```json
{
  "requested_url": "https://example.org",
  "final_url": "https://example.org/",
  "status": 200,
  "vendor": "none",
  "confidence": null,
  "detections": []
}
```

## Understanding the response
| Field | Type | What it means |
|---|---|---|
| `requested_url` | string | The URL you sent |
| `final_url` | string | Where you landed after redirects |
| `status` | integer | HTTP status code from the target (200, 403, 503, …) |
| `vendor` | string | **Main** protection detected. Shortcut for the best match in `detections`. Use `none` when nothing matched. |
| `confidence` | string or null | Confidence for the main `vendor`. `high`, `medium`, or `low`. `null` when `vendor` is `none`. |
| `detections` | array | All matches found, best match first. Can contain **several vendors** on the same site (for example Cloudflare + reCAPTCHA). |

Each item in `detections`:
| Field | Type | What it means |
|---|---|---|
| `vendor` | string | Protection identified (`cloudflare`, `datadome`, `recaptcha`, …) |
| `confidence` | string | Confidence for this specific match |
| `evidence` | string[] | Human-readable clues: headers, cookies, or page markers that triggered the match |

**How to read it:** start with root `vendor` + `confidence` for a quick answer. Open `detections` when you need the full picture or when several protections overlap.

## Detected protections
| What you may see on the site | `vendor` value |
|---|---|
| Cloudflare (WAF, Bot Management, "Just a moment" page) | `cloudflare` |
| Cloudflare Turnstile | `cloudflare` |
| Akamai Bot Manager | `akamai` |
| DataDome | `datadome` |
| PerimeterX / HUMAN | `perimeterx` |
| Imperva / Incapsula | `imperva` |
| Kasada | `kasada` |
| AWS WAF | `awswaf` |
| Google reCAPTCHA | `recaptcha` |
| hCaptcha | `hcaptcha` |

## Good to know
- A **challenge page** (403, 503, "Checking your browser") is still a successful analysis. That page is often exactly the signal you were looking for.
- **`none` is not a guarantee.** Some protections only show up after JavaScript runs in a real browser.

## What to do next on Piloterr
| Result | Typical next step |
|---|---|
| `none` or light protection | Try [Website Crawler](https://docs.piloterr.com/website-crawler) |
| JavaScript-heavy site | Try [Website Rendering](https://docs.piloterr.com/website-rendering) |
| Strong bot manager (Cloudflare, DataDome, Akamai, …) | Check if the domain is whitelisted, then try [Website WebUnlocker](https://docs.piloterr.com/website-webunlocker) |

## Error codes
| Code | Cause |
|---|---|
| `400` | Missing or invalid URL |
| `500` | Site unreachable (timeout, DNS, connection error) |

## Limitations
- **Passive check:** one HTTP request, no JavaScript execution on the page.
- Captcha widgets or sensor scripts injected at runtime may not appear in the raw HTML.
- For research and planning only, not for bypassing protections.