MusicAnalyser/docs/API.md

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:

  {
    "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:

  {
    "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:

  {
    "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:

  {
    "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:

  {
    "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
    }
  }