> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.rydhm.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.rydhm.ai/_mcp/server.

# Post what the user did

POST https://api.rydhm.ai/v1/engine/events
Content-Type: application/json

At most 50 events. Each is checked on its own; refused ones come back by index. Moves guide progress (guide.completed is sent once, when the last step is done) and the page map’s health. The unload beacon may send the key as ?key= or a body key, with a text/plain body.

A publishable key (Authorization: Bearer rydhm_pk_…), from one of the key’s allowed websites: the Origin header must be on its list. Never a secret API key (401 secret_key_not_allowed). Rate limited per visitor and per key.

Reference: https://docs.rydhm.ai/api-reference/engine/post-events

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Body (application/json)

This endpoint expects an EngineEventsRequest.

- `events` (list of EngineEventsRequestEventsItems, required)
- `user` (EngineUser, optional) — Who the page’s user is. id with hash (hex HMAC-SHA256 of id under your workspace’s user-signing secret, computed on your server) is a signed user; id alone, or anonymousId, is stored as anon_ and the id.
- `key` (string, optional) — The publishable key, only on the page’s unload beacon (text/plain body; also accepted as ?key=).

## Response

### 201

OK

- `accepted` (integer, required)
- `rejected` (list of EngineEventsResponseRejectedItems, required)

## Errors

### 401 Unauthorized Error

The publishable key is missing, not valid or revoked (invalid_publishable_key), or a secret API key was sent (secret_key_not_allowed).

- `statusCode` (integer, required)
- `message` (string, required)
- `error` (string, optional) — A stable code such as insufficient_scope, expert_not_allowed, rate_limited, plan_limit, payment_required.
- `code` (string, optional) — The stable code on the refusals that carry it here instead of in `error`: stale_edit (409 on an expert save).
- `requestId` (string, optional) — The X-Request-Id of the call, to quote to support.
- `upgradeHint` (ErrorUpgradeHint, optional) — On 402 payment_required and 403 plan_limit: what fixes it.
- `requiredScopes` (list of string, optional) — On 403 insufficient_scope: what the route needs.
- `missingScopes` (list of string, optional)
- `retryAfterSeconds` (integer, optional) — On 429: how long to wait.
- `retryAt` (datetime, optional, nullable)
- `timeZone` (string, optional, nullable)
- `localTime` (string, optional, nullable)
- `state` (string, optional, nullable)
- `exceptionsAllowed` (boolean, optional) — On 400 outside_calling_hours: whether `callingHoursException` may be sent.

### 403 Forbidden Error

The Origin is not one of the key’s allowed websites (origin_not_allowed), the expert is switched off (expert_unavailable), or the user is not signed when the key requires it (signed_user_required, user_hash_invalid).

- `statusCode` (integer, required)
- `message` (string, required)
- `error` (string, optional) — A stable code such as insufficient_scope, expert_not_allowed, rate_limited, plan_limit, payment_required.
- `code` (string, optional) — The stable code on the refusals that carry it here instead of in `error`: stale_edit (409 on an expert save).
- `requestId` (string, optional) — The X-Request-Id of the call, to quote to support.
- `upgradeHint` (ErrorUpgradeHint, optional) — On 402 payment_required and 403 plan_limit: what fixes it.
- `requiredScopes` (list of string, optional) — On 403 insufficient_scope: what the route needs.
- `missingScopes` (list of string, optional)
- `retryAfterSeconds` (integer, optional) — On 429: how long to wait.
- `retryAt` (datetime, optional, nullable)
- `timeZone` (string, optional, nullable)
- `localTime` (string, optional, nullable)
- `state` (string, optional, nullable)
- `exceptionsAllowed` (boolean, optional) — On 400 outside_calling_hours: whether `callingHoursException` may be sent.

### 429 Too Many Requests Error

Rate limited (per visitor and per key); wait Retry-After seconds.

- `statusCode` (integer, required)
- `message` (string, required)
- `error` (string, optional) — A stable code such as insufficient_scope, expert_not_allowed, rate_limited, plan_limit, payment_required.
- `code` (string, optional) — The stable code on the refusals that carry it here instead of in `error`: stale_edit (409 on an expert save).
- `requestId` (string, optional) — The X-Request-Id of the call, to quote to support.
- `upgradeHint` (ErrorUpgradeHint, optional) — On 402 payment_required and 403 plan_limit: what fixes it.
- `requiredScopes` (list of string, optional) — On 403 insufficient_scope: what the route needs.
- `missingScopes` (list of string, optional)
- `retryAfterSeconds` (integer, optional) — On 429: how long to wait.
- `retryAt` (datetime, optional, nullable)
- `timeZone` (string, optional, nullable)
- `localTime` (string, optional, nullable)
- `state` (string, optional, nullable)
- `exceptionsAllowed` (boolean, optional) — On 400 outside_calling_hours: whether `callingHoursException` may be sent.

## Types

### EngineEventsRequestEventsItems

- `type` (enum, required)
  - Allowed values: `page_view`, `guide_started`, `step_completed`, `guide_dismissed`, `announcement_shown`, `announcement_clicked`, `announcement_dismissed`, `target_missing`, `custom`
- `name` (string, optional) — The page path, guide id, announcement id, target or custom event name.
- `data` (map from string to any, optional) — At most 2 KB. step_completed needs stepId.
- `at` (datetime, optional)
- `sessionId` (string, optional)

### EngineUser

Who the page’s user is. id with hash (hex HMAC-SHA256 of id under your workspace’s user-signing secret, computed on your server) is a signed user; id alone, or anonymousId, is stored as anon_ and the id.

- `id` (string, optional)
- `hash` (string, optional)
- `anonymousId` (string, optional)
- `name` (string, optional)
- `traits` (map from string to any, optional) — plan, role, company… (at most 4 KB); used by audiences.

### EngineEventsResponseRejectedItems

- `index` (integer, optional)
- `reason` (string, optional)

### ErrorUpgradeHint

On 402 payment_required and 403 plan_limit: what fixes it.

- `action` (enum, optional)
  - Allowed values: `top_up`, `upgrade`, `contact`
- `planCode` (string, optional) — The smallest plan that allows it, when action is upgrade.
- `href` (string, optional) — Where to go in the app.

## Examples

**Request**

```json
{
  "events": [
    {
      "type": "page_view"
    }
  ]
}
```

**Response**

```json
{
  "accepted": 1,
  "rejected": [
    {
      "index": 1,
      "reason": "string"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.rydhm.ai/v1/engine/events"

payload = { "events": [{ "type": "page_view" }] }
headers = {
    "Authorization": "Bearer <apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.rydhm.ai/v1/engine/events';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <apiKey>', 'Content-Type': 'application/json'},
  body: '{"events":[{"type":"page_view"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```