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?

• arenza_visitor_id: which visitor? The SDK generates and keeps it in the site's cookie. Read it with window.arenzaEvents.getVisitorId() when writing your own HTTP client. Reuse it for that visitor; do not generate a new visitor ID for every event. Reading the ID sends nothing.
• X-Arenza-Delivery-Id: which delivery? The SDK generates a UUID per logical request and reuses the event UUID for its retries. When writing your own HTTP client, generate it with crypto.randomUUID() before sending, retain it for retries of that same request, and create a new one for a different request. It is not a visitor ID or a business event name. Do not assume every downstream mode deduplicates identically.

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

• Origin: the page's valid HTTPS origin, sent automatically by a browser; it must satisfy reporting_origins if that optional restriction is configured.
• Content-Type: application/json
• X-Arenza-Delivery-Id: a fresh UUID. Do not reuse it for another request.

JSON body

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

• arenza_visitor_id required: arz_v_ followed by 12–80 letters, digits, _ or -. Use the same ID in the subsequent event.
• consent required: must be true; load the SDK only after analytics consent.
• url required: absolute HTTPS page URL on the same origin as the Origin header, at most 2,048 characters. Only origin and path are recorded; query strings are not used as the page URL.
• source and referrer optional attribution hints. Do not include personal information.

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

• The same Origin and Content-Type: application/json as the session call.
• X-Arenza-Delivery-Id: a new UUID for this action.
• Authorization: Bearer <session_token> from /session.

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": "…" } }:

• 401 invalid_session: missing, expired, revoked or mismatched token/visitor/origin.
• 403 origin_not_allowed: malformed origin, origin rejected by a configured restriction, or inactive integration.
• 404 not_found: unknown install ID or unsupported connection.
• 422 invalid_input / invalid_url: malformed body, visitor ID, UUID, consent or page URL.
• 429 rate_limited: retry after the response's Retry-After header.

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

Server events

Server event fields

Use this endpoint:

POST https://api.arenza.ai/api/v1/billing-events/{website_install_id}

With API Key authentication, the arz_pub_… Website install ID is an alias for your brand's configured connection. Existing connection UUIDs also remain valid; do not put the API Key in the URL.

Required headers: Authorization: Bearer <API_KEY>, Content-Type: application/json, and webhook-id: <delivery UUID>. No HMAC signature or timestamp is required on this path.

In the Arenza request, put that same ID under attribution.visitor_id, not a top-level arenza_visitor_id:

JSON — example test event; replace values with your business record

{
  "spec_version": "1.0",
  "event_id": "booking-event-123",
  "event_handle": "YOUR_CONFIGURED_EVENT_HANDLE",
  "occurred_at": "2026-09-24T12:00:00Z",
  "subject": { "type": "booking", "id": "booking-123" },
  "attribution": { "visitor_id": "arz_v_aaaaaaaaaaaa" },
  "status": "test"
}

Responses and errors

HTML / JavaScript: trigger an approved test once, then check DevTools → Network for one /events request returning 202. This means received, not independent proof of the business outcome.

Python / Go:

A successful request returns 202:

{
  "accepted": true,
  "receipt_id": "<receipt ID>",
  "duplicate": false,
  "status_url": "/api/v1/billing-events/<connection ID>/receipts/<receipt ID>"
}

202 means queued, not that attribution, reporting or billing has completed. Save the receipt for processing checks.

• 401: the API Key is missing, invalid or revoked.
• 403 insufficient_scope: create a Key with Write permission.
• 404: the connection is unavailable or the Key has no access to its brand.
• 422 server_event_not_configured: this installation has no configured server event binding.
• 422 event_handle_not_allowed: the event type is not configured for this connection.
• 409: an event/delivery ID may have been reused with a changed body.
• Network failures or 5xx: retry through your worker using the same IDs and unchanged event; do not generate a new event ID or delivery ID for the retry. Avoid unbounded immediate retries.

Test only against an approved connection. The examples do not send until you call the function.

Existing preconfigured connections

An existing pre-bound integration can accept just {"arenza_visitor_id":"arz_v_…"} at /api/v1/billing-events/{website_install_id}/preconfigured, with the same Bearer, content-type and webhook-id headers. It only supports its preconfigured event binding. Do not use that minimal body on the general endpoint above, and do not assume it supports arbitrary event types.

HTTP / curl reference · JSON Schema · Stopping collection

Existing HMAC-signed integrations continue to work with their connection UUID and signature headers. API Key callers do not need to obtain or rotate those signing secrets.

Production verification: 2026-09-24 — tested paths, deployed version, authentication checks and limits of the evidence.