WARD

Documentation

Quick Start

1

Create an account

Register and add your first project (domain).

2

Get your API key

Go to Projects and copy the API key for your site.

3

Send events from your site

In your WARD middleware (or any server-side code), POST bot events to getward.org:

// Fire-and-forget in your middleware
fetch("https://getward.org/api/v1/events", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    botName: "GPTBot",
    botCompany: "OpenAI",
    path: "/impressum",
    ip: request.ip,
    redactedBlocks: 3,
  }),
}).catch(() => {});
4

View your dashboard

Open the Dashboard — filter by site, bot, or date range.

API Reference

POST/api/v1/events

Submit a bot event. Called from your server whenever WARD middleware detects an AI bot.

Headers

AuthorizationBearer YOUR_API_KEY — required
Content-Typeapplication/json

Body

{
  "botName": "GPTBot",        // required — bot user-agent name
  "botCompany": "OpenAI",     // required — company behind the bot
  "path": "/impressum",       // required — requested path
  "ip": "52.1.2.3",           // optional — bot IP address
  "redactedBlocks": 3         // optional — number of redacted blocks (default 0)
}

Response

201 Created
{ "ok": true }

Errors

401Missing or invalid API key
400Missing required fields (botName, botCompany, path)

Integration with ward-protocol

If you use the ward-protocol npm package, add the getward.org reporter to your middleware:

// In your ward-log endpoint or middleware
import { detectBot, redactHtml } from "ward-protocol";

// After detecting and redacting...
if (bot) {
  // Report to getward.org (fire-and-forget)
  fetch("https://getward.org/api/v1/events", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.WARD_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      botName: bot.name,
      botCompany: bot.company,
      path: request.nextUrl.pathname,
      ip: request.headers.get("x-forwarded-for"),
      redactedBlocks: redactionResult.count,
    }),
  }).catch(() => {});
}

The call is fire-and-forget — it won't slow down your middleware even if getward.org is unreachable.