---
title: "Shield API"
description: "Create and manage Edge Shield bot-protection widgets and view protection stats over the Edge REST API. Token verification runs on shield.edge.network."
url: "https://edge.network/docs/api/shield"
section: "REST API"
---

# Shield API

Manage Edge Shield widgets and view protection stats under /api/shield.

All endpoints require [authentication](/docs/api/authentication). Manage [Edge Shield](/docs/shield) widgets here; token verification itself doesn't happen on this API. Send verification requests to `shield.edge.network` as described in [Server-side validation](/docs/shield/siteverify).

## Create a widget

```bash
curl -X POST https://edge.network/api/shield/widgets \
  -H "Authorization: Bearer ek_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing site",
    "hostnames": ["example.com", "www.example.com"],
    "mode": "managed",
    "agentPolicy": "challenge"
  }'
```

Response (`201`). The secret is shown only once:

```json
{
  "widget": {
    "id": "wgt_abc123",
    "name": "Marketing site",
    "sitekey": "sk_...",
    "secretPrefix": "ss_...",
    "hostnames": ["example.com", "www.example.com"],
    "mode": "managed",
    "agentPolicy": "challenge",
    "shadow": false,
    "tarpit": false
  },
  "secret": "ss_live_...",
  "message": "Save the secret now. It will not be shown again."
}
```

| Field | Required | Description |
|---|---|---|
| `name` | Yes | Display name for the widget |
| `hostnames` | No | Hostnames the sitekey may be used on |
| `mode` | No | Widget mode. See [Widget modes](/docs/shield/widget-modes) |
| `agentPolicy` | No | `allow`, `challenge` or `block`: how [verified agents](/docs/shield/verified-agents) are treated |
| `shadow` | No | Shadow mode: score traffic without enforcing |
| `tarpit` | No | Slow down suspected bots instead of failing fast |

## Widget management

| Endpoint | Description |
|---|---|
| `GET /api/shield/widgets` | List widgets |
| `POST /api/shield/widgets` | Create. Returns the widget and its secret (once). |
| `PATCH /api/shield/widgets/:widgetId` | Update any subset of `name`, `hostnames`, `mode`, `agentPolicy`, `shadow`, `tarpit` |
| `DELETE /api/shield/widgets/:widgetId` | Revoke a widget. Its sitekey and secret stop working. |
| `GET /api/shield/widgets/:widgetId/stats?hours=24` | Hourly challenge/verify stats plus anomaly detection (up to 720 hours) |
| `GET \| POST /api/shield/widgets/:widgetId/examine` | Fetch / run the [Shield Examiner](/docs/shield/examiner) AI analysis |

## Verifying tokens

Widget creation gives you a **sitekey** (public, rendered in the browser widget) and a **secret** (server-side). Verify tokens by sending a `POST` to the Shield service directly (`https://shield.edge.network/siteverify`), or verify offline with our published JWKS keys. See [Server-side validation](/docs/shield/siteverify) and [Offline verification](/docs/shield/offline-verification).