Ingest API#

REVU SDKs capture, batch and send. The REVU API validates, attributes and stores. The ingest endpoints are the boundary between the two, and every REVU SDK targets one of them.

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 (the development key also accepts localhost).

• 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.
• 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.

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 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. 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.

Reference and spec#

• API reference - both endpoints 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.