Story Models Predictions API Database
Chapter IV

API Reference

The language AURA speaks — 50+ endpoints, one unified intelligence

Every prediction, every insight, every recommendation flows through a clean RESTful interface. JSON in, intelligence out. All endpoints return structured responses with consistent error handling.

Base URL http://localhost:5000

Health Logs

Daily health metrics — the primary data source for all AI predictions.

GET /api/health-logs Paginated

Retrieve all health logs. Supports pagination, date filtering, and sort order.

Query Parameters
pageinteger, default 1
per_pageinteger, default 20, max 100
sort_orderasc | desc, default desc
start_dateYYYY-MM-DD
end_dateYYYY-MM-DD
Response 200
{
  "logs": [{
    "id": 184,
    "date": "2026-05-13",
    "mood": 7.5,
    "energy": 8.0,
    "stress": 3.5
  }],
  "total": 184,
  "page": 1
}
POST /api/health-logs

Create a new daily health log entry. Triggers model retraining if threshold reached.

Request Body
{
  "date": "2026-05-13",
  "mood": 7.5,
  "energy": 8.0,
  "stress": 3.5,
  "sleep_hours": 7.5,
  "exercise_type": "running",
  "exercise_minutes": 45,
  "water_intake_ml": 2400
}
Response 201
{
  "id": 185,
  "message": "Health log created",
  "retrained": false
}
PATCH /api/health-logs/:id

Update specific fields of an existing health log.

DELETE /api/health-logs/:id

Permanently delete a health log entry.

Activity Logs

Real-time activity tracking with before/after energy measurements.

GET /api/activity-logs Paginated

Retrieve activity logs. Filter by category, date range, or activity name.

Query Parameters
categoryexercise | work | social | rest
activitystring, partial match
pageinteger
Response 200
{
  "logs": [{
    "activity": "Morning Run",
    "energy_before": 6.0,
    "energy_after": 8.5,
    "duration_minutes": 45
  }]
}
POST /api/activity-logs

Log a completed activity with before/after energy measurements.

AI & Predictions

The intelligence layer — train models, generate predictions, analyze influence.

POST /api/train Requires 5+ logs

Train all five AI models on current health log data. Returns performance metrics.

Response 200
{
  "status": "trained",
  "samples": 146,
  "metrics": {
    "rmse": 0.84,
    "mae": 0.67,
    "r2": 0.82
  }
}
POST /api/predict

Generate predictions for all 8 prediction types using current data.

Response 200
{
  "energy_tomorrow": 7.8,
  "mood_tomorrow": 7.2,
  "burnout_risk": 0.18,
  "performance_index": 0.74,
  "recovery_needed": false,
  "optimal_activity_time": "09:00-11:00"
}
POST /api/influence

Analyze causal influence between variables using the Bayesian Network.

Request Body
{
  "variable": "sleep_hours",
  "change": +1.5
}
Response 200
{
  "direct_effects": {
    "energy": +1.2,
    "mood": +0.8
  },
  "indirect_effects": {
    "stress": -0.6
  }
}
GET /api/patterns

Retrieve discovered behavioral patterns, correlations, and anomalies.

Goals & Habits

AI-powered goal decomposition and habit tracking.

GET /api/goals

Retrieve all active goals with AI-generated milestones and progress tracking.

POST /api/goals

Create a new goal. AURA automatically decomposes it into actionable milestones.

Request Body
{
  "title": "Improve sleep quality",
  "target_metric": "sleep_hours",
  "target_value": 8.0,
  "deadline": "2026-06-01"
}
GET /api/habits

Retrieve habit tracking data with streak information and completion rates.

Notifications

Intelligent alerts triggered by AI-detected patterns and thresholds.

GET /api/notifications

Retrieve pending and historical notifications with read status.

PATCH /api/notifications/:id/read

Mark a notification as read.