Arenza is now part of the OpenAI Partner Network 🎉
Arenza

Browser action API reference

SDK quickstart: load, initialize, send · Machine-readable JSON Schema

Base URL: https://api.arenza.ai/api/v1/events/collect/{public_install_id}. The public installation ID (arz_pub_ + 32 lowercase hex characters) is available under Portal → AI Integrations. It is not a bearer token.

Using the SDK? You do not need to call these endpoints yourself. init() calls /session; track() calls /events when your code tells it an event happened. Read this page only if you are implementing the browser HTTP calls yourself or debugging them. For events sent by your backend, use the server webhook guide.

For example, your trigger could be a confirmed booking, an accepted enquiry or an activated trial. You choose the trigger. The current browser receiver stores all these as the same generic interaction (internally cta_click), so this API does not yet distinguish custom event names.

Who supplies the IDs?

Browser authentication boundary

The installation ID is public. /session issues a short-lived token bound to that integration, visitor and origin; /events verifies that token. This is not proof of website ownership or a completed business outcome. Keep server API Keys off the website; use your backend for trusted business confirmations.

Source restrictions use the optional integration configuration reporting_origins. When unset, other valid HTTPS origins can create sessions with the public install ID. When configured, a non-matching origin receives 403 origin_not_allowed; measurement mode also permits subdomains of the listed hosts. The separate allowed_origins list restricts cross-domain identity exchange (/link and /redeem), not ordinary session creation or event reporting. These are integration configuration fields, not settings passed to ArenzaBilling.create(); this guide does not imply a Portal editor exists for them.

1. Create a session

POST /session → 200 OK

When: after consent, before sending the first event, and again when the credential expires. SDK init() handles this; track() also ensures a valid session before sending. This request records a page visit, not the business event.

Headers

JSON body

{
  "arenza_visitor_id": "arz_v_aaaaaaaaaaaa",
  "consent": true,
  "url": "https://your-site.example/page"
}

Response

{
  "session_token": "<opaque short-lived token>",
  "expires_in": 900,
  "mode": "measurement"
}

mode can also be shadow for a separately approved connection. Keep session_token private; it is bound to this visitor ID and origin, and expires in 900 seconds. A new session may be created when it expires. The SDK's init() performs/renews this call.

2. Report an action

POST /events → 202 Accepted

When: your own business code determines that the chosen trigger occurred. For example, after a booking response confirms success, not simply when its submit button is clicked. SDK track() handles this request. A valid session is required first.

Headers

JSON body

{
  "arenza_visitor_id": "arz_v_aaaaaaaaaaaa"
}

arenza_visitor_id is required and must match the session. The receiver also accepts an optional flat properties object (at most 20 non-sensitive scalar fields, 4 KiB serialized); these fields do not define an action type or a completed conversion and are not currently stored as customer-visible event labels. Do not send form values, email, prices, cookies or secrets. The body must be at most 8 KiB.

Response (measurement mode)

{ "accepted": true, "mode": "measurement" }

For an approved shadow session the success response also includes receipt_id and duplicate; neither mode's 202 proves a completed signup, payment or a fee.

Errors and verification

Errors have the shape { "error": { "code": "…" } }:

A browser sends its real Origin automatically. curl can supply any Origin string and thus only checks the protocol—not that a site is installed or consent works. Both calls write measurement evidence; do not send synthetic production requests for a customer's brand without separate approval. On the real website, verify consent, one /events 202 per action and unchanged button/form behavior.

Schema: sessionRequest, sessionResponse, eventRequest, eventResponse under $defs. JSON Schema covers payloads; the server additionally checks Origin, session token, request UUID, body-size limits and sensitive property keys.

Stop collection

When a visitor turns off analytics in your site's privacy settings:

  1. Stop the current client with window.arenzaEvents?.stop().
  2. Delete the site's arenza_visitor_id cookie using the same path (/) and domain used to set it.
  3. Do not load or initialize the SDK again while analytics is disabled. Cancel any waiting initialization or event callbacks in your consent integration as well.

stop() stops that client; it does not delete the cookie or change your site's consent settings. If the visitor later opts in again, create a new client rather than reusing the stopped instance.

Manual curl test

Requires Bash, curl and uuidgen. Replace the install ID and origin, then supply the SDK visitor ID. Only run against an approved test brand: these requests record a visit and an event. The page URL must share the request's origin and satisfy any configured reporting-origin restriction. Copy the token only after a successful session response.

INSTALL_ID='arz_pub_YOUR_32_LOWERCASE_HEX_CHARACTERS'
ORIGIN='https://your-site.example'
read -r -s -p 'Visitor ID from your site: ' VISITOR_ID; echo

curl -sS "https://api.arenza.ai/api/v1/events/collect/$INSTALL_ID/session" \
  -H "Origin: $ORIGIN" -H 'Content-Type: application/json' \
  -H "X-Arenza-Delivery-Id: $(uuidgen)" \
  -d "{\"arenza_visitor_id\":\"$VISITOR_ID\",\"consent\":true,\"url\":\"$ORIGIN/page\"}"
# Copy session_token from the response:
read -r -s -p 'session_token: ' TOKEN; echo

curl -i -sS "https://api.arenza.ai/api/v1/events/collect/$INSTALL_ID/events" \
  -H "Origin: $ORIGIN" -H 'Content-Type: application/json' \
  -H "X-Arenza-Delivery-Id: $(uuidgen)" -H "Authorization: Bearer $TOKEN" \
  -d "{\"arenza_visitor_id\":\"$VISITOR_ID\"}"
unset VISITOR_ID TOKEN