# API Documentation

The MusicAnalyser Backend is built with FastAPI. It provides endpoints for data ingestion, listening history retrieval, and AI-powered analysis.

## Base URL
Default local development: `http://localhost:8000`
Docker environment: Proxied via Nginx at `http://localhost:8991/api`

---

## Endpoints

### 1. Root / Health Check
- **URL**: `/`
- **Method**: `GET`
- **Response**:
  ```json
  {
    "status": "ok",
    "message": "Music Analyser API is running"
  }
  ```

### 2. Get Recent History
Returns a flat list of recently played tracks.
- **URL**: `/history`
- **Method**: `GET`
- **Query Parameters**:
  - `limit` (int, default=50): Number of items to return.
- **Response**: List of PlayHistory objects with nested Track data.

### 3. Get Tracks
Returns a list of unique tracks in the database.
- **URL**: `/tracks`
- **Method**: `GET`
- **Query Parameters**:
  - `limit` (int, default=50): Number of tracks to return.

### 4. Trigger Spotify Ingestion
Manually triggers a background task to poll Spotify for recently played tracks.
- **URL**: `/trigger-ingest`
- **Method**: `POST`
- **Response**:
  ```json
  {
    "status": "Ingestion started in background"
  }
  ```

### 5. Trigger Analysis Pipeline
Runs the full stats calculation and AI narrative generation for a specific timeframe.
- **URL**: `/trigger-analysis`
- **Method**: `POST`
- **Query Parameters**:
  - `days` (int, default=30): Number of past days to analyze.
  - `model_name` (str): LLM model to use.
- **Response**:
  ```json
  {
    "status": "success",
    "snapshot_id": 1,
    "period": { "start": "...", "end": "..." },
    "metrics": { ... },
    "narrative": { ... }
  }
  ```

### 6. Get Analysis Snapshots
Retrieves previously saved analysis reports.
- **URL**: `/snapshots`
- **Method**: `GET`
- **Query Parameters**:
  - `limit` (int, default=10): Number of snapshots to return.

### 7. Detailed Listening Log
Returns a refined listening log with skip detection and listening duration calculations.
- **URL**: `/listening-log`
- **Method**: `GET`
- **Query Parameters**:
  - `days` (int, 1-365, default=7): Timeframe.
  - `limit` (int, 1-1000, default=200): Max plays to return.
- **Response**:
  ```json
  {
    "plays": [
      {
        "id": 123,
        "track_name": "Song Name",
        "artist": "Artist Name",
        "played_at": "ISO-TIMESTAMP",
        "listened_ms": 180000,
        "skipped": false,
        "image": "..."
      }
    ],
    "period": { "start": "...", "end": "..." }
  }
  ```

### 8. Session Statistics
Groups plays into listening sessions (Marathon, Standard, Micro).
- **URL**: `/sessions`
- **Method**: `GET`
- **Query Parameters**:
  - `days` (int, 1-365, default=7): Timeframe.
- **Response**:
  ```json
  {
    "sessions": [
      {
        "start_time": "...",
        "end_time": "...",
        "duration_minutes": 45,
        "track_count": 12,
        "type": "Standard"
      }
    ],
    "summary": {
      "count": 10,
      "avg_minutes": 35,
      "micro_rate": 0.1,
      "marathon_rate": 0.05
    }
  }
  ```