API Documentation

Complete REST API for integrating VibeTraffic analytics into your applications. Perfect for freelancers building custom solutions.

Authentication

API requests use scoped keys. Send the tracking key for event ingestion and the analytics read key for stats or exports in an HTTP header so secrets do not appear in URLs, logs, or browser history.

Recommended Header

X-API-Key: YOUR_SCOPED_KEY

Bearer Token

Authorization: Bearer YOUR_SCOPED_KEY

Security Note: The tracking key can write events only. Keep the analytics read key on your server. Analytics read and export endpoints reject URL-carried keys and do not accept tracking keys.

API Endpoints

Track Events

POST
/track

Request Body

{
  "path": "/pricing",
  "ref": "https://google.com",
  "utm_source": "newsletter",
  "utm_medium": "email",
  "utm_campaign": "launch",
  "ua": "Mozilla/5.0...",
  "ip": "192.168.1.1",
  "screen_w": 1920,
  "screen_h": 1080,
  "lang": "en-US",
  "kind": "pageview",
  "title": "Pricing - vibetraffic.app",
  "search_query": "web analytics"
}

Custom Events

{
  "path": "/signup",
  "kind": "signup",
  "custom_data": {
    "plan": "pro",
    "source": "github"
  }
}

Response

{
  "status": "success",
  "event_id": "evt_1234567890"
}

Get Analytics Stats

GET
/api/stats

Query Parameters

start_date

Start date (YYYY-MM-DD)

end_date

End date (YYYY-MM-DD)

limit

Number of results (default: 100)

offset

Pagination offset (default: 0)

Response

{
  "total_views": 15420,
  "total_uniques": 3280,
  "top_pages": [
    {"path": "/", "views": 5230, "uniques": 1200},
    {"path": "/pricing", "views": 2100, "uniques": 890}
  ],
  "top_referrers": [
    {"ref": "https://google.com", "views": 3200},
    {"ref": "https://github.com", "views": 1800}
  ],
  "daily_stats": [
    {"date": "2024-01-01", "views": 450, "uniques": 120},
    {"date": "2024-01-02", "views": 520, "uniques": 140}
  ]
}

Export Data

GET
/api/export

Query Parameters

format

Export format: csv or json

date_range

Date range: 7d, 30d, 90d, custom

Response

Returns the requested file format for download.

Content-Type: application/csv
Content-Disposition: attachment; filename="analytics-export.csv"

path,views,uniques
/,450,120
/pricing,180,45

Rate Limits

API Rate Limits

  • Tracking endpoint: 1000 requests/minute
  • Analytics API: 100 requests/minute
  • Export endpoint: 10 requests/hour

Response Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

When rate limits are exceeded, you'll receive a 429 Too Many Requests response.

Code Examples

JavaScript/Node.js

const trackingKey = 'YOUR_TRACKING_KEY';
const readKey = 'YOUR_READ_KEY';

// Track page view
fetch('/track', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': trackingKey,
  },
  body: JSON.stringify({
    path: '/pricing',
    kind: 'pageview',
    title: 'Pricing Page'
  })
});

// Get analytics
const response = await fetch('/api/stats?start_date=2024-01-01', {
  headers: { 'X-API-Key': readKey }
});
const data = await response.json();
console.log(data.total_views);

Python

import requests
import json

TRACKING_KEY = 'YOUR_TRACKING_KEY'
READ_KEY = 'YOUR_READ_KEY'
BASE_URL = 'https://your-domain.com'

# Track custom event
response = requests.post(
  f'{BASE_URL}/track',
  headers={'X-API-Key': TRACKING_KEY},
  json={
    'path': '/signup',
    'kind': 'signup',
    'custom_data': {'plan': 'pro'}
  }
)

# Get analytics data
response = requests.get(
  f'{BASE_URL}/api/stats',
  headers={'X-API-Key': READ_KEY},
  params={'start_date': '2024-01-01'}
)
data = response.json()
print(f"Total views: {data['total_views']}")

PHP

<?php
$trackingKey = 'YOUR_TRACKING_KEY';
$baseUrl = 'https://your-domain.com';

// Track event
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$baseUrl/track");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'path' => '/contact',
  'kind' => 'form_submit'
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Content-Type: application/json',
  'X-API-Key: ' . $trackingKey
]);
$response = curl_exec($ch);
curl_close($ch);
?>

cURL

# Track page view
curl -X POST https://your-domain.com/track \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_TRACKING_KEY" \
  -d '{
    "path": "/pricing",
    "kind": "pageview",
    "title": "Pricing Page"
  }'

# Get analytics
curl "https://your-domain.com/api/stats?start_date=2024-01-01" \
  -H "X-API-Key: YOUR_READ_KEY"

Error Handling

The API returns standard HTTP status codes and includes error details in the response body:

400 Bad Request

Invalid request parameters or malformed JSON

401 Unauthorized

Invalid or missing API key

429 Too Many Requests

Rate limit exceeded

500 Internal Server Error

Server error - try again later

Error Response Format

{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY",
  "message": "The provided API key is not valid or has been revoked"
}