Skip to main content
Zenovay
Pro Plan10 minutesIntermediate

API Overview

Introduction to the Zenovay API - capabilities, authentication, and getting started with programmatic access. Learn about api in this API integrations guide.

apideveloperintegrationrest
Last updated:
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)

CapabilityEndpoint
Analytics overviewGET /api/external/v1/analytics/:websiteId
Visitor dataGET /api/external/v1/analytics/:websiteId/visitors
Page analyticsGET /api/external/v1/analytics/:websiteId/pages
Country dataGET /api/external/v1/analytics/:websiteId/countries
Technology breakdownGET /api/external/v1/analytics/:websiteId/technology
List websitesGET /api/external/v1/websites
Website detailsGET /api/external/v1/websites/:websiteId
API usageGET /api/external/v1/usage
Heatmap pagesGET /api/external/v1/heatmaps/:websiteId/pages
Session replaysGET /api/external/v1/replays/:websiteId/sessions
Error groupsGET /api/external/v1/errors/:websiteId/groups

Tracking (Public)

These endpoints are used by the tracking script — no API key required.

CapabilityEndpoint
Track pageview/eventPOST /e/:trackingCode
Live visitor countGET /e/live/:trackingCode
HeartbeatPOST /e/heartbeat/:trackingCode

API Access by Plan

The REST API is a paid feature. Free workspaces can't create or use API keys — the unauthenticated tracking endpoints above stay available on every plan.

PlanAPI AccessRequests/MinuteMonthly Limit
FreeNot available——
ProFull3010,000
ScaleFull60100,000
EnterpriseFull1201,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

  1. Go to Settings → Security and open the API Keys section
  2. Click "Create API Key"
  3. Name your key
  4. Set its scope (all websites, or a single website)
  5. Copy the key (shown once)

API keys require a Pro plan or higher. On a Free plan the create button is disabled.

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

Analytics endpoints take a website ID (a UUID — copy it from the List Your Websites response above) and an optional range (one of 24h, 7d, 30d, 90d, 1y):

curl "https://api.zenovay.com/api/external/v1/analytics/YOUR_WEBSITE_ID?range=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 header (use either form):

Authorization: Bearer YOUR_API_KEY

X-API-Key: YOUR_API_KEY

Send Content-Type: application/json on POST requests that carry a JSON body.

Optional header:

X-Request-ID: your-unique-id (echoed back for debugging)

Query Parameters

Common parameters on the analytics endpoints:

ParameterDescriptionExample
rangeTime window: 24h, 7d, 30d, 90d, 1y (default 7d)?range=30d
limitMax rows to return?limit=50
offsetRows to skip (for paging)?offset=100

Response Format

Success Response

Successful responses are wrapped in a success/data envelope:

{
  "success": true,
  "data": { ... },
  "timestamp": "2026-06-13T00:00:00.000Z"
}

The data object's shape depends on the endpoint (for example, the analytics overview returns website, summary, and daily_stats). Endpoints that page their results include a pagination object inside data.

Error Response

{
  "success": false,
  "error": {
    "message": "Rate limit exceeded (30 requests/minute). Try again in 12 seconds",
    "code": "RATE_LIMIT_EXCEEDED",
    "timestamp": "2026-06-13T00:00:00.000Z"
  }
}

HTTP Status Codes

CodeMeaning
200Success
201Created
400Bad request
401Unauthorized
403Forbidden
404Not found
429Rate limited
500Server 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

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, and depend on the plan of the team the key belongs to:

PlanRequests/MinuteMonthly Limit
Pro3010,000
Scale60100,000
Enterprise1201,000,000

Rate Limit Headers

Responses include usage and rate-limit headers:

X-RateLimit-Limit: 30
X-Usage-Monthly: 4521
X-Usage-Limit: 10000
X-Usage-Reset: 2026-07-01T00:00:00.000Z

X-RateLimit-Remaining is included when available. When you exceed a limit the API returns 429 with a Retry-After header.

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

There's no separate sandbox — test against production with a dedicated key:

  1. Go to Settings → Security and open the API Keys section
  2. Create a key and give it a recognisable name (e.g. "Test")
  3. Scope it to a single test website if you can
  4. Use the standard API URL: https://api.zenovay.com/api/external/v1/
  5. Delete the key when you're done

Support

Getting Help

Changelog

Track product and API changes at docs.zenovay.com/changelog.

Next Steps

Related articles

  1. REST API Reference

    Complete REST API reference - all endpoints, parameters, and response formats for the Zenovay API. Learn about api in this API integrations guide.

  2. How do I query my analytics programmatically (Stats API)?

    Query Zenovay's analytics data over HTTP — totals, time series, and breakdowns by page, country, browser, and more. Plausible-compatible parameter shape for easy migration.

  3. Webhooks

    Configure outbound webhooks to receive real-time notifications from Zenovay when platform events occur, and learn how Zenovay handles inbound payment webhooks internally.

Was this article helpful?