REVU API#
Send behavior events, crawler hits and server events, and read your insights with a read key.
REVU SDKs capture, batch and POST. The server validates, attributes and stores. POST /v1/behavior/events takes behavioral events from the Web SDK, authenticated by a public write key (revu_pk_...) in the request body. POST /v1/behavior/server-events takes crawler hits and custom events (conversions that happen on a server) from the customer's own server, authenticated by a secret server key (revu_sk_...) in the Authorization header. Both are idempotent on (organization, event_id), so retried batches are de-duplicated server-side. GET /v1/read and POST /v1/read/{tool} read your organization's insights with a secret read key (revu_rk_...): the same tools AI assistants use through the MCP server at https://mcp.revu.ai/mcp.
This page is generated from the OpenAPI specification. Download it as openapi.json to drive a client generator, a mock server, or an AI agent integration.
Servers#
https://api.revu.ai- Productionhttps://{host}- First-party ingest through your own domain (reverse proxy). See the web SDK first-party-ingest guide.
Authentication#
Each endpoint names the key it takes. There are no cookies and no session.
- Public write key (
revu_pk_...), sent in the request body asapi_key. A tenant identifier safe to embed in client bundles, it grants only append access to one organization's event log. - Secret read key (
revu_rk_prod_...,revu_rk_stg_...orrevu_rk_dev_...), sent asAuthorization: Bearer <key>. It belongs to your organization, reads one environment, and never writes. Organization owners and admins create it in the REVU app's settings (Professional and Enterprise plans). It is shown once. - Secret server key (
revu_sk_prod_...,revu_sk_stg_...orrevu_sk_dev_...), sent asAuthorization: Bearer <key>. Each key belongs to one environment and writes only that environment. Create it in the REVU app under Settings > Touchpoints > your website > the environment's tab > Server capture. It is shown once. Send it from your server only: a request that carries anOriginheader is refused with 403.
POST /v1/behavior/events#
Ingest a batch of behavioral events
Accept a batch of captured events from a REVU SDK. The body carries the public api_key and a batch of 1 to 200 events. Returns 204 with an empty body on success. The SDK sends Content-Type: application/json; on page unload it uses navigator.sendBeacon with an application/json Blob so the terminal batch still parses. When you serve this endpoint from your own domain through a proxy, the proxy passes the visitor's IP in X-Revu-Client-IP with the site's secret server key in X-Revu-Proxy-Key; otherwise every visitor reads as the proxy's location and network. The response's X-Revu-Client-IP-Status says used, or ignored: and why.
Authentication: the public write key in the request body (api_key).
Request body#
Content type: application/json
IngestBody#
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
api_key | string | yes | pattern: ^revu_pk_[A-Za-z0-9_-]{8,120}$ | Public ingest write key (prefix revu_pk_). |
batch | array<BehaviorEvent> | yes | items 1-200 | Up to 200 events per request. |
BehaviorEvent#
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
event_id | string | yes | format: uuid | Client-generated UUID. Unique per organization; the idempotency / dedupe key for retried batches. |
anonymous_id | string | yes | length 1-128 | First-party anonymous visitor (device) id assigned by the SDK. |
user_id | string | null | no | length 0-128 | Identified user id, if any. Null when the visitor is not yet identified. |
session_id | string | yes | length 1-128 | Per-session id. |
sequence_no | integer | yes | min: 0 | Per-page-load monotonic counter starting at 0. Gaps indicate dropped events within a page load. |
platform | enum | yes | one of: web, ios, android | Capture platform. |
event_type | string | yes | length 1-120 | Event type: '$pageview', '$autocapture', or a custom name. |
screen | string | yes | length 0-2048 | Route / path at capture time. |
fingerprint | object | null | no | Element descriptor, present for element interactions ($autocapture, $rightclick, $rageclick, $change). Describes the interactive element the interaction acts on (the link around a tapped icon, say). Used server-side to name the element and group its use. | |
properties | object | yes | Event payload: capture-layer fields (path, url, depth_percent, form structure, ...) plus caller-supplied custom properties. Client-side masked, PII-free, never input values. | |
context | object | no | Engine environment bucket (unprefixed): user_agent, language, timezone, screen_ / viewport_, online, connection_*, environment, sdk_version, consent, gpc, sample_rate, and first/last-touch attribution. Optional: a client that omits it still validates. | |
device_time | string | yes | format: date-time | ISO-8601 capture timestamp from the client device. |
BehaviorEvent.fingerprint#
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
tag | string | yes | Element tag, e.g. 'button'. | |
text | string | null | no | Visible text (truncated; masked if sensitive). | |
role | string | null | no | ARIA role / type. | |
id | string | null | no | Element id, if present. | |
classes | array | null | no | Class list. | |
selector | string | yes | Best-effort CSS selector (fragile; a tiebreaker). | |
ordinal | number | no | Position among siblings. | |
aria_label | string | null | no | The element's accessible name, author-written text (truncated). Names icon-only buttons and form fields; never a field's value. | |
title | string | null | no | The element's title attribute (truncated). | |
interactive | boolean | no | False when nothing interactive encloses the node hit (a tap on a chart, say): a sign of confusion rather than use of a feature. | |
target_part | string | no | The node actually hit (tag and first class, e.g. svg.spark) when it sits inside the element described. |
Example requests#
A curl call (the SDK does this for you, batched and retried):
curl -X POST https://api.revu.ai/v1/behavior/events \
-H "Content-Type: application/json" \
-d '{"api_key":"revu_pk_example12345678","batch":[{"event_id":"f1d2c3b4-a5e6-4789-9abc-de0123456789","anonymous_id":"a0e1d2c3-b4a5-4677-8899-aabbccddeeff","user_id":null,"session_id":"11112222-3333-4444-5555-666677778888","sequence_no":0,"platform":"web","event_type":"$pageview","screen":"/pricing","properties":{"path":"/pricing","url":"https://acme.com/pricing"},"context":{"user_agent":"Mozilla/5.0 ...","language":"en-US","timezone":"Europe/Berlin","environment":"production","sdk_version":"0.1.0"},"device_time":"2026-06-21T18:04:05.123Z"}]}'
A single $pageview event#
{
"api_key": "revu_pk_example12345678",
"batch": [
{
"event_id": "f1d2c3b4-a5e6-4789-9abc-de0123456789",
"anonymous_id": "a0e1d2c3-b4a5-4677-8899-aabbccddeeff",
"user_id": null,
"session_id": "11112222-3333-4444-5555-666677778888",
"sequence_no": 0,
"platform": "web",
"event_type": "$pageview",
"screen": "/pricing",
"properties": {
"path": "/pricing",
"url": "https://acme.com/pricing"
},
"context": {
"user_agent": "Mozilla/5.0 ...",
"language": "en-US",
"timezone": "Europe/Berlin",
"environment": "production",
"sdk_version": "0.1.0"
},
"device_time": "2026-06-21T18:04:05.123Z"
}
]
}
An $autocapture click with an element fingerprint#
{
"api_key": "revu_pk_example12345678",
"batch": [
{
"event_id": "0a1b2c3d-4e5f-4061-8273-8495a6b7c8d9",
"anonymous_id": "a0e1d2c3-b4a5-4677-8899-aabbccddeeff",
"user_id": "user_8675309",
"session_id": "11112222-3333-4444-5555-666677778888",
"sequence_no": 4,
"platform": "web",
"event_type": "$autocapture",
"screen": "/pricing",
"fingerprint": {
"tag": "button",
"text": "Start free trial",
"role": "button",
"selector": "main > section.cta button.primary",
"ordinal": 0
},
"properties": {
"path": "/pricing"
},
"context": {
"environment": "production",
"sdk_version": "0.1.0"
},
"device_time": "2026-06-21T18:04:11.880Z"
}
]
}
Responses#
| Status | Meaning |
|---|---|
204 | Batch accepted. Empty body. Already-seen event_ids in the batch are de-duplicated. |
401 | The api_key is unknown, or its environment is inactive. |
403 | The api_key is valid but the request's Origin is not allowed: it is not in the key's allowed-origins list, or it is not the touchpoint's domain for the key's environment (the development key also accepts localhost). |
422 | The body failed schema validation (a missing or malformed field, or a batch outside 1 to 200 events). |
429 | The api_key's per-minute rate limit is exhausted. Carries a Retry-After header (seconds). SDK transport treats this as a backoff-and-retry signal; events stay queued. |
500 | Unexpected server error. The SDK backs off and retries; events stay queued client-side. |
POST /v1/behavior/server-events#
Report crawler hits and server events from your server
Accept a batch of events from your server only. Each event's event_type says its kind, and a batch may mix kinds. $crawl is a crawler request seen by your web server, including crawlers that never run JavaScript: a page counts as crawled when the crawler got it (a GET answered with 2xx, 304 or an unknown status), and robots.txt, llms.txt and sitemap reads are reported as site files, not pages. A name without a leading $, such as tg_subscribe, is a custom server event: something that happened on your server, such as a subscription through a bot or a payment confirmed by a webhook. It joins the visitor whose browser anonymous_id it carries, or the person who identified with its user_id, and is credited to that visitor's latest visit started up to 7 days before it, so funnels, sources and ad cost per conversion count it. It never adds a visit, and never creates, links or merges a person. Other $ names are reserved and rejected as invalid. Each event is validated on its own, and the 202 response counts what was stored and what was dropped, by reason.
Authentication: a secret server key in the Authorization: Bearer header.
Request body#
Content type: application/json
ServerEventsBody#
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
sdk | object | no | Optional sender identity, for example { "name": "@revu-ai/server", "version": "0.1.0" }. | |
sent_at | string | no | format: date-time | Optional. The sender's clock at send time. Every event's timestamp is corrected by the difference from REVU's clock. |
events | array<object> | yes | items 1-500 | Up to 500 events per request (more answers 413). Each is validated on its own, by its kind. |
ServerEventsBody.sdk#
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
name | string | no | length 0-40 | Sender name. |
version | string | no | length 0-40 | Sender version. |
Example requests#
A curl call (the SDK does this for you, batched and retried):
curl -X POST https://api.revu.ai/v1/behavior/server-events \
-H "Authorization: Bearer revu_sk_..." \
-H "Content-Type: application/json" \
-d '{"sdk":{"name":"@revu-ai/server","version":"0.1.0"},"sent_at":"2026-09-15T12:00:00.000Z","events":[{"event_type":"$crawl","event_id":"0b6d9f0e-6c1d-4a51-9a4e-2b7f1c0d8e11","timestamp":"2026-09-15T11:59:58.120Z","host":"www.acme.com","path":"/pricing","method":"GET","status":200,"user_agent":"Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.1; +https://openai.com/gptbot","ip":"203.0.113.7","referer_host":null}]}'
One GPTBot page fetch#
{
"sdk": {
"name": "@revu-ai/server",
"version": "0.1.0"
},
"sent_at": "2026-09-15T12:00:00.000Z",
"events": [
{
"event_type": "$crawl",
"event_id": "0b6d9f0e-6c1d-4a51-9a4e-2b7f1c0d8e11",
"timestamp": "2026-09-15T11:59:58.120Z",
"host": "www.acme.com",
"path": "/pricing",
"method": "GET",
"status": 200,
"user_agent": "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.1; +https://openai.com/gptbot",
"ip": "203.0.113.7",
"referer_host": null
}
]
}
A subscription confirmed by a bot, for the visitor who came from an ad#
{
"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"
}
}
]
}
Responses#
| Status | Meaning |
|---|---|
202 | Accepted. The body counts the events: accepted + duplicates + rejected always equals the number of events sent. |
401 | The server key is missing, malformed or unknown, a public write key (revu_pk_) was sent instead, or the key's environment is turned off on the touchpoint. Stop sending until the key or the environment is fixed. |
403 | The key was revoked, its touchpoint is archived or is not a website, or the request came from a browser (it carries an Origin header). Stop sending. |
413 | More than 500 events or more than 1 MB in one request. Send smaller batches. |
422 | The envelope failed validation: events is missing, empty or not an array. A malformed single event is not a 422: it is dropped and counted as invalid. |
429 | The key's rate limit (3,000 requests a minute) is exhausted, or this address sent too many unknown keys and is blocked for a minute. Carries a Retry-After header (seconds). Keep the batch and retry after it. |
500 | Unexpected server error. Retry once, then drop the batch. |
The 202 response carries this body:
ServerEventsResult#
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
accepted | integer | yes | min: 0 | New events stored. |
duplicates | integer | yes | min: 0 | Events already stored, or repeated within the batch. |
rejected | object | yes | Dropped events, by reason. |
ServerEventsResult.rejected#
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
invalid | integer | yes | min: 0 | Malformed, more than 7 days old, or a reserved $ name. |
unknown_host | integer | yes | min: 0 | The host is not the key's environment's domain. |
not_crawler | integer | yes | min: 0 | A $crawl hit whose user agent does not classify as a crawler. |
GET /v1/read#
List the tools a read key can run
The tools your organization's products allow, in a fixed order, each with its input and output JSON Schema. Every tool answers with insights and a scope (the period after your plan's history limit, timezone, environment, website or app, traffic). Individual reviews and visits come only from the tools that return them on request, a few per call.
Authentication: a secret server key in the Authorization: Bearer header.
Responses#
| Status | Meaning |
|---|---|
200 | The tools. |
401 | No key, or an unknown, revoked or expired key. |
The 200 response carries this body:
ReadToolList#
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | yes |
ReadToolList.data#
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
tools | array<object> | yes |
The 401 response carries this body:
ReadError#
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
error | string | yes | What went wrong, and what to change. | |
code | string | yes | UNAUTHORIZED, NOT_FOUND, VALIDATION_ERROR, TOOL_ERROR, BLOCKED, QUOTA or RATE_LIMITED. | |
link | string | no | Where in REVU to fix it, when there is a place. | |
details | array<string> | no | For VALIDATION_ERROR: the invalid fields. |
POST /v1/read/{tool}#
Run a read tool
Run one tool with a JSON body of its input (see GET /v1/read). The answer matches the tool's output schema. Calls count against the plan's monthly API requests; from 80 percent of the allowance the answer carries a notice.
Authentication: a secret server key in the Authorization: Bearer header.
Request body#
Content type: application/json
Body#
| Field | Type | Required | Constraints | Description |
|---|
Example requests#
A curl call (the SDK does this for you, batched and retried):
curl -X POST https://api.revu.ai/v1/read/{tool} \
-H "Authorization: Bearer revu_sk_..." \
-H "Content-Type: application/json" \
-d '{"touchpoint":"example.com","page":"/pricing","period":"last_30_days"}'
trends#
{
"touchpoint": "example.com",
"page": "/pricing",
"period": "last_30_days"
}
Responses#
| Status | Meaning |
|---|---|
200 | The tool's answer. |
401 | No key, or an unknown, revoked or expired key. |
402 | This month's API requests are used (QUOTA); the message names the plan, the reset date and the next plan's allowance. |
403 | The plan is not active (BLOCKED). |
404 | No such tool for your organization. |
422 | Invalid input (VALIDATION_ERROR, with details), or a question the tool cannot answer as asked (TOOL_ERROR); the message says what to change. |
429 | More than 60 calls a minute with this key (RATE_LIMITED); wait for Retry-After. |
The 401 response carries this body:
ReadError#
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
error | string | yes | What went wrong, and what to change. | |
code | string | yes | UNAUTHORIZED, NOT_FOUND, VALIDATION_ERROR, TOOL_ERROR, BLOCKED, QUOTA or RATE_LIMITED. | |
link | string | no | Where in REVU to fix it, when there is a place. | |
details | array<string> | no | For VALIDATION_ERROR: the invalid fields. |
The 402 response carries this body:
ReadError#
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
error | string | yes | What went wrong, and what to change. | |
code | string | yes | UNAUTHORIZED, NOT_FOUND, VALIDATION_ERROR, TOOL_ERROR, BLOCKED, QUOTA or RATE_LIMITED. | |
link | string | no | Where in REVU to fix it, when there is a place. | |
details | array<string> | no | For VALIDATION_ERROR: the invalid fields. |
The 403 response carries this body:
ReadError#
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
error | string | yes | What went wrong, and what to change. | |
code | string | yes | UNAUTHORIZED, NOT_FOUND, VALIDATION_ERROR, TOOL_ERROR, BLOCKED, QUOTA or RATE_LIMITED. | |
link | string | no | Where in REVU to fix it, when there is a place. | |
details | array<string> | no | For VALIDATION_ERROR: the invalid fields. |
The 404 response carries this body:
ReadError#
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
error | string | yes | What went wrong, and what to change. | |
code | string | yes | UNAUTHORIZED, NOT_FOUND, VALIDATION_ERROR, TOOL_ERROR, BLOCKED, QUOTA or RATE_LIMITED. | |
link | string | no | Where in REVU to fix it, when there is a place. | |
details | array<string> | no | For VALIDATION_ERROR: the invalid fields. |
The 422 response carries this body:
ReadError#
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
error | string | yes | What went wrong, and what to change. | |
code | string | yes | UNAUTHORIZED, NOT_FOUND, VALIDATION_ERROR, TOOL_ERROR, BLOCKED, QUOTA or RATE_LIMITED. | |
link | string | no | Where in REVU to fix it, when there is a place. | |
details | array<string> | no | For VALIDATION_ERROR: the invalid fields. |
The 429 response carries this body:
ReadError#
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
error | string | yes | What went wrong, and what to change. | |
code | string | yes | UNAUTHORIZED, NOT_FOUND, VALIDATION_ERROR, TOOL_ERROR, BLOCKED, QUOTA or RATE_LIMITED. | |
link | string | no | Where in REVU to fix it, when there is a place. | |
details | array<string> | no | For VALIDATION_ERROR: the invalid fields. |
Errors#
Every error response carries this body:
Error#
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
error | string | yes | Human-readable error message. | |
code | string | yes | Stable machine-readable code: UNAUTHORIZED, FORBIDDEN, VALIDATION_ERROR, RATE_LIMIT_EXCEEDED, or OPERATION_FAILED. | |
timestamp | string | yes | format: date-time | ISO-8601 time the error was produced. |