Skip to main content
Whether you’re evaluating Bluesky for the first time or troubleshooting a specific behaviour, the questions below cover the most common things customers ask. If you’re just getting started, the Edge Network overview walks through the full install.
Work through these in order:
  1. Is AEN_EDGE_TOKEN set as a Vercel environment variable? A local .env file is not enough. If the token is blank, the middleware returns NextResponse.next() on the very first line and does nothing — no detection, no telemetry.
  2. Is the middleware actually deployed? Confirm middleware.ts is at the root of your Next.js app and shows up as an Edge Function in your Vercel project’s Functions tab.
  3. Did you trigger a real browsing AI? Visiting your own site in a browser won’t generate a hit. You need to ask ChatGPT or Perplexity (with browsing enabled) a question that causes their crawler to fetch a URL on your domain.
Note on verification: the drop-in middleware records telemetry for any matched answer-engine agent, but only verified hits are ever served the optimized variant. A bot that matches by user-agent string alone — but whose source IP isn’t inside the vendor’s published CIDR ranges — is classified as UA_ONLY and is always passed through to your normal page.
In the drop-in middleware, every one of these must be true before the variant is served:
  1. The bot must be verified. The middleware verifies the request’s source IP against the vendor’s published CIDR ranges (IP_VERIFIED). A UA_ONLY match is never served the variant.
  2. The bot’s purpose class must be USER_TRIGGERED or RETRIEVAL. Other purpose classes pass through, even when the bot is verified.
  3. SERVE_MODE must be "default". The middleware ships in "shadow", which logs requests but always serves your normal page. Change the constant in middleware.ts to "default" and redeploy.
  4. An artifact must exist for the URL. If Bluesky hasn’t generated one yet, the middleware degrades to your normal page — it never fabricates a response.
Separately, classic search bots (Googlebot / Bingbot / Applebot) are always passed through by the cloaking firewall, no matter what — see the SEO question below.
Yes — and this is enforced in code, not left to configuration. The serve rule contains an explicit cloaking firewall: if an incoming bot is flagged isSearchIndex in the Bluesky botset, the middleware immediately returns your normal page without branching. Googlebot, Bingbot, and Applebot always get your normal page, full stop. The control plane also strips SEARCH_INDEX from a site’s enabled purposes defensively, so it can never be turned on.This matters especially because Google’s AI Overviews run on Googlebot and the same search index as Google Search. Serving Googlebot a different version would be cloaking Google Search itself — a clear policy violation. Bluesky never does this.For the non-search answer-engine agents that Bluesky does serve (such as OAI-SearchBot, Claude-SearchBot, and PerplexityBot), the artifact is a pure extraction-and-restructure of your existing page — the same substance, reformatted into answer-first markdown and JSON-LD. A strict-parity grounding guardrail rejects any artifact that introduces content the source page didn’t contain, so nothing is added or invented.See the cloaking firewall guide for the full rule.
The shipped drop-in today is a Next.js edge middleware that runs on the Vercel Edge runtime. If your stack is different, a Cloudflare Worker adapter and a zero-code CNAME reverse-proxy option are in development. Reach out via in-app chat to discuss your stack or ask about early access.
The edge token (AEN_EDGE_TOKEN) is a separate, site-scoped credential, distinct from your Bluesky account credentials. It has the format aen_..., is scoped to exactly one domain, and can be rotated at any time — re-provisioning the site mints a fresh token without affecting the rest of your account.Its job is to authenticate the middleware’s calls to the Bluesky control plane (Authorization: Bearer <edgeToken>): fetching the botset, fetching artifacts, and posting telemetry hits. Because it’s site-scoped and revocable, the blast radius of a leaked token is limited to that one site’s edge configuration.The token is returned in full only once, at provision time, so copy it straight into Vercel’s environment variable store rather than committing it to your repository. If you lose it, re-provision the site to mint a new one.
Shadow mode (SERVE_MODE = "shadow") is the default in the downloadable middleware.ts. In this mode the middleware runs the full detection and verification pipeline on every request and logs what it would have served, but always delivers your normal page to every visitor — human or bot.Starting in shadow mode lets you confirm that:
  • The middleware is deployed and receiving requests.
  • AEN_EDGE_TOKEN is set and the control plane is reachable.
  • Verified AI crawler hits are appearing in Agent Analytics.
  • The artifacts Bluesky has generated look right — the Agent Analytics artifacts list shows each optimized page with its status and citability score.
