Complete reference for all Zenovay REST API endpoints. For getting started, see API Overview.
External API
The External API uses API key authentication and is available to Pro, Scale, and Enterprise plans.
Base URL
https://api.zenovay.com/api/external/v1
Authentication
Include your API key in every request using either header:
X-API-Key: zv_YOUR_API_KEY
# or
Authorization: Bearer zv_YOUR_API_KEY
Analytics Endpoints
Get Analytics Overview
GET /analytics/{websiteId}
Returns an overview of analytics data for a website.
Query parameters:
| Parameter | Type | Description |
|---|---|---|
| timeRange | string | Time range: 24h, 7d, 30d, 90d (default: 7d) |
Response:
{
"website": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"domain": "example.com",
"name": "My Website"
},
"timeRange": "7d",
"totalVisitors": 1247,
"totalPageViews": 3891,
"bounceRate": 42.3,
"topCountries": [
{
"name": "United States",
"code": "US",
"visitors": 456,
"percentage": 36.6
}
],
"dailyStats": [
{
"date": "2025-01-01",
"visitors": 178,
"pageViews": 542,
"bounceRate": 38.2
}
]
}
Get Visitors
GET /analytics/{websiteId}/visitors
Returns visitor data for a website.
Query parameters:
| Parameter | Type | Description |
|---|---|---|
| timeRange | string | Time range filter |
| page | integer | Page number (default: 1) |
| per_page | integer | Results per page (max: 100) |
Get Pages
GET /analytics/{websiteId}/pages
Returns page analytics data for a website.
Get Countries
GET /analytics/{websiteId}/countries
Returns geographic breakdown of visitors by country.
Get Technology
GET /analytics/{websiteId}/technology
Returns technology breakdown (browsers, operating systems, device types).
Websites Endpoints
List Websites
GET /websites
Returns all websites accessible to your API key.
Response:
{
"websites": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"domain": "example.com",
"name": "My Website",
"tracking_code": "abc123def456",
"is_active": true,
"created_at": "2025-01-01T00:00:00Z"
}
]
}
Get Website Details
GET /websites/{websiteId}
Returns details for a specific website.
Heatmap Endpoints
Get Heatmap Pages
GET /heatmaps/{websiteId}/pages
Returns pages that have heatmap data collected.
Session Replay Endpoints
Get Replay Sessions
GET /replays/{websiteId}/sessions
Returns session replay recordings for a website.
Error Tracking Endpoints
Get Error Groups
GET /errors/{websiteId}/groups
Returns grouped error data for a website.
Usage Endpoint
Check API Usage
GET /usage
Returns your current API usage and limits.
Response:
{
"plan": "pro",
"usage": {
"requests_this_minute": 5,
"requests_this_month": 4521,
"monthly_limit": 10000
}
}
Tracking Endpoints (Public)
These endpoints do not require API key authentication. They use the website tracking code.
Track Pageview or Event
POST /e/{trackingCode}
Sends a pageview or custom event. This is used by the tracking script automatically. For server-side tracking, send the same payload format with appropriate headers.
Live Visitor Count
GET /live/{trackingCode}
Returns the current number of live visitors on the site.
Heartbeat
POST /heartbeat
Sends a heartbeat signal to keep a visitor session alive.
Error Responses
Error Format
{
"error": {
"code": "invalid_parameter",
"message": "The 'start_date' parameter must be a valid date",
"details": {
"parameter": "start_date",
"provided": "invalid",
"expected": "YYYY-MM-DD"
}
}
}
Common Error Codes
| Code | HTTP Status | Description |
|---|---|---|
| invalid_api_key | 401 | API key invalid or missing |
| unauthorized | 403 | Insufficient permissions |
| not_found | 404 | Resource not found |
| invalid_parameter | 400 | Bad parameter |
| rate_limit_exceeded | 429 | Too many requests |
| monthly_limit_exceeded | 429 | Monthly API request limit reached |
| server_error | 500 | Internal error |
Rate Limits
External API rate limits are per API key:
| Plan | Requests/Minute | Monthly Limit |
|---|---|---|
| Free | 10 | 1,000 |
| Pro | 30 | 10,000 |
| Scale | 60 | 100,000 |
| Enterprise | 120 | 1,000,000 |
Every response includes rate limit headers:
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 27
X-Usage-Monthly: 4521
X-Usage-Limit: 10000
X-Usage-Reset: 2025-02-01T00:00:00Z