---
title: "Bot protection"
description: "Let your AI agent add free Edge Shield bot protection to the forms and pages it deploys: create a widget, inject the embed and wire up server-side verification."
url: "https://edge.network/docs/agent/shield"
section: "Agent tooling"
---

# Bot protection

"Add bot protection to my contact form" is one API call. Your agent creates an Edge Shield widget, injects the two-line embed snippet into the page it's deploying, and wires up server-side verification, all without leaving the Agent API.

## Why use Shield through the Agent API

- **Free, forever:** Unlimited widgets and verifications. Shield never counts against an agent's budget cap.
- **Ready-to-paste embed:** The create response includes the exact script tag, widget div and siteverify contract, so the agent doesn't need to look anything up in the docs.
- **Agent-aware:** Set an `agent_policy` to allow, challenge or block cryptographically verified AI agents (Web Bot Auth) on the protected page.
- **Stats built in:** Agents can report solve rates, humanity scores and blocked replays back to the user on request.

## API endpoints

```text
GET    /agent/shield/widgets             # List widgets
POST   /agent/shield/widgets             # Create a widget (returns secret + embed snippet)
PATCH  /agent/shield/widgets/{id}        # Update name, hostnames, mode, agent_policy
DELETE /agent/shield/widgets/{id}        # Revoke a widget
GET    /agent/shield/widgets/{id}/stats  # Hourly traffic stats (?hours=24, max 720)
```

Requires an agent access code with the `shield` product. Creating, updating and revoking widgets require the `manage` permission. All write endpoints support `X-Dry-Run: true`.

## Creating a widget

```http
POST /agent/shield/widgets
Authorization: Bearer ea_live_...

{
  "name": "Contact form",
  "hostnames": ["portfolio.example.com"],
  "mode": "managed",
  "agent_policy": "allow"
}

# Response:
{
  "widget": {
    "id": "wgt-abc123",
    "name": "Contact form",
    "sitekey": "es_6206c6fdb43e7a3cb948507e6f3e5a11",
    "mode": "managed",
    "agentPolicy": "allow",
    "hostnames": ["portfolio.example.com"]
  },
  "secret": "ss_4f8e2a1b9c7d6e5f4a3b2c1d0e9f8a7b",
  "embed": {
    "script": "<script src=\"https://shield.edge.network/api.js\" defer></script>",
    "widget": "<div class=\"edge-shield\" data-sitekey=\"es_6206...\"></div>",
    "verify": {
      "endpoint": "https://shield.edge.network/siteverify",
      "method": "POST",
      "body": { "secret": "<widget secret>", "response": "<edge-shield-response form field>" }
    }
  },
  "tell_user": "Shield widget \"Contact form\" created. IMPORTANT: the secret is
    shown only once. Store it as a server-side environment variable now..."
}
```

> [!WARNING]
> **The secret is returned only on creation.** A well-behaved agent stores it as a server-side environment variable (never in client code or the repository) and tells the user where it was put. If the secret is lost, revoke the widget and create a new one.

## Typical agent workflow

1. **Create the widget:** scoped to the site's hostname, in `managed` mode unless the user asks otherwise.
2. **Inject the embed snippet:** the script tag in the page head, the widget div inside the form being protected.
3. **Wire up verification:** the form handler posts the `edge-shield-response` field to `/siteverify` with the secret, and rejects submissions that fail.
4. **Redeploy and report back:** including where the secret is stored.

## Checking traffic

```http
GET /agent/shield/widgets/wgt-abc123/stats?hours=168
Authorization: Bearer ea_live_...

# Response:
{
  "totals": {
    "hours": 168,
    "challenges_issued": 14382,
    "challenges_solved": 9041,
    "solve_rate_pct": 62.9,
    "verify_success": 1204,
    "verify_replay": 17,
    "verified_agents": 93
  },
  "stats": [ /* hourly rows */ ],
  "anomaly": null,
  "tell_user": "Last 168h: 14382 challenges issued, 62.9% solved,
    1204 verified submissions, 17 replayed tokens blocked."
}
```

If a drift anomaly is flagged on the widget, the response includes an `anomaly` object and the `tell_user` summary mentions it.

## See also

- [Server-side validation](/docs/shield/siteverify): The siteverify contract in full
- [Discovery endpoint](/docs/agent/discovery): The agent's entry point