---
title: "Shield API"
description: "Manage Edge Shield widgets and view stats over the Edge REST API."
url: https://edge.network/docs/api/shield/
---

# Shield API

# Shield API

Manage [Edge Shield](https://edge.network/docs/shield) widgets and
view protection stats under `/api/shield`.
Note that token verification itself doesn't happen here — send verification requests to
`shield.edge.network` as described in
[Server-Side Validation](https://edge.network/docs/shield/siteverify).

## Create a Widget

```
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
{
  "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](https://edge.network/docs/shield/widget-modes) |
| agentPolicy | No | `allow`, `challenge`, or `block` — how [verified agents](https://edge.network/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](https://edge.network/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 POSTing to the Shield service directly —
`https://shield.edge.network/siteverify` —
or verify offline with our published JWKS keys. See
[Server-Side Validation](https://edge.network/docs/shield/siteverify) and
[Offline Verification](https://edge.network/docs/shield/offline-verification).

[Back to Docs](https://edge.network/docs) [Need help?](https://edge.network/support)