API Reference

REST API

Programmatic access to your analytics data. Build custom dashboards, integrate with your apps, or export data to your own systems.

Quick Start

1. Create an API Key

Go to API Keys in your dashboard to create a new key.

2. Make Your First Request

curl -X GET "https://phi.llc/api/v1/stats?range=7d" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Authentication

Bearer Token Authentication

All API requests require a valid API key passed in the Authorization header.

Authorization: Bearer sk_live_YOUR_API_KEY

Key Security

• Keys are hashed and cannot be retrieved
• Rotate keys regularly
• Never expose keys in client-side code

Key Format

• Prefix: sk_live_
• Length: ~55 characters
• Encoding: Base64URL

Rate Limits

1,000

Requests per hour (default)

10,000

Available on request

Unlimited

Enterprise plans

Rate Limit Headers

When rate limited, responses include 429 Too Many Requests with details in the response body.

Endpoints

Get aggregated analytics statistics

Query Parameters

Name	Type	Default	Description
range	string	7d	Time range: 24h, 7d, 30d, 90d

Example Request

curl -X GET "https://phi.llc/api/v1/stats" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Response

{
  "site_id": "phi_abc123",
  "range": "7d",
  "stats": {
    "totalViews": 15420,
    "uniqueVisitors": 3847,
    "uniqueSessions": 5291,
    "avgDuration": 127,
    "bounceRate": 42,
    "viewsPerVisitor": 4.01
  },
  "deviceBreakdown": {
    "desktop": 8934,
    "mobile": 5821,
    "tablet": 665
  },
  "topCountries": [
    { "country": "US", "count": 5234 },
    { "country": "UK", "count": 2341 }
  ],
  "dailyViews": [
    { "date": "2025-01-01", "count": 2134 },
    { "date": "2025-01-02", "count": 2456 }
  ]
}

Error Handling

Status Code	Error Code	Description
401	UNAUTHORIZED	Invalid or missing API key
403	FORBIDDEN	Insufficient permissions or disallowed origin
429	RATE_LIMITED	Too many requests, slow down
500	INTERNAL_ERROR	Server error, contact support

Error Response Format

{
  "error": "Rate limit exceeded. 0 requests remaining. Resets in 1823 seconds.",
  "code": "RATE_LIMITED"
}

Code Examples

JavaScript / Node.js

const response = await fetch('https://phi.llc/api/v1/stats?range=7d', {
  headers: {
    'Authorization': 'Bearer sk_live_YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(`Total views: ${data.stats.totalViews}`);

Python

import requests

response = requests.get(
    'https://phi.llc/api/v1/stats',
    params={'range': '7d'},
    headers={'Authorization': 'Bearer sk_live_YOUR_API_KEY'}
)

data = response.json()
print(f"Total views: {data['stats']['totalViews']}")

cURL

curl -X GET "https://phi.llc/api/v1/stats?range=30d" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json"

Best Practices

🔐 Security

• Store keys in environment variables
• Use server-side requests only
• Rotate keys periodically

⚡ Performance

• Cache responses when possible
• Use pagination for large datasets
• Request only needed fields

🔄 Rate Limits

• Implement exponential backoff
• Monitor your usage via /api/v1/usage
• Contact us for higher limits

🛠️ Debugging

• Check error codes in responses
• Verify key format (sk_live_...)
• Ensure correct site_id scope