> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trybluesky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Edge Network: Architecture and Request Flow

> How the Bluesky Agent Edge Network detects verified AI crawlers at the edge, serves pre-generated answer-optimized content, and reports every hit as analytics.

The Bluesky Agent Edge Network (AEN) is a self-contained edge drop-in you install in your own app. Each drop-in — a Next.js `middleware.ts`, a Cloudflare Worker, a WordPress plugin, or a snippet for any other stack — is zero-dependency, runs in your request path, identifies verified AI crawlers, serves them pre-generated answer-optimized content, and reports every hit back to Bluesky.

<Note>
  Every drop-in runs **inside your own stack**, not as a reverse proxy — Bluesky stays out of your traffic path. A zero-code CNAME reverse-proxy (Bluesky-hosted) is on the roadmap, not shipped. See [Supported platforms](#supported-platforms).
</Note>

## What the AEN does

On each request, the middleware runs these steps in order:

<Steps>
  <Step title="Detect">
    The middleware fetches a verified bot registry (`botset`) from the Bluesky control plane, caches it in-process for one hour, and matches the incoming `User-Agent` token against it. If there is no match, the normal page is served.
  </Step>

  <Step title="Protect your search ranking">
    Before anything else, classic search-index bots — Googlebot, Bingbot, and Applebot (`isSearchIndex`) — are **never** served the variant. They always receive your normal page. See [Cloaking Firewall](/guides/cloaking-firewall) for why branching them would cloak Search itself.
  </Step>

  <Step title="Verify">
    For a matched non-search bot, the middleware verifies the source IP against the vendor's published CIDR ranges. A verified IP is `IP_VERIFIED`; an unverified token match is `UA_ONLY` and is treated as unverified. Only verified crawlers whose purpose class is enabled are eligible to be served.
  </Step>

  <Step title="Serve (or pass through)">
    If the request is eligible and the site is in `default` serve mode, the middleware fetches the pre-generated artifact for that URL and returns its `markdown` field as the response body (`Content-Type: text/markdown`). If no artifact exists, or the bot is not eligible, the normal page is served instead.
  </Step>

  <Step title="Report telemetry">
    A fire-and-forget hit is posted to the control plane with the bot name, path, status, user-agent, IP, trust level, purpose class, and what was served. It is called with `.catch(() => {})`, so it never blocks or errors the response. This powers **Agent Analytics**.
  </Step>
</Steps>

<Note>
  There is no LLM call on the request path. Artifacts are generated offline and cached ahead of time. In this drop-in v0 the artifact is fetched from the control plane per served request; a productized edge caches it.
</Note>

## Detection trust tiers

Detection assigns an ascending trust level. The core library defines four tiers:

| Tier           | How it is established                                  | In v0 drop-in |
| -------------- | ------------------------------------------------------ | ------------- |
| `SIGNED`       | Web Bot Auth signature verified (RFC 9421 / Ed25519)   | Not verified  |
| `IP_VERIFIED`  | Source IP inside the vendor's published CIDR ranges    | Yes (IPv4)    |
| `DNS_VERIFIED` | Reverse-DNS confirmation, resolved engine-side / async | Not on path   |
| `UA_ONLY`      | User-Agent token matched but nothing verified          | Unverified    |

Only `SIGNED` and `IP_VERIFIED` are treated as verified and can be served the variant. The shipped middleware verifies by IPv4 CIDR only; `SIGNED` and `DNS_VERIFIED` exist in the core but are not performed by the drop-in.

<Warning>
  A User-Agent alone proves nothing — it is trivially spoofed. An unverified token match tops out at `UA_ONLY` and always receives the normal page.
</Warning>

## Request flow at a glance

```
Incoming request
      │
      ▼
┌─────────────────────┐
│  Fetch bot registry │  ← GET /api/v1/edge/botset (cached 1 h)
│  Match User-Agent   │
└────────┬────────────┘
         │ no match?
         ├──────────────────────────────▶ NextResponse.next() (passthrough)
         │
         │ isSearchIndex? (Googlebot/Bingbot/Applebot)
         ├──────────────────────────────▶ NextResponse.next() (cloaking firewall)
         │
         ▼
┌─────────────────────┐
│  Verify source IP   │  against vendor CIDR list
│  Check purpose      │  USER_TRIGGERED | RETRIEVAL
└────────┬────────────┘
         │ verified + purpose enabled + SERVE_MODE = "default"?
         ├──────────────────────────────▶ GET /api/v1/edge/artifact?u=<sha256(url)>
         │                                serve markdown if found, else passthrough
         │
         ▼
┌─────────────────────┐
│  Fire telemetry     │  ← POST /api/v1/edge/telemetry (non-blocking)
└─────────────────────┘
```

## Control-plane endpoints

The AEN talks to four `/api/v1/edge/` endpoints. Every call carries an `Authorization: Bearer <edgeToken>` header. The shipped drop-in v0 calls three of them (`botset`, `artifact`, `telemetry`) and hardcodes its serve config; fuller adapters additionally poll `config`.

<CardGroup cols={2}>
  <Card title="Bot registry" icon="robot">
    **`GET /api/v1/edge/botset`**

    Returns the verified bots with UA tokens, CIDR ranges, purpose classes, and the `isSearchIndex` flag. Cached in-process for one hour.
  </Card>

  <Card title="Artifact fetch" icon="file-lines">
    **`GET /api/v1/edge/artifact?u=<sha256>`**

    Returns the pre-generated artifact for a URL, addressed by the SHA-256 hash of its full URL. The response carries the artifact's `markdown`, `jsonLd`, and `cleanHtml` fields; the drop-in serves the `markdown` field.
  </Card>

  <Card title="Telemetry" icon="chart-bar">
    **`POST /api/v1/edge/telemetry`**

    Accepts a `{ hits: [...] }` array. Non-blocking. Powers Agent Analytics.
  </Card>

  <Card title="Config" icon="sliders">
    **`GET /api/v1/edge/config`**

    Per-site serve config: `serveMode`, `enabledPurposes`, `pathAllow`, `pathDeny`. Polled by productized adapters on a TTL; the v0 drop-in hardcodes these instead.
  </Card>
</CardGroup>

All endpoints live under:

```
https://app.trybluesky.com/api/v1/edge/
```

## Authentication

Every control-plane call uses an **edge token** — a per-site secret, scoped to a single domain and revocable independently of your account API key.

```
Authorization: Bearer aen_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

<Warning>
  The edge token is **not** your account API key. It is scoped to one site and can be revoked without affecting your account or other sites. Store it as the `AEN_EDGE_TOKEN` environment variable — never commit it to source control.
</Warning>

You provision a domain in **Agent Analytics** to mint its edge token, then set it as `AEN_EDGE_TOKEN` in your host's environment (for example, in Vercel project settings). See the [Quickstart](/quickstart).

## Supported platforms

<Tabs>
  <Tab title="Available now">
    * **Next.js / Vercel** — a self-contained `middleware.ts` or the `@trybluesky/aen` package. See the [Next.js Middleware guide](/guides/nextjs-middleware).
    * **Cloudflare** — a drop-in [Worker](/guides/cloudflare-worker) that runs on your own zone.
    * **WordPress / PHP** — a [plugin](/guides/wordpress) you upload and activate.
    * **Any other stack** — Node, PHP, Ruby, nginx or Apache via the [custom integration](/guides/custom-integration) snippets.

    All of them are the same \~40 lines of logic, verified by published IP ranges, zero dependencies.
  </Tab>

  <Tab title="Roadmap">
    A **zero-code CNAME reverse-proxy** (Bluesky-hosted edge, no code on your side) is planned. It is not yet shipped.
  </Tab>
</Tabs>

## Serve modes

The full serve-mode vocabulary is `off`, `shadow`, `canary:<pct>`, and `default`. Sites start in `shadow` so you can validate detection before serving anything to real crawlers. The shipped v0 drop-in supports `shadow` and `default`; the control plane understands all four.

| Mode           | Behavior                                                                      |
| -------------- | ----------------------------------------------------------------------------- |
| `off`          | Never serve the variant.                                                      |
| `shadow`       | Serve the human page to everyone, but log what it **would** have served.      |
| `canary:<pct>` | Serve a deterministic percentage of eligible requests; the rest pass through. |
| `default`      | Serve the artifact to all eligible verified answer-engine agents.             |

Once you see verified hits in Agent Analytics, promote the serve mode from `shadow` toward `default`. See [Serve modes](/guides/serve-modes) for the full progression.