REST API v1

API Reference

The AnalyticsPro REST API lets you programmatically ingest analytics data, query KPIs, manage alerts, and generate reports. All endpoints return JSON and require a Bearer token obtained via /api/v1/auth/login.

🔐

Sanctum Tokens

Per-user API tokens with configurable scopes. Tokens do not expire unless revoked.

⚡

Rate Limited

Auth: 10 req/min · Ingest: 30 req/min · Other: 60 req/min per token.

📦

JSON Only

All requests and responses use application/json. Always set Accept: application/json.

Authentication

After logging in, include the token in every request using the Authorization header.

# Include in every authenticated request
Authorization: Bearer YOUR_TOKEN_HERE
Accept:        application/json
Content-Type:  application/json

💡 Tip: Tokens are scoped per user. Deleting a user revokes all their tokens. Use /api/v1/auth/logout to revoke the current token programmatically.

Errors & Rate Limits

All errors return a consistent JSON structure. HTTP status codes follow REST conventions.

401

Unauthenticated — missing or invalid Bearer token

403

Forbidden — valid token but insufficient role/permission

404

Resource not found

422

Validation failed — check the errors object

429

Rate limit exceeded — back off and retry

500

Server error — contact support

// Error response shape (422 example)
{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."]
  }
}

Auth Endpoints

Register

Create a new user account and immediately receive a Sanctum token. Rate limited to 10 requests/minute.

POST /api/v1/auth/register Public · No token required

Field	Type	Required	Description
name	string	required	Full name, 2–100 chars
email	string	required	Unique email address
password	string	required	Min 8 chars
password_confirmation	string	required	Must match password

# Request
POST /api/v1/auth/register
{
  "name":                  "Jane Smith",
  "email":                 "jane@acme.com",
  "password":              "secret1234",
  "password_confirmation": "secret1234"
}

# 201 Response
{
  "user": { "id": 42, "name": "Jane Smith", "email": "jane@acme.com" },
  "token": "1|AbcXyzSanctumToken..."
}

Login

Authenticate with email & password to receive a Bearer token. Any previous tokens remain active.

POST /api/v1/auth/login Public · No token required

Field	Type	Required	Description
email	string	required	Registered email address
password	string	required	Account password

# Request
POST /api/v1/auth/login
{ "email": "jane@acme.com", "password": "secret1234" }

# 200 Response
{ "user": { ... }, "token": "1|AbcXyzSanctumToken..." }

Get Current User

Returns the authenticated user's profile, role, and permissions.

GET /api/v1/auth/me 🔒 Bearer token required

# 200 Response
{
  "id": 42,
  "name":  "Jane Smith",
  "email": "jane@acme.com",
  "roles": ["analyst"],
  "permissions": ["view-dashboard", "view-analytics", "manage-alerts"]
}

Logout

Revokes the current Bearer token. The token is immediately invalid.

DELETE /api/v1/auth/logout 🔒 Bearer token required

# 200 Response
{ "message": "Logged out successfully." }

Analytics Endpoints

List Analytics Data

Returns paginated raw analytics records. Filterable by metric and date range. Requires view-analytics permission.

GET /api/v1/analytics 🔒 view-analytics

Query Param	Type	Required	Description
metric_type	string	optional	Filter by metric: revenue, users, orders, conversion_rate, bounce_rate, session_duration, page_views
from	date	optional	Start date (Y-m-d)
to	date	optional	End date (Y-m-d)
per_page	integer	optional	Page size, default 30, max 100

GET /api/v1/analytics?metric_type=revenue&from=2025-01-01&per_page=10

# 200 Response
{
  "data": [
    { "id": 1, "metric_type": "revenue", "value": 4820.50, "recorded_at": "2025-01-01" },
    ...
  ],
  "meta": { "current_page": 1, "last_page": 9, "per_page": 10, "total": 87 }
}

Ingest Analytics Data

Push a new analytics data point. Triggers alert rule evaluation immediately. Rate limited to 30 req/min.

⚠️ After ingestion, alert rules run synchronously. If a threshold is breached, an alert is created and users are notified.

POST /api/v1/analytics 🔒 Bearer token · 30/min

Field	Type	Required	Description
metric_type	string	required	revenue · users · orders · conversion_rate · bounce_rate · session_duration · page_views
value	numeric	required	Decimal metric value
recorded_at	date	optional	Y-m-d, defaults to today
category	string	optional	Revenue category label
source	string	optional	Traffic source label

POST /api/v1/analytics
{ "metric_type": "revenue", "value": 5240.00, "recorded_at": "2025-03-01" }

# 201 Response
{
  "id": 901, "metric_type": "revenue",
  "value": "5240.00", "recorded_at": "2025-03-01",
  "alerts_triggered": 1
}

KPI Summary

Returns aggregated KPIs for the requested period vs previous period, with trend direction.

GET /api/v1/analytics/kpi?period=30 🔒 view-analytics · cached

