# AnalyticsHub Integration Guide

> **Base URL:** `https://bizeyes.securitasmachina.org`

AnalyticsHub is a self-hosted telemetry platform. Send page views, events, exceptions,
and request metrics from any application using simple HTTP POST calls.

---

## Getting an API Key

1. Log in to AnalyticsHub at [https://bizeyes.securitasmachina.org/login](https://bizeyes.securitasmachina.org/login).
2. Navigate to **Applications** (`/apps`).
3. Register your application and create an API key — the full key is shown **once** at
   creation time. Copy it immediately.
4. Use the placeholder `ah_live_YOUR_KEY` in the examples below and replace it with your
   actual key.

---

## Authentication

Every collect request authenticates via an `apiKey` field in the **JSON request body**.
There are no HTTP headers or query-string parameters required for auth.

```json
{
  "apiKey": "ah_live_YOUR_KEY",
  ...
}
```

---

## Environments

Include the optional `environment` field to tag telemetry by deployment environment.
Accepted values (case-sensitive): `Production`, `Staging`, `QA`, `Dev`.
**Default:** `Production` (if omitted).

```json
{
  "apiKey": "ah_live_YOUR_KEY",
  "environment": "Staging"
}
```

---

## Endpoints

All endpoints: `POST https://bizeyes.securitasmachina.org/api/collect/<type>`

### POST /api/collect/session

Start a user session. Returns a `sessionToken` to attach to subsequent events.

**Request body:**
```json
{
  "apiKey": "ah_live_YOUR_KEY",
  "userId": "optional-user-id",
  "country": "US",
  "city": "New York",
  "browser": "Chrome",
  "os": "Windows",
  "device": "Desktop",
  "referrer": "https://example.com",
  "utmSource": "newsletter",
  "utmMedium": "email",
  "utmCampaign": "spring2026",
  "environment": "Production"
}
```

**Response:** `200 OK`
```json
{ "sessionToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }
```

---

### POST /api/collect/pageview

Record a page view.

**Request body:**
```json
{
  "apiKey": "ah_live_YOUR_KEY",
  "path": "/home",
  "title": "Home Page",
  "sessionToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "referrer": "https://google.com",
  "environment": "Production"
}
```

**Response:** `200 OK`

---

### POST /api/collect/event

Record a custom event (button click, feature use, etc.).

**Request body:**
```json
{
  "apiKey": "ah_live_YOUR_KEY",
  "name": "button.clicked",
  "category": "ui",
  "label": "signup-cta",
  "value": 1.0,
  "sessionToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "properties": "{\"plan\":\"pro\"}",
  "environment": "Production"
}
```

**Response:** `200 OK`

---

### POST /api/collect/exception

Record an application exception.

**Request body:**
```json
{
  "apiKey": "ah_live_YOUR_KEY",
  "type": "NullReferenceException",
  "message": "Object reference not set to an instance of an object",
  "stackTrace": "   at MyApp.Foo() in Foo.cs:line 42",
  "severity": "Error",
  "isHandled": false,
  "environment": "Production"
}
```

**Response:** `200 OK`

---

### POST /api/collect/request

Record an HTTP request metric.

**Request body:**
```json
{
  "apiKey": "ah_live_YOUR_KEY",
  "method": "GET",
  "path": "/api/products",
  "statusCode": 200,
  "durationMs": 45.2,
  "environment": "Production"
}
```

**Response:** `200 OK`

---

## Quick-Start Snippets

### curl

```bash
# 1. Create a session
SESSION=$(curl -s -X POST https://bizeyes.securitasmachina.org/api/collect/session \
  -H 'Content-Type: application/json' \
  -d '{"apiKey":"ah_live_YOUR_KEY","browser":"curl","environment":"Dev"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['sessionToken'])")

# 2. Send a page view
curl -s -X POST https://bizeyes.securitasmachina.org/api/collect/pageview \
  -H 'Content-Type: application/json' \
  -d "{"apiKey":"ah_live_YOUR_KEY","path":"/home","sessionToken":"$SESSION","environment":"Dev"}"
```

---

### JavaScript (fetch)

```javascript
const BASE = 'https://bizeyes.securitasmachina.org';
const API_KEY = 'ah_live_YOUR_KEY';

// 1. Create session
const sessionRes = await fetch(`${BASE}/api/collect/session`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ apiKey: API_KEY, browser: navigator.userAgent, environment: 'Production' })
});
const { sessionToken } = await sessionRes.json();

// 2. Track page view
await fetch(`${BASE}/api/collect/pageview`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ apiKey: API_KEY, path: window.location.pathname, sessionToken, environment: 'Production' })
});

// 3. Track a custom event
await fetch(`${BASE}/api/collect/event`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ apiKey: API_KEY, name: 'button.clicked', category: 'ui', sessionToken, environment: 'Production' })
});
```

---

### C# (HttpClient)

```csharp
using System.Net.Http.Json;

const string baseUrl = ""https://bizeyes.securitasmachina.org";
const string apiKey  = "ah_live_YOUR_KEY";

var http = new HttpClient();

// 1. Create session
var sessionResp = await http.PostAsJsonAsync($"{baseUrl}/api/collect/session", new
{
    apiKey,
    browser = "MyApp/1.0",
    environment = "Production"
});
var session = await sessionResp.Content.ReadFromJsonAsync<SessionResult>();
var sessionToken = session!.SessionToken;

// 2. Record a page view
await http.PostAsJsonAsync($"{baseUrl}/api/collect/pageview", new
{
    apiKey,
    path = "/home",
    sessionToken,
    environment = "Production"
});

// 3. Record a custom event
await http.PostAsJsonAsync($"{baseUrl}/api/collect/event", new
{
    apiKey,
    name = "feature.used",
    category = "ui",
    sessionToken,
    environment = "Production"
});

record SessionResult(string SessionToken);
```

---

### Python (requests)

```python
import requests

BASE = ""https://bizeyes.securitasmachina.org"
API_KEY = 'ah_live_YOUR_KEY'

# 1. Create session
resp = requests.post(f'{BASE}/api/collect/session', json={
    'apiKey': API_KEY,
    'browser': 'Python/requests',
    'environment': 'Production'
})
session_token = resp.json()['sessionToken']

# 2. Track page view
requests.post(f'{BASE}/api/collect/pageview', json={
    'apiKey': API_KEY,
    'path': '/home',
    'sessionToken': session_token,
    'environment': 'Production'
})

# 3. Track custom event
requests.post(f'{BASE}/api/collect/event', json={
    'apiKey': API_KEY,
    'name': 'feature.used',
    'category': 'analytics',
    'sessionToken': session_token,
    'environment': 'Production'
})
```

---

## For AI Agents (Claude)

**Machine-readable version of this guide:** `GET https://bizeyes.securitasmachina.org/docs/llms.txt`

**Terse integration recipe — follow in order:**

1. **Obtain an API key** — the human owner must create one at `https://bizeyes.securitasmachina.org/apps`. The key
   starts with `ah_` and is shown once. Use placeholder `ah_live_YOUR_KEY` in all
   code until the real key is substituted.

2. **Create a session** — `POST https://bizeyes.securitasmachina.org/api/collect/session` with `apiKey` and
   optional metadata (`browser`, `os`, `device`, `userId`, `environment`). Extract
   `sessionToken` from the response JSON.

3. **Send page views** — `POST https://bizeyes.securitasmachina.org/api/collect/pageview` with `apiKey`,
   `path`, `sessionToken`, and optionally `environment`.

4. **Send events** — `POST https://bizeyes.securitasmachina.org/api/collect/event` with `apiKey`, `name`,
   `category`, `sessionToken`, and optionally `value`, `properties`, `environment`.

5. **Send exceptions** — `POST https://bizeyes.securitasmachina.org/api/collect/exception` with `apiKey`,
   `type`, `message`, `stackTrace`, `severity` (`Error`/`Warning`/`Info`),
   `isHandled` (bool), and optionally `environment`.

6. **Send request metrics** — `POST https://bizeyes.securitasmachina.org/api/collect/request` with `apiKey`,
   `method`, `path`, `statusCode`, `durationMs`, and optionally `environment`.

**Environment field** — use `Production`, `Staging`, `QA`, or `Dev` (default:
`Production`). Omit for production traffic.

**OpenAPI spec** — machine-readable contract available at:
`GET https://bizeyes.securitasmachina.org/swagger/v1/swagger.json`

**Interactive Swagger UI** — `https://bizeyes.securitasmachina.org/swagger`

All endpoints accept and return JSON. No extra HTTP headers are required beyond
`Content-Type: application/json`.