Documentation

REST API · v1.0

Send page views and custom events to WysLeap from any application.

On this page

API documentation

API Documentation

Send page views and custom events to WysLeap from any application with the telemetry ingest endpoints.

Quick Start

The fastest path depends on what you need:

Create a site

Get started

Add the tracker

One script tag auto-tracks pageviews, clicks, and scroll depth, with optional session replay.

Onboarding guide

Call the API

Send page views and custom events with the endpoints below.

Jump to endpoints

Overview

Base URL

https://wysleap.com/api

Authentication

API Key (header or body)

Response format

JSON + HTTP status codes

Authentication

Every API request requires your API key, found in Site Settings. Supply it as a request header (recommended) or inside the request body.

Header (recommended)

http

X-API-Key: your-api-key-here

Request body

json

{
  "siteId": "your-site-id",
  "_apiKey": "your-api-key-here"
}

Security: Never expose your API key in client-side code or public repos. Use environment variables and rotate immediately if compromised.

Endpoints

POST

/telemetry/pageview

Track page views. Automatically builds visitor profiles from browser and device signals.

Request Parameters

Parameter	Type	Required	Description
`siteId`	string	Yes	Your site identifier
`pageUrl`	string	Yes	Full URL of the page being viewed
`pageTitle`	string	No	Page title from document.title
`referrer`	string	No	Referring URL
`visitorId`	string	No	Visitor ID, auto-generated if omitted
`sessionId`	string	No	Session ID, auto-generated if omitted
`screenWidth`	integer	No	Viewport width in pixels
`screenHeight`	integer	No	Viewport height in pixels
`language`	string	No	Browser language (e.g. en-US)
`timeZone`	string	No	IANA timezone identifier
`_apiKey`	string	Yes*	API key (or use X-API-Key header)

Code Examples

cURL

curl -X POST https://wysleap.com/api/telemetry/pageview \
  -H "Content-Type: application/json" \
  -d '{
    "siteId": "your-site-id",
    "pageUrl": "https://example.com/products",
    "pageTitle": "Products - Example Store",
    "referrer": "https://google.com",
    "visitorId": "vis_abc123",
    "sessionId": "sess_xyz789",
    "userAgent": "Mozilla/5.0...",
    "screenWidth": 1920,
    "screenHeight": 1080,
    "language": "en-US",
    "timeZone": "America/New_York",
    "_apiKey": "your-api-key"
  }'

Response 200 OK

json

{
  "success": true,
  "message": "Pageview tracked successfully",
  "visitorId": "vis_abc123",
  "sessionId": "sess_xyz789",
  "timestamp": "2025-01-15T10:30:00Z"
}

POST

/telemetry/event

Track custom events such as purchases, sign-ups, button clicks, or any other interaction that matters to you.

Use Title Case for event names, e.g. Sign Up Success, not sign_up_success.

Request Parameters

Parameter	Type	Required	Description
`siteId`	string	Yes	Your site identifier
`eventName`	string	Yes	Event name in Title Case (e.g. "Purchase Completed")
`eventData`	object	No	Any JSON-serializable metadata for the event
`visitorId`	string	No	Visitor ID to associate the event with
`sessionId`	string	No	Session ID to associate the event with
`pageUrl`	string	No	URL where the event occurred
`_apiKey`	string	Yes*	API key (or use X-API-Key header)

Code Examples

cURL

curl -X POST https://wysleap.com/api/telemetry/event \
  -H "Content-Type: application/json" \
  -d '{
    "siteId": "your-site-id",
    "eventName": "Purchase Completed",
    "eventData": {
      "productId": "prod_123",
      "productName": "Premium Plan",
      "currency": "USD"
    },
    "visitorId": "vis_abc123",
    "pageUrl": "https://example.com/checkout/success",
    "_apiKey": "your-api-key"
  }'

Response 200 OK

json

{
  "success": true,
  "message": "Event tracked successfully",
  "eventId": "evt_123456",
  "timestamp": "2025-01-15T10:30:00Z"
}

Error Handling

All error responses use standard HTTP status codes with a consistent JSON body.

400Bad Request

json

{
  "error": "Invalid payload"
}

401Unauthorized

json

{
  "error": "Invalid API key"
}

403Forbidden

json

{
  "error": "Origin not allowed"
}

429Too Many Requests

json

{
  "error": "Monthly event limit reached",
  "usage": { "count": 1000000, "limit": 1000000, "percentUsed": 100 }
}

500Internal Server Error

json

{
  "error": "Internal server error"
}

Rate Limits

Ingestion is limited by your plan's monthly event allowance (page views and events). Requests beyond it return 429 Too Many Requests with your current usage, until the allowance resets at the start of the next month. Requests are also checked against the site's API key and allowed domains.

json

{
  "error": "Monthly event limit reached",
  "usage": { "count": 1000000, "limit": 1000000, "percentUsed": 100 }
}

JavaScript SDK

The easiest integration. One script tag handles anonymous visitor IDs, session management, and data collection automatically.

For full setup, configuration options (trackClicks, trackScroll, session replay), and all SDK methods (trackPageView, trackEvent, setConsent), see the Onboarding Guide.

Use WysLeap.trackEvent('Event Name', { }) in your app to send custom events without calling the REST endpoint directly.

Ready to get started?

Get your API key and start integrating privacy-first visitor intelligence into your application.

Get your API key Contact support