4 min read

API Reference

The Zenovay API allows you to access your analytics data programmatically.

Authentication

All API requests require authentication. The External API uses the X-API-Key header. API keys are available on the Pro plan and higher — generate one from Settings → Security → API keys in the dashboard.

Authentication HeaderBash

curl -H "X-API-Key: YOUR_API_KEY" \
https://api.zenovay.com/api/external/v1/analytics/WEBSITE_ID

Base URL

The External API base URL is:

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

Rate Limits

The External API is available on paid plans. Free plans do not include programmatic API access.

Plan	Requests per Minute	Monthly Limit
Free	No API access	No API access
Pro	30	10,000
Scale	60	100,000
Enterprise	120	1,000,000

Rate limit headers are included in all responses:

X-RateLimit-Limit: Request limit
X-RateLimit-Remaining: Requests remaining
X-RateLimit-Reset: Unix timestamp when limit resets

Endpoints

Analytics

GET/analytics/{websiteId}

Get analytics data for a website

Parameters

Parameter	Type	Required	Description
`websiteId`	string	Yes	Website ID
`range`	string	No	Time range: `24h`, `7d`, `30d`, `90d` (default: `7d`)

Response

ResponseJSON

{
"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
  }
]
}

Real-time Data

GET/track/realtime/{websiteId}

Get real-time visitor data

Response

ResponseJSON

{
"count": 23,
"visitors": [
  {
    "id": "visitor-123",
    "country_name": "United States",
    "city": "New York",
    "device_type": "desktop",
    "value_score": 78,
    "visited_at": "2025-01-01T12:34:56Z"
  }
],
"timestamp": "2025-01-01T12:35:00Z"
}

Websites Management

GET/websites

List all websites

Response

ResponseJSON

{
"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"
  }
]
}

POST/websites

Create a new website

Request Body

RequestJSON

{
"domain": "newsite.com",
"name": "My New Website"
}

Response

ResponseJSON

{
"website": {
  "id": "789e0123-e89b-12d3-a456-426614174000",
  "domain": "newsite.com",
  "name": "My New Website",
  "tracking_code": "xyz789abc123",
  "is_active": true,
  "created_at": "2025-01-01T12:00:00Z"
}
}

Error Handling

The API uses standard HTTP status codes:

Status Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Error ResponseJSON

{
"error": "Website not found",
"message": "The specified website ID does not exist or you don't have access to it"
}

Using the API

You can call the External API from any language using standard HTTP requests:

cURL

curl -X GET "https://api.zenovay.com/api/external/v1/analytics/WEBSITE_ID" \
-H "X-API-Key: YOUR_API_KEY"

Bash