API#

The REVU API has two sides. Ingest: REVU SDKs capture, batch and send, and the API validates, attributes and stores; every REVU SDK targets one of the ingest endpoints below. Read: your scripts, servers and AI assistants read your organization's insights, through /v1/read with a read key or through the MCP server. See AI assistants (MCP).

EndpointSent byKey
POST /v1/behavior/eventsThe Web SDKPublic write key (revu_pk_...) in the request body
POST /v1/behavior/server-eventsThe Server SDK, or any server over plain HTTPSecret server key (revu_sk_...) in the Authorization header

The production base URL is https://api.revu.ai. Both endpoints are idempotent on the event id, so a retried batch never stores anything twice.

Behavioral events#

POST /v1/behavior/events accepts a batch of 1 to 200 events in the canonical event shape. The public write key resolves to your organization and touchpoint on the server. It is safe to ship in client code: it only grants append access, and a website key accepts events only from its environment's domain and its subdomains (the development key also accepts localhost). When domains overlap, the most specific one decides: with production at acme.com and staging at staging.acme.com, the production key refuses staging.acme.com with a 403 and the staging key accepts it. A subdomain with no domain of its own belongs to its parent, so a preview deploy on preview.acme.com that ships the production key is counted as production until you give it an environment of its own.

  • The canonical event shape - event_id, anonymous_id, user_id, session_id, sequence_no, platform, event_type, screen, fingerprint, properties, device_time.
  • Transport and offline - how the Web SDK batches, retries and flushes against this endpoint.
  • First-party ingest - route events through your own domain with reverse-proxy recipes. The proxy passes the visitor's IP in X-Revu-Client-IP with your secret server key in X-Revu-Proxy-Key, added on your server; without them every visitor reads as the proxy's location and network. The response's X-Revu-Client-IP-Status says whether the IP was used.
  • Privacy. REVU derives country, city and network from the request's IP when an event arrives. The IP itself is kept for 30 days, for crawler verification and troubleshooting, then cleared. The events and the derived fields stay. Each event also keeps the request's user agent, client hint and fetch metadata headers and its origin, which tell a browser from an automated client. The referring page is not kept.

Crawler hits from your server#

POST /v1/behavior/server-events accepts $crawl hits: crawler requests seen by your own web server, including crawlers that never run JavaScript and so never reach the Web SDK. REVU uses them for AI visibility: which crawlers read which pages, and which pages none has read. A hit marked resource: "api" is a read of your API or a data feed: it is counted per crawler apart from page reads, so you can see whether AI assistants use your data without it changing page coverage.

  • A secret key per environment. Create a server key in the REVU app, under Settings > Touchpoints > your website > the environment's tab > Server capture (organization owners and admins). The key is shown once. Keep it on your server: a request from a browser, one that carries an Origin header, is refused.
  • Validated hit by hit. A batch is accepted even when some of its hits are not. The 202 response counts the accepted, duplicate and rejected hits, with the reason for each rejection (invalid, unknown_host, not_crawler).
  • What counts as automated. not_crawler means the user agent is a person's browser. Search crawlers, AI crawlers and fetchers, preview and monitoring bots, and scripted HTTP clients (command-line tools, language runtimes, API clients) all count as automated, so a hit from your own tooling is stored like any other. To keep traffic you do not want measured out of the numbers, drop it before it is sent (see what is reported).
  • Host and environment. A key writes only its own environment: the request host must be that environment's domain or a subdomain, and the development key also accepts localhost. When domains overlap, the most specific one decides, so staging.acme.com is staging once it is set as the staging domain. A subdomain with no domain of its own belongs to its parent: with production set to acme.com and no staging domain, a hit for staging.acme.com or preview.acme.com is accepted by the production key and counted as production. To keep staging and preview crawler hits out of production, set that environment's domain and report them with its key. While an environment is turned off, its keys are refused.
  • Limits. Up to 500 hits and 1 MB per request, and 3,000 requests a minute per key.
  • What counts as crawled. Every valid hit is stored. A page counts as crawled when a crawler got it: a GET answered with 2xx, 304 or an unknown status. robots.txt, llms.txt and sitemap reads are shown as site files, not pages.
  • Verified crawlers. REVU checks each hit's IP with the crawler vendor's own documented method: its published IP ranges, or reverse DNS confirmed by a forward lookup. A hit that uses a crawler's name from an address that crawler does not use is left out of AI visibility. A hit from a CDN edge address (Cloudflare, Fastly or Akamai) is marked unverifiable instead: it still counts, but it is never verified, because that address is your CDN's rather than the crawler's. Report the crawler's own address to get it verified. Crawlers seen through the Web SDK are checked the same way, with the address their request came from.
  • Privacy. A hit carries the host, path, method, status, user agent, the crawler's IP and the referring host, and nothing else. The IP is kept for crawler verification and cleared after 30 days.

The Server SDK (@revu-ai/server) builds these hits, batches them and handles retries and backoff for you.

Events from your server#

Some conversions happen on your server, never in a browser: a subscription through a chat bot, a payment confirmed by a webhook, an account approved by hand. POST /v1/behavior/server-events accepts them as custom events, with the same server key, limits and 202 result as crawler hits. A batch may mix both kinds.

{
  "sent_at": "2026-10-12T09:30:00.000Z",
  "events": [
    {
      "event_type": "tg_subscribe",
      "event_id": "5c2f7e3a-9d41-5b8e-8a1f-3e6d2c9b7a40",
      "timestamp": "2026-10-12T09:29:57.000Z",
      "anonymous_id": "8f14e45f-ceea-467a-9b8e-6c1a2d3e4f50",
      "properties": { "plan": "monthly" }
    }
  ]
}
  • The name is yours. Any event_type without a leading $, up to 120 characters. Names starting with $ are REVU's; an unknown one is rejected as invalid.
  • Who it belongs to. Send the visitor's Web SDK anonymous_id (a UUID), passed through the step that leaves the browser, such as a deep-link parameter; or your user_id for a person who signed in, as the browser's identify() sends it; or both. The event joins the visitor or person REVU already knows. It never creates, links or merges a person: identity comes only from the browser. An event that arrives before its person identifies in the browser joins them when they do.
  • Credited to the visit that led to it. The event is credited to that visitor's latest visit that started up to 7 days before it, so funnels, sources and an ad's cost per conversion count it. It never adds a visit or changes one: visit counts, durations and pages stay the same.
  • Send each conversion once. Retry with the same event_id, so a retried event is stored once. Send a conversion from one side only, the browser or your server, or it counts twice.
  • Timestamps and host. timestamp follows the same rules as crawler hits: up to 7 days old, corrected by sent_at. host is optional; when given it must be the key's environment's domain.
  • Privacy and consent. properties holds up to 16 KB of JSON; keep personal data out of it. REVU cannot see consent on your server, so do not send events for a visitor who declined tracking in the browser.

Reading your insights#

  • AI assistants (MCP) - connect Claude, ChatGPT, Cursor, VS Code or any MCP client to https://mcp.revu.ai/mcp, sign in, and ask.
  • Scripts and servers - GET /v1/read lists the tools a read key (revu_rk_...) can run; POST /v1/read/{tool} runs one. The answers are the same as the MCP server's: insights, each with the scope it covers.

Reference and spec#

  • API reference - every endpoint in full (request body schemas, every field, responses, and copy-paste examples), generated from the OpenAPI specification.
  • openapi.json - the machine-readable OpenAPI 3.1 specification. Point a client generator, a mock server, or an AI agent at it.