Stateless Analytics API Reference

Perform every dashboard action programmatically through self-sufficient stateless HTTP requests using your secret API key.

Stateless Secret Key Authentication

All API requests are completely stateless. You do not need session cookies or CSRF tokens. Pass your secret key (tya_...) in the Authorization header or X-API-Key header:

Authorization: Bearer tya_7f9a2b1c_your_secret_key
# OR
X-API-Key: tya_7f9a2b1c_your_secret_key

POST /api/v1/keys/

Generate a new stateless secret key programmatically using your account credentials (or from the Dashboard UI).

curl -X POST https://analytics.teeyatech.com/api/v1/keys/ \
  -H "Content-Type: application/json" \
  -d '{"username": "your_username", "password": "your_password", "name": "Production Server"}'

POST /api/v1/websites/

Register a new website to track. Returns the Website UUID (id), tracking_id, and ready-to-embed HTML tracker_snippet in JSON.

curl -X POST https://analytics.teeyatech.com/api/v1/websites/ \
  -H "Authorization: Bearer YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Store", "domain": "acme-store.com"}'

# JSON Response (201 Created):
{
  "status": "success",
  "message": "Website registered successfully",
  "website": {
    "id": "b3d9182e-5f4a-4b9c-8112-90ab34cd56ef",
    "name": "Acme Store",
    "domain": "acme-store.com",
    "tracking_id": "tya_site_8f91a2b3c4d5e6f7",
    "is_active": true,
    "tracker_snippet": "<script src=\"https://analytics.teeyatech.com/tracker.js\" data-site-id=\"tya_site_8f91a2b3c4d5e6f7\" data-collector-url=\"https://analytics.teeyatech.com/api/v1/collect/\" defer></script>"
  }
}

GET /api/v1/websites/

List all websites belonging to the authenticated API key owner along with their embed snippets.

curl -X GET https://analytics.teeyatech.com/api/v1/websites/ \
  -H "Authorization: Bearer YOUR_SECRET_API_KEY"

GET PUT DELETE /api/v1/websites/<uuid:website_id>/

Inspect, update (name, domain, is_active), or delete a specific website by its UUID.

GET /api/v1/websites/<uuid:website_id>/analytics/?days=30

Retrieve all analytics data for a website by its Website ID (website_id). Supports ?days=1, 7, 30, 90, etc.

curl -X GET "https://analytics.teeyatech.com/api/v1/websites/b3d9182e-5f4a-4b9c-8112-90ab34cd56ef/analytics/?days=30" \
  -H "Authorization: Bearer YOUR_SECRET_API_KEY"

# JSON Response (200 OK):
{
  "website": {
    "id": "b3d9182e-5f4a-4b9c-8112-90ab34cd56ef",
    "name": "Acme Store",
    "domain": "acme-store.com",
    "tracking_id": "tya_site_8f91a2b3c4d5e6f7"
  },
  "period_days": 30,
  "summary": {
    "realtime_active_visitors": 12,
    "total_pageviews": 18420,
    "total_sessions": 6210,
    "unique_visitors": 4890,
    "bounce_rate_percentage": 34.2,
    "total_conversions": 312,
    "conversion_rate_percentage": 6.38
  },
  "top_pages": [{"pathname": "/pricing", "page_title": "Pricing", "views": 4120}],
  "top_referrers": [{"referrer_domain": "google.com", "count": 2150}],
  "campaigns": [{"utm_source": "newsletter", "utm_medium": "email", "utm_campaign": "launch", "count": 640}],
  "geographic": {
    "countries": [{"country": "Nigeria", "country_code": "NG", "visits": 2840}],
    "cities": [{"city": "Lagos", "country": "Nigeria", "visits": 2100}]
  },
  "technology": {
    "devices": [{"device_type": "mobile", "count": 3800}, {"device_type": "desktop", "count": 2410}],
    "browsers": [{"browser": "Chrome", "count": 4100}],
    "operating_systems": [{"os": "iOS", "count": 2100}, {"os": "Windows 10/11", "count": 1950}]
  },
  "events_breakdown": [{"event_type": "conversion", "event_name": "checkout_completed", "count": 312}]
}

JavaScript Tracker (`tracker.js`) & Conversions

Once tracker.js is loaded on your site, it automatically tracks pageviews, SPA route changes, referrers, UTM tags, device/OS/browser, and IP geolocation. You can also track custom events and conversions:

// 1. Track a Conversion Goal via JavaScript
window.teeya.conversion('checkout_completed', { order_id: 'ORD-102', amount: 120 });

// 2. Track a Custom Event via JavaScript
window.teeya.track('video_played', { video_title: 'Product Tour' });

// 3. Declarative HTML Attribute Tracking (Zero JS needed)
<button data-teeya-conversion="signup_completed" data-teeya-meta='{"plan": "pro"}'>
  Create Account
</button>

Stateless Analytics API Reference

Stateless Secret Key Authentication

JavaScript Tracker (tracker.js) & Conversions

JavaScript Tracker (`tracker.js`) & Conversions