API Reference

Authentication

API Key Generation

Generate API keys from your dashboard settings at /Devhelion/settings?tab=api-keys

Bearer Token Authentication

Include your API key in the Authorization header:

Authorization: Bearer sk_live_abc123...

Security Best Practices

• Store API keys securely in environment variables
• Never include API keys in client-side code
• Rotate keys regularly (90-day expiration recommended)
• Use different keys for development and production
• Revoke compromised keys immediately

Endpoints

Analytics Events

Query Parameters

Response Format

{
  "events": [
    {
      "id": "evt_123",
      "time": "2024-01-15T10:30:00Z",
      "event_type": "assistant",
      "tool": "claude_code",
      "project_path": "/Users/dev/my-project",
      "user_id": "usr_456",
      "tokens_used": 1234,
      "model": "claude-3-sonnet"
    }
  ],
  "totalCount": 150,
  "stats": {
    "totalEvents": 150,
    "projects": 3,
    "totalTokens": 25000,
    "toolsUsed": 2
  },
  "page": 0,
  "limit": 50
}

Query Parameters

Response Format

{
  "insights": [
    {
      "id": "ins_789",
      "title": "High Token Usage Detected",
      "description": "Your last 5 sessions used 40% more tokens than average",
      "value": "15,234 tokens",
      "type": "trend",
      "category": "performance",
      "is_read": false,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "hasTable": true,
  "unreadCount": 3
}

Path Parameters

• id - The insight ID to mark as read

Response

{
  "success": true
}

Code Examples

cURL

# Get recent events
curl -H "Authorization: Bearer sk_live_..." \
  "https://Devhelion.ai/api/data/events?limit=50&timeRange=7d"

# Get unread insights
curl -H "Authorization: Bearer sk_live_..." \
  "https://Devhelion.ai/api/data/insights?filter=unread"

# Mark insight as read
curl -X POST \
  -H "Authorization: Bearer sk_live_..." \
  "https://Devhelion.ai/api/data/insights/ins_123/read"

JavaScript/TypeScript

const API_KEY = process.env.Devhelion_API_KEY;
const BASE_URL = 'https://Devhelion.ai';

async function fetchEvents(options = {}) {
  const params = new URLSearchParams({
    limit: '50',
    ...options
  });

  const response = await fetch(`${BASE_URL}/api/data/events?${params}`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    }
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

// Usage
const events = await fetchEvents({ timeRange: '7d' });
console.log(`Found ${events.totalCount} events`);

Python

import requests
import os

class DevhelionAPI:
    def __init__(self, api_key=None, base_url="https://Devhelion.ai"):
        self.api_key = api_key or os.getenv("Devhelion_API_KEY")
        self.base_url = base_url
        self.headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }

    def get_events(self, **params):
        response = requests.get(
            f"{self.base_url}/api/data/events",
            headers=self.headers,
            params=params
        )
        response.raise_for_status()
        return response.json()

    def get_insights(self, filter=None):
        params = {"filter": filter} if filter else {}
        response = requests.get(
            f"{self.base_url}/api/data/insights",
            headers=self.headers,
            params=params
        )
        response.raise_for_status()
        return response.json()

# Usage
client = DevhelionAPI()
events = client.get_events(limit=50, timeRange="7d")
print(f"Found {events['totalCount']} events")

Rate Limits

Rate Limit Headers

API responses include rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

429 Too Many Requests

When rate limits are exceeded, you'll receive:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "error": "Rate limit exceeded",
  "retry_after": 60
}

Best Practices

Performance Optimization

• Cache responses when possible to reduce API calls
• Use pagination for large datasets with limit/page parameters
• Filter data at the API level rather than client-side
• Implement retry logic with exponential backoff for failed requests

Error Handling

• Check HTTP status codes before processing responses
• Handle rate limits gracefully with Retry-After headers
• Log API errors for debugging and monitoring
• Implement timeouts to prevent hanging requests

Security

• Validate API keys server-side only - never expose them to clients
• Use HTTPS in production environments
• Rotate API keys regularly (every 90 days recommended)
• Monitor API usage for unusual patterns

Data Handling

• Process events incrementally using time-based filters
• Store insights locally to avoid repeated API calls
• Respect data retention policies when caching responses
• Use appropriate data types for timestamps and numeric values

Support

Need help with the API? Check out our other documentation pages or contact support: