HTTP request evidence

Epode accepts a deliberately narrow evidence layer for candidate AI-related HTTP requests. It is for aggregate traffic measurement from infrastructure your company controls. It is not an access-log upload and it is not an identity, citation, or outcome contract.

Privacy boundary

POST /api/v1/evidence/http-requests/batches accepts only:

an HMAC-before-storage source ID and event ID;
observation time, GET or HEAD, and response status;
one exact allowlisted bot product token, one allowlisted assistant referrer host, or both; and
an optional source-reported network verification method.

The schema has no fields for an IP address, raw user agent, path, URL, query, headers, cookies, request or response body, byte content, customer, session, interaction, AEO run, conversion, revenue, or outcome. Unknown fields are rejected. Source and event IDs must be non-personal opaque tokens and are never stored in plaintext.

curl https://app.tryintents.com/api/v1/evidence/http-requests/batches \
  -H "Authorization: Bearer $EPODE_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "schemaVersion": 1,
    "source": {
      "kind": "cdn_log",
      "provider": "cloudflare",
      "sourceId": "production_edge"
    },
    "events": [{
      "eventId": "ray_0123456789abcdef",
      "observedAt": "2026-08-10T12:00:00Z",
      "method": "GET",
      "responseStatus": 200,
      "agentToken": "OAI-SearchBot",
      "networkEvidence": { "method": "cloudflare_verified_bot" },
      "referrerHost": null
    }]
  }'

The endpoint is idempotent per environment, source, and source event. A batch returns accepted, duplicates, and expired. Events older than the environment retention window are counted as expired and are not stored.

Classification and provenance

The accepted product tokens are versioned with schemaVersion: 1:

Provider	Crawling	Search	User-triggered fetch	Other crawl
OpenAI	`GPTBot`	`OAI-SearchBot`	`ChatGPT-User`	—
Anthropic	`ClaudeBot`	`Claude-SearchBot`	`Claude-User`	—
Perplexity	—	`PerplexityBot`	`Perplexity-User`	—
Google	—	`Googlebot`	`Google-Agent`, `Google-GeminiNotebook`, `Google-NotebookLM`	`GoogleOther`, `Google-CloudVertexBot`
Microsoft	—	`bingbot`	—	—

These are exact user-agent product tokens, not full raw user-agent strings. Google-Extended is intentionally absent because Google documents it as a robots control token, not an HTTP user agent. Bing publishes no separate Copilot crawler token; bingbot is therefore never relabeled as a Copilot visit. Unrecognized tokens fail closed until a reviewed contract and database allowlist update adds them; additive token coverage does not change the event shape identified by schemaVersion: 1. Google-Agent is Google’s generic user-triggered agent, not proof that Gemini initiated the request. Google-GeminiNotebook is the current user-triggered fetcher for URLs supplied to Gemini Notebook; Google-NotebookLM remains a separate accepted transitional token through Google’s documented August 2026 compatibility window. To elevate any of the three from claimed to source_attested under schema version 1, verify Google’s user-triggered-agent ranges or use forward-confirmed reverse DNS. Google also documents Web Bot Auth for Google-Agent, but that verification method is not yet representable in networkEvidence. A fetch proves only that the company-controlled source observed the bounded request and response metadata. It does not prove indexing, training inclusion, ranking, grounding, citation, impression, consumption, or authorization. user_fetch does not identify an end user, prompt, model, or conversation. Actor evidence has only two tiers:

claimed: an exact product token was reported by the authenticated importer. User-agent tokens are spoofable.
source_attested: the importer also reported cloudflare_verified_bot, published_ip_range, or forward_confirmed_reverse_dns. This preserves the check’s provenance but does not claim that Epode independently authenticated the requester.

For vendor IP checks, combine the exact token with the provider’s current published range. For reverse DNS, forward-confirm the hostname back to the original address. Use the source IP only transiently; do not send it to Epode. Cloudflare bot scores and categories alone are automation or category signals, not provider identity. Referral coverage is an exact payload allowlist:

Referral provider	Exact `referrerHost` values
OpenAI	`chatgpt.com`, `chat.openai.com`
Anthropic	`claude.ai`
Perplexity	`perplexity.ai`, `www.perplexity.ai`
Google	`gemini.google.com`
Microsoft	`copilot.microsoft.com`, `copilot.cloud.microsoft`
xAI	`grok.com`

This endpoint is for an authenticated exporter operating on company-controlled CDN or origin observations. The exporter must extract the hostname before emission and discard the rest of the referrer. The API accepts only one of the exact strings above; it does not accept or normalize full URLs, ports, case variants, suffix matches, or arbitrary subdomains. In particular, x.com, broad Microsoft, Google, or Bing hosts, and lookalike domains are not referral evidence. This allowlist does not expand browser SDK collection, agent telemetry, AEO execution, or sampled-answer coverage. A referrer attributes only the immediately preceding page. It may be absent or spoofed. Accepting one of these hosts does not identify who requested the page, establish that an answer or citation existed, connect the request to an AEO observation, or prove that an answer engine caused a later outcome.

Aggregate read

Dashboard sessions can read:

GET /api/products/{productId}/evidence/http-requests/summary
    ?environmentId={environmentId}&days=30

The response contains counts by actor provider, fetch class, evidence tier, referral provider, source, and network evidence method. It returns no row-level source or event identifier. The requested window is capped by the environment’s retention period. Crawler, user-triggered fetch, and referral evidence remain separate dimensions. The storage table has no customer, session, interaction, AEO-run, or outcome key. Do not join records by timing, user agent, or IP to infer a person or a causal journey. Outcomes require a separate consent-aware first-party event and an explicit correlation contract.

First-party references

OpenAI crawler overview and its published IP lists for GPTBot, OAI-SearchBot, and ChatGPT-User
Anthropic crawler distinctions and Anthropic bot IPs
Perplexity crawler distinctions and its separate IP lists for PerplexityBot and Perplexity-User
Google common crawlers, user-triggered fetchers, and request verification
Microsoft crawler list and Bingbot verification
Cloudflare AI bot reference, Bot Management variables, and http_requests Logpush fields

Rollout and rollback

Apply migrations 0047 and 0048 before deploying the API image that accepts the expanded host and Google agent-token values, and before exporters begin emitting them. Start with one company-controlled exporter and compare accepted, duplicate, and expired counts against its aggregate source totals. Configure that exporter with the same exact allowlists; do not enable a source that can only provide a raw log export. Migration 0047 replaces only the two validated referral allowlist checks. Migration 0048 similarly replaces only the validated agent-token allowlist check. Neither changes columns nor rewrites rows. The immediately previous API image can continue to write its original values and read string-valued aggregates after the expansions, but it cannot ingest the new enum values. Roll back by first stopping emission of the new values and then reverting the API image. Leave the expanded checks in place for a forward fix; never rewrite an applied migration.

​Privacy boundary

​Classification and provenance

​Aggregate read

​First-party references

​Rollout and rollback

Privacy boundary

Classification and provenance

Aggregate read

First-party references

Rollout and rollback