3 min de leitura

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. Get your API key from Settings > 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

Plan	Requests per Minute	Monthly Limit
Free	10	1,000
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