Invoker Analytics/Documentation
API Reference

REST API Documentation

Complete API reference for integrating Invoker Analytics into your applications.

Authentication

All API requests require authentication using a Bearer token. You can obtain your API token from your account settings after logging in.

Authorization Header
Authorization: Bearer YOUR_API_TOKEN

Base URL

https://api.invoker.app/api

Authentication Endpoints

POST/login
Authenticate and receive an API token
curl -X POST "https://api.invoker.app/api/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'
GET/user
Get the authenticated user's information
{
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "user@example.com",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Sites Endpoints

GET/sites
List all sites for the authenticated user
{
  "sites": [
    {
      "id": 1,
      "domain": "example.com",
      "name": "Example Site",
      "sid": "abc123xyz",
      "timezone": "UTC",
      "tracking_enabled": true,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}
POST/sites
Create a new site
curl -X POST "https://api.invoker.app/api/sites" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "newsite.com",
    "name": "My New Site",
    "timezone": "America/New_York"
  }'
PUT/sites/{id}
Update a site's settings
curl -X PUT "https://api.invoker.app/api/sites/1" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Site Name",
    "timezone": "Europe/London",
    "tracking_enabled": true
  }'

Analytics Endpoints

GET/sites/{id}/analytics/overview
Get aggregate statistics for a site

Query Parameters

ParameterTypeDescription
periodstringtoday, 7d, 30d, 12mo, custom
start_datedateStart date (YYYY-MM-DD)
end_datedateEnd date (YYYY-MM-DD)
{
  "data": {
    "pageviews": 15420,
    "unique_visitors": 3256,
    "sessions": 4521,
    "bounce_rate": 42.5,
    "avg_session_duration": 185,
    "events": 892,
    "goals": 156
  },
  "comparison": {
    "pageviews_change": 12.5,
    "visitors_change": 8.3,
    "bounce_rate_change": -2.1
  },
  "period": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31"
  }
}
GET/sites/{id}/analytics/pageviews
Get page view statistics with breakdown by page
{
  "data": [
    {
      "page": "/",
      "pageviews": 5420,
      "unique_visitors": 2100,
      "avg_time_on_page": 45,
      "bounce_rate": 35.2
    },
    {
      "page": "/pricing",
      "pageviews": 2150,
      "unique_visitors": 980,
      "avg_time_on_page": 120,
      "bounce_rate": 28.5
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total": 45,
    "total_pages": 3
  }
}
GET/sites/{id}/analytics/referrers
Get traffic sources and referrer data
{
  "data": [
    {
      "source": "google.com",
      "visitors": 1250,
      "percentage": 38.4
    },
    {
      "source": "twitter.com",
      "visitors": 450,
      "percentage": 13.8
    },
    {
      "source": "Direct / None",
      "visitors": 890,
      "percentage": 27.3
    }
  ]
}
GET/sites/{id}/analytics/locations
Get geographic distribution of visitors
{
  "data": [
    {
      "country": "US",
      "country_name": "United States",
      "visitors": 2100,
      "percentage": 45.2,
      "regions": [
        {
          "region": "California",
          "visitors": 650
        }
      ]
    },
    {
      "country": "GB",
      "country_name": "United Kingdom",
      "visitors": 890,
      "percentage": 19.1
    }
  ]
}
GET/sites/{id}/analytics/utm-sources
Get UTM campaign tracking data
{
  "sources": [
    { "source": "google", "visitors": 450 },
    { "source": "newsletter", "visitors": 230 }
  ],
  "mediums": [
    { "medium": "cpc", "visitors": 450 },
    { "medium": "email", "visitors": 230 }
  ],
  "campaigns": [
    { "campaign": "spring_sale", "visitors": 320 }
  ]
}
GET/sites/{id}/analytics/events
Get custom event tracking data
{
  "data": [
    {
      "name": "Button Click",
      "count": 1250,
      "unique_visitors": 890,
      "properties": {
        "button_id": ["cta-signup", "cta-demo"]
      }
    },
    {
      "name": "Form Submit",
      "count": 450,
      "unique_visitors": 445
    }
  ]
}
GET/sites/{id}/analytics/goals
Get goal conversion data
{
  "data": [
    {
      "name": "Signup",
      "conversions": 156,
      "conversion_rate": 4.8,
      "total_value": 0
    },
    {
      "name": "Purchase",
      "conversions": 45,
      "conversion_rate": 1.4,
      "total_value": 4500.00
    }
  ]
}
GET/sites/{id}/analytics/realtime
Get real-time visitor data (last 5 minutes)
{
  "current_visitors": 12,
  "pageviews_last_5min": 45,
  "top_pages": [
    { "page": "/", "visitors": 5 },
    { "page": "/pricing", "visitors": 3 }
  ],
  "top_countries": [
    { "country": "US", "visitors": 7 },
    { "country": "GB", "visitors": 3 }
  ]
}

Team Management Endpoints

GET/sites/{id}/team
List team members for a site
{
  "members": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "role": "owner"
    },
    {
      "id": 2,
      "name": "Jane Smith",
      "email": "jane@example.com",
      "role": "admin"
    }
  ],
  "pending_invitations": [
    {
      "id": 1,
      "email": "new@example.com",
      "role": "viewer",
      "expires_at": "2024-02-01T00:00:00Z"
    }
  ]
}
POST/sites/{id}/team/invite
Invite a new team member
curl -X POST "https://api.invoker.app/api/sites/1/team/invite" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new@example.com",
    "role": "viewer"
  }'

Export Endpoints

GET/sites/{id}/export
Export analytics data in CSV or JSON format

Query Parameters

ParameterRequiredDescription
formatYescsv or json
typeYespageviews, visitors, events, goals, sessions
periodNo7d, 30d, 12mo, custom
limitNoMax rows to export (default: 1000)
curl -X GET "https://api.invoker.app/api/sites/1/export?format=csv&type=pageviews&period=30d" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o export.csv

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

Status CodeDescription
200Success
201Created
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing token
403Forbidden - Insufficient permissions
404Not Found - Resource doesn't exist
422Validation Error - Check error details
429Too Many Requests - Rate limit exceeded

Error Response Format

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."],
    "password": ["The password must be at least 8 characters."]
  }
}

Rate Limits

API requests are rate limited to ensure fair usage:

  • Authentication: 5 requests per minute
  • General API: 240 requests per minute

Rate limit headers are included in all responses:

X-RateLimit-Limit: 240
X-RateLimit-Remaining: 235
X-RateLimit-Reset: 1705329600