Developer Documentation

Overview

The Zero Trust Analytics API provides programmatic access to your analytics data, site management, and advanced features like webhooks, goals, and funnels. All API endpoints use HTTPS and return JSON responses.

Base URL: https://ztas.io/api

Authentication

Most API endpoints require authentication using JWT (JSON Web Tokens). See the Authentication guide for details on obtaining and using tokens.

curl https://ztas.io/api/stats?siteId=site_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Quick Start

1. Get your credentials - Log in to get a JWT token
2. Make your first request - Fetch analytics data for your site
3. Explore the API - Check out the endpoint documentation below

Example: Fetch Analytics

# Get JWT token
TOKEN=$(curl -X POST https://ztas.io/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}' \
  | jq -r '.token')

# Fetch analytics data
curl "https://ztas.io/api/stats?siteId=site_abc123&period=7d" \
  -H "Authorization: Bearer $TOKEN"

API Endpoints

Core Analytics

• Authentication - Login, password reset, and token management
• Stats - Get aggregated analytics data
• Track - Send pageview and event data
• Export - Export analytics data
• Realtime - Get real-time visitor data

Site Management

• Sites - Create, list, and delete sites
• API Keys - Manage API keys for programmatic access
• Teams - Invite and manage team members

Advanced Features

• Goals - Create and track conversion goals
• Funnels - Analyze user conversion funnels
• Alerts - Set up automated alerts
• Webhooks - Receive real-time event notifications
• Heatmaps - Get click and scroll heatmap data
• Activity Log - View account activity history

Rate Limits

API requests are rate-limited to ensure service quality:

• 100 requests per minute per user
• 1000 requests per hour per user

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response:

{
  "error": "Rate limit exceeded. Try again in 60 seconds."
}

Response Format

All API endpoints return JSON responses with consistent formatting:

Success Response

{
  "data": {
    // Response data
  }
}

Error Response

{
  "error": "Error message describing what went wrong"
}

HTTP Status Codes

Best Practices

Security

1. Use HTTPS - Always use HTTPS for API requests
2. Protect your tokens - Never expose JWT tokens in client-side code or URLs
3. Rotate API keys - Regularly rotate API keys and revoke unused ones
4. Limit scope - Only request data for resources you own

Performance

1. Cache responses - Cache analytics data that doesn’t change frequently
2. Use appropriate time periods - Request only the data you need
3. Batch operations - Group related API calls when possible
4. Handle rate limits - Implement exponential backoff for rate limit errors

Error Handling

Always handle errors gracefully:

try {
  const response = await fetch('https://ztas.io/api/stats?siteId=site_abc123', {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });

  if (!response.ok) {
    if (response.status === 401) {
      // Token expired - get a new one
      await refreshToken();
    } else if (response.status === 429) {
      // Rate limited - wait and retry
      await sleep(60000);
    }
  }

  const data = await response.json();
} catch (error) {
  console.error('API request failed:', error);
}

CORS

The API supports CORS (Cross-Origin Resource Sharing) for browser-based requests. The following headers are included in responses:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type

Webhooks

For real-time notifications, use Webhooks instead of polling the API. Webhooks deliver events instantly when they occur:

• New pageviews
• Custom events
• Goal completions
• Alert triggers

Support

Need help with the API?

• Check the documentation for each endpoint
• Review code examples in our GitHub repository
• Contact support at support@ztas.io

SDKs and Libraries

Official SDKs coming soon:

• JavaScript/TypeScript (Node.js & Browser)
• Python
• Go
• Ruby

For now, use standard HTTP clients to interact with the API.