Zenovay Help Center

Pro Plan

The Zenovay API provides programmatic access to your analytics data. Build custom integrations, automate workflows, and extend Zenovay's capabilities.

What You Can Do

External API (API Key Authentication)

Capability	Endpoint
Analytics overview	GET /api/external/v1/analytics/:websiteId
Visitor data	GET /api/external/v1/analytics/:websiteId/visitors
Page analytics	GET /api/external/v1/analytics/:websiteId/pages
Country data	GET /api/external/v1/analytics/:websiteId/countries
Technology breakdown	GET /api/external/v1/analytics/:websiteId/technology
List websites	GET /api/external/v1/websites
Website details	GET /api/external/v1/websites/:websiteId
API usage	GET /api/external/v1/usage
Heatmap pages	GET /api/external/v1/heatmaps/:websiteId/pages
Session replays	GET /api/external/v1/replays/:websiteId/sessions
Error groups	GET /api/external/v1/errors/:websiteId/groups

Tracking (Public)

Capability	Endpoint
Track pageview/event	POST /e/:trackingCode
Live visitor count	GET /live/:trackingCode
Heartbeat	POST /heartbeat

API Access by Plan

Plan	API Access	Requests/Minute	Monthly Limit
Free	Limited	10	1,000
Pro	Full	30	10,000
Scale	Full	60	100,000
Enterprise	Full	120	1,000,000

Base URL

The External API base URL is:

https://api.zenovay.com/api/external/v1

Authentication

API Keys

Authenticate with API keys using the X-API-Key header or Authorization: Bearer header:

curl https://api.zenovay.com/api/external/v1/websites \
  -H "X-API-Key: zv_YOUR_API_KEY"

Or using Bearer authentication:

curl https://api.zenovay.com/api/external/v1/websites \
  -H "Authorization: Bearer zv_YOUR_API_KEY"

API keys always start with the zv_ prefix.

Getting Your API Key

Go to API Keys in the sidebar
Click "Create API Key"
Name your key
Set permissions
Copy the key (shown once)

See Authentication for details.

Quick Start

List Your Websites

curl https://api.zenovay.com/api/external/v1/websites \
  -H "X-API-Key: zv_YOUR_API_KEY"

Get Analytics Summary

curl "https://api.zenovay.com/api/external/v1/analytics/YOUR_TRACKING_CODE?timeRange=30d" \
  -H "X-API-Key: zv_YOUR_API_KEY"

Check API Usage

curl https://api.zenovay.com/api/external/v1/usage \
  -H "X-API-Key: zv_YOUR_API_KEY"

Request Format

Headers

Required headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Optional headers:

X-Request-ID: your-unique-id (for debugging)
Accept-Language: en-US

Query Parameters

Common parameters:

Parameter	Description	Example
page	Page number	?page=2
per_page	Items per page (max 100)	?per_page=50
start_date	Filter start	?start_date=2025-01-01
end_date	Filter end	?end_date=2025-01-31
website_id	Filter by website	?website_id=web_xyz

Request Body

For POST/PUT requests:

{
  "field": "value",
  "nested": {
    "field": "value"
  }
}

Response Format

Success Response

{
  "data": { ... },
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 50
  }
}

Error Response

{
  "error": {
    "code": "invalid_parameter",
    "message": "The 'start_date' parameter is invalid",
    "details": {
      "parameter": "start_date",
      "expected": "ISO 8601 date"
    }
  }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad request
401	Unauthorized
403	Forbidden
404	Not found
429	Rate limited
500	Server error

Client Libraries

Zenovay does not have official SDK packages. Instead, use the CDN tracking script for browser-side tracking and standard HTTP requests (fetch, requests, curl, etc.) for server-side API access.

JavaScript (Browser)

Add the tracking script to your HTML:

<script defer data-tracking-code="YOUR_TRACKING_CODE" src="https://api.zenovay.com/z.js"></script>

Then use the global zenovay function:

// Track events
zenovay('track', 'signup', { plan: 'pro' });

JavaScript (Server-Side)

Use fetch to call the External API directly:

const response = await fetch('https://api.zenovay.com/api/external/v1/analytics/WEBSITE_ID', {
  headers: {
    'X-API-Key': 'zv_YOUR_API_KEY',
  },
});
const data = await response.json();

Python (using requests)

import requests

response = requests.get(
    'https://api.zenovay.com/api/external/v1/analytics/WEBSITE_ID',
    headers={'X-API-Key': 'zv_YOUR_API_KEY'}
)
data = response.json()

Common Use Cases

Custom Dashboards

Build internal dashboards:

Fetch aggregated metrics
Create custom visualizations
Combine with other data

Data Warehouse Sync

Export to your warehouse:

Schedule regular exports
Incremental syncs
Full historical export

Automated Reporting

Generate custom reports:

Weekly stakeholder reports
Real-time alerts
Threshold monitoring

CRM Integration

Connect to your CRM:

Push visitor data
Update contact records
Trigger workflows

Rate Limits

External API rate limits are per API key, per minute:

Plan	Requests/Minute	Monthly Limit
Free	10	1,000
Pro	30	10,000
Scale	60	100,000
Enterprise	120	1,000,000

Rate Limit Headers

Every response includes usage 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

See Rate Limits for best practices.

Best Practices

Efficient Requests

Request only needed fields
Use date filters
Paginate large results
Cache when possible

Error Handling

Implement retries
Handle rate limits
Log errors
Monitor success rates

Security

Keep keys secret
Use minimal permissions
Rotate keys regularly
Audit key usage

Testing

Use a test API key with production endpoints:

Go to API Keys in the sidebar
Create a key with "Test" prefix for easy identification
Use the standard API URL: https://api.zenovay.com/api/external/v1/
Delete test keys when done

Support

Getting Help

API documentation: docs.zenovay.com/api
Email: support@zenovay.com

Changelog

Track API changes:

docs.zenovay.com/api/changelog
Subscribe to updates

API Overview