Query Param	Type	Description
period	integer	7, 14, or 30 days. Default: 7

# 200 Response
{
  "revenue":         { "value": 128430.50, "label": "+12.4% vs prev period", "direction": "up" },
  "users":           { "value": 2418,      "label": "+5.1%",                  "direction": "up" },
  "orders":          { "value": 843,       "label": "-2.3%",                  "direction": "down" },
  "conversion_rate": { "value": 3.48,     "label": "+0.8%",                  "direction": "up" }
}

Chart Data

Returns time-series labels + data arrays for charting a single metric.

GET /api/v1/analytics/chart/{metric} 🔒 view-analytics

Param	Type	Description
metric (path)	string	revenue · users · orders · bounce_rate · session_duration · page_views
period	integer	7, 14, or 30 days

GET /api/v1/analytics/chart/revenue?period=7

# 200 Response
{
  "labels": ["Feb 23", "Feb 24", ..., "Mar 01"],
  "data":   [4820, 5120, 4980, 5340, 4910, 5580, 5240]
}

Revenue by Category

Returns revenue percentage breakdown per category for pie/donut charts.

GET /api/v1/analytics/categories

# 200 Response
{ "labels": ["Software", "Hardware", "Services"], "data": [42, 31, 27] }

Alert Endpoints

List Alerts

Returns paginated triggered alerts for the authenticated user. Filterable by status and severity.

GET /api/v1/alerts 🔒 manage-alerts

Query Param	Type	Description
status	string	unread · read · resolved
severity	string	critical · warning · info
per_page	integer	Default 20

# 200 Response
{
  "data": [{
    "id": 7, "severity": "critical", "status": "unread",
    "metric_type": "revenue", "message": "Revenue dropped below $3,000",
    "triggered_at": "2025-03-01T09:22:00Z"
  }],
  "meta": { "total": 14, "current_page": 1 }
}

Mark Alert as Read

Changes an alert's status from unread to read. Alert remains active.

PATCH /api/v1/alerts/{id}/read

# No body required
PATCH /api/v1/alerts/7/read

# 200 Response
{ "message": "Alert marked as read.", "alert": { "id": 7, "status": "read" } }

Resolve Alert

Marks an alert as resolved. Sets resolved_at timestamp and fires the alert-resolved event.

PATCH /api/v1/alerts/{id}/resolve

# 200 Response
{ "message": "Alert resolved.", "alert": { "id": 7, "status": "resolved", "resolved_at": "2025-03-01T10:05:00Z" } }

Alert Rule Endpoints

List Alert Rules

GET /api/v1/alert-rules

# 200 Response
{
  "data": [{
    "id": 1, "name": "Revenue Drop Alert",
    "metric_type": "revenue", "operator": "<",
    "threshold": 3000, "severity": "critical", "is_active": true
  }]
}

Create Alert Rule

Define a new threshold rule. Rules are evaluated on every data ingest.

POST /api/v1/alert-rules 🔒 manage-alerts

Field	Type	Required	Description
name	string	required	Descriptive rule name
metric_type	string	required	revenue · users · orders · conversion_rate · bounce_rate
operator	string	required	< · > · <= · >= · =
threshold	numeric	required	Trigger value
severity	string	required	critical · warning · info
is_active	boolean	optional	Default: true

POST /api/v1/alert-rules
{
  "name": "Low Conversion Warning", "metric_type": "conversion_rate",
  "operator": "<", "threshold": 2.5, "severity": "warning"
}

Delete Alert Rule

DELETE /api/v1/alert-rules/{id} 🔒 manage-alerts

# 200 Response
{ "message": "Alert rule deleted." }

Report Endpoints

List Reports

GET /api/v1/reports 🔒 view-reports

# 200 Response
{
  "data": [{
    "id": 12, "name": "Weekly Performance Q1", "type": "weekly",
    "status": "sent", "scheduled_at": "2025-03-04T08:00:00Z"
  }],
  "meta": { "total": 8 }
}

Create Report

Queues a new report for async generation. Initial status is draft.

POST /api/v1/reports 🔒 create-reports

Field	Type	Required	Description
name	string	required	Report display name
type	string	required	daily · weekly · monthly
scheduled_at	datetime	optional	ISO 8601, defaults to now

POST /api/v1/reports
{ "name": "March Weekly Report", "type": "weekly" }

# 201 Response
{ "id": 15, "name": "March Weekly Report", "type": "weekly", "status": "draft" }

Get Report

GET /api/v1/reports/{id} 🔒 view-reports

# 200 Response
{
  "id": 15, "name": "March Weekly Report",
  "type": "weekly", "status": "sent",
  "scheduled_at": "2025-03-04T08:00:00Z",
  "created_at":   "2025-03-04T07:55:10Z"
}

Delete Report

Permanently deletes a report. Requires delete-reports permission (Admin only).

DELETE /api/v1/reports/{id} 🔒 delete-reports

# 200 Response
{ "message": "Report deleted." }