Once you’re satisfied, flip the constant to "default" and redeploy to start serving the variant. The middleware.ts constant only accepts "shadow" or "default"; richer serve modes such as canary rollouts are configured from the Bluesky platform (off / shadow / canary:<pct> / default).
Bluesky maintains a botset — a list of known AI agents with their user-agent tokens, published IP CIDR ranges, and a purpose classification. The middleware fetches it from the control plane and caches it on the edge for up to one hour.Tracked agents include:
  • OpenAI: ChatGPT-User (USER_TRIGGERED), OAI-SearchBot (RETRIEVAL), GPTBot (TRAINING)
  • Anthropic: Claude-User (USER_TRIGGERED), Claude-SearchBot (RETRIEVAL), ClaudeBot (TRAINING)
  • Perplexity: Perplexity-User (USER_TRIGGERED), PerplexityBot (RETRIEVAL)
  • Mistral: MistralAI-User (USER_TRIGGERED)
  • Classic search (firewall-protected, never served): Googlebot, Bingbot, Applebot
Detection matches the request’s user-agent token against the botset, then verifies the source IP against the vendor’s published CIDR ranges. A match on user-agent alone yields UA_ONLY, which is never served the variant; IP confirmation yields IP_VERIFIED. The core also defines a higher SIGNED tier backed by Web Bot Auth (RFC 9421 HTTP Message Signatures, Ed25519); the shipped drop-in verifies by IP range.Bluesky maintains the botset centrally, so you don’t need to track vendor crawler tokens or IP ranges yourself.
Every bot in the botset carries a purpose class describing why it’s crawling:
  • USER_TRIGGERED — A human is actively waiting. When a ChatGPT user asks a question with browsing enabled, ChatGPT-User fetches your page in real time to inform the answer.
  • RETRIEVAL — The crawler is building or refreshing an index for future queries. OAI-SearchBot and PerplexityBot fall here.
Both classes are enabled for variant serving by default. Other classes are not served:
  • TRAINING crawlers (e.g. GPTBot, ClaudeBot, CCBot) pass through to your normal page.
  • SEARCH_INDEX bots (Googlebot / Bingbot / Applebot) always pass through via the cloaking firewall.
You control which purposes are eligible per site (SEARCH_INDEX can never be enabled).
No — for human visitors there is no perceptible latency. The overwhelming majority of your traffic is human, and if no bot user-agent is matched the middleware calls NextResponse.next() and steps aside immediately.For a verified AI crawler request the middleware does a little extra work: it fetches the pre-generated artifact from the control plane. This is completely separate from any human session. The botset is cached on the edge for up to one hour, so that lookup does not hit the control plane on every request.
Bluesky never puts an LLM call on the request path. Artifacts are generated offline — pure extraction-and-restructure of your existing page — and cached, so serving one is just a fetch, never a model round-trip.
Artifacts are built from a snapshot of your page content, so editing your page does not automatically rebuild them.To refresh one:
  1. Open Agent Analytics in the Bluesky app.
  2. Find the page you’ve edited.
  3. Use the Regenerate action, which flags the artifact stale so the engine rebuilds it from your page’s current content.
Because the drop-in middleware fetches artifacts per request from the control plane (it keeps no local edge cache), the rebuilt version is served to the next qualifying crawler with no redeploy on your side. While a page is queued for regeneration its status shows as stale and the edge passes crawlers through to your normal page until the engine rebuilds it back to fresh — you can watch that status flip (and the updated citability score) in the artifacts list. See the Agent Analytics guide for the served → cited loop.