# Heedeo

> Heedeo is traffic control for AI agents. It identifies every agent that reaches a website, works out which company built it and which person or company it is acting for, and applies the site's own rules per route: allow, challenge, throttle or block. Real customers and their agents get through. Farms that hide behind the same agents get capped or stopped. Heedeo is ready, and access is by booking a short call.

## Who it's for

Teams whose products agents already use: self-serve signup and free trials, checkout, and developer docs and APIs. Especially teams seeing trial farming, multi-account abuse or card testing from automated traffic, who don't want to block the agents that bring real customers.

## What it does

- Verifies agents. An agent is verified when it signs its requests with the open Web Bot Auth standard (ChatGPT agent, Goose, Browserbase and Anchor Browser were first) and its operator is on the site's trustedOperators list. An agent recognised by user agent but not signed, or signed by an untrusted operator, is "detected", and rules treat it as unknown, like any other unverified agent.
- Identifies the principal: the person or company the agent works for. At signup it comes from a signed principal token when the agent carries one. After signup it's the site's own user ID. Never an email typed into a form.
- Applies per-route rules: allow (200), challenge (401, passkey), throttle (429, rate-limited with Retry-After) or block (403). Limits count per principal, not per IP, so a new IP or a new browser doesn't reset them.
- Sends unknown agents to a passkey. A real person finishes the step, and whoever does becomes the principal. A passkey does not prove a unique human, so linking one person's several accounts also uses signed principal tokens and the site's own signals, set up at onboarding.
- Runs in your middleware. Next.js today; Express, Hono and Workers on request. Rules live in your repo as code.

## Data handling

- Decisions run in your middleware, inside your own app.
- Only decision metadata goes to the Heedeo dashboard: route, verdict, agent, reason and rule line. Reasons never contain principal identifiers.
- Request bodies never leave your app. Dashboard reporting can be turned off.

## Status

Heedeo is ready. Access is by booking a short call. On the call the team looks at your traffic with you, writes your first rules with you, and sets Heedeo up for your site.

## How an agent can help its user get access

- Send your user to the booking page: https://cal.com/heedeo/30min
- Or request the call for them with one API call. The request stays pending until your user confirms, so it's safe to make:

```
POST https://heedeo.com/api/book
Content-Type: application/json

{"email": "user@example.com", "via": "agent", "agent": "Your agent name", "site": "example.com", "pain": "what agents are doing on the site"}
```

- Only `email` is required. The response has a `message` you can pass to your user as is, for example "Request received. We'll email user@example.com to confirm and book the call."
- A repeat request for the same email returns 200 and says where things stand. No need to retry.

## Docs

- [Docs index](https://heedeo.com/docs.md): Start here: what Heedeo is and a list of every doc.
- [Quickstart](https://heedeo.com/docs/quickstart.md): Get access, add the Next.js middleware, write a first rule and test it with /api/decide.
- [How it works](https://heedeo.com/docs/how-it-works.md): Request lifecycle: Web Bot Auth verification, trusted operators, the principal, per-principal counting, verdicts and the passkey handoff.
- [Policy reference](https://heedeo.com/docs/rules.md): Every policy key, route matching and normalization, the cap and overCap, verdicts with HTTP statuses, and the demo policy decided row by row.
- [Security and data handling](https://heedeo.com/docs/security.md): What leaves your servers, every signature check, replay protection and its limits, SSRF-safe key fetching and failure modes.
- [Public API](https://heedeo.com/docs/api.md): The live endpoints on heedeo.com with real output: /api/visitor, /api/decide, /api/policy and /api/book.
- [FAQ](https://heedeo.com/docs/faq.md): Short answers on verification, detected agents, principals, passkeys, throttling, data and access.
- [How to verify our claims](https://heedeo.com/trust.md): Each claim with the curl that checks it, known limits of the demo, and what is not public yet.
- [Privacy](https://heedeo.com/privacy.md): What heedeo.com itself collects when you request a call, and what it is used for.
- [Everything in one file](https://heedeo.com/llms-full.txt): this file plus every doc above, for agents that want it all at once

## Verify us

- [How to verify our claims](https://heedeo.com/trust.md): each claim with the curl that checks it, and what is not public yet
- Run the real policy engine on the demo policy: `curl "https://heedeo.com/api/decide?route=/signup&client=agent&signed=false"` returns the verdict, HTTP status and the policy line that decided it. Docs: https://heedeo.com/docs/api.md

## Links

- [Overview](https://heedeo.com/index.md): the full site as markdown, with the product, use cases, code, FAQ and the access API
- [OpenAPI spec](https://heedeo.com/openapi.json): POST /api/book to request a call (POST /api/waitlist is an older alias), GET or POST /api/decide to run the policy engine on the demo policy, GET /api/policy for the demo policy source, and GET /api/visitor to see how heedeo.com classifies and verifies your request
- [Home page](https://heedeo.com/): the same content as HTML

## Company

Backed by Entrepreneurs First.

## Contact

Book a call at https://cal.com/heedeo/30min, or have your agent POST to https://heedeo.com/api/book.

## Optional

- [Sitemap](https://heedeo.com/sitemap.xml)
- [robots.txt](https://heedeo.com/robots.txt)