nfoguard/API_ENDPOINTS.md

# NFOGuard API Endpoints

## Health & Status Endpoints

### GET `/health`
Health check endpoint with comprehensive status information.

**Example:**
```bash
curl http://localhost:8080/health
```

**Response:**
```json
{
  "status": "healthy",
  "version": "0.5.0",
  "uptime": "0:15:23.456789",
  "database_status": "healthy",
  "radarr_database": {
    "status": "healthy",
    "database_type": "postgresql",
    "connection": "readable",
    "readable": true,
    "tables_exist": true,
    "sample_data": true,
    "functional": true,
    "movie_count": 1250,
    "history_count": 5847,
    "movies_with_imdb": 1248,
    "connection_info": {
      "type": "postgresql",
      "host": "postgres",
      "port": 5432,
      "database": "radarr-main"
    },
    "tested_at": "2025-09-08T17:30:15+00:00"
  }
}
```

### GET `/stats`
Database statistics for NFOGuard's internal database.

**Example:**
```bash
curl http://localhost:8080/stats
```

### GET `/batch/status`
Current batch processing queue status.

**Example:**
```bash
curl http://localhost:8080/batch/status
```

## Debug & Testing Endpoints

### GET `/debug/movie/{imdb_id}`
**Primary testing endpoint** - Debug movie import date detection for a specific IMDb ID.

**Examples:**
```bash
# Test with your existing command
curl http://localhost:8080/debug/movie/tt1674782

# Test other movies
curl http://localhost:8080/debug/movie/tt1596343  # Fast & Furious 6
curl http://localhost:8080/debug/movie/tt0468569  # The Dark Knight
```

**Response includes:**
- Movie lookup results (database vs API)
- Import date detection with performance metrics
- Source information (radarr:db.history.import vs radarr:api.history.import)
- Fallback chain details

### GET `/debug/movie/{imdb_id}/history`
Detailed history analysis for a movie (if available in your version).

## Webhook Endpoints

### POST `/webhook/radarr`
Radarr webhook endpoint for real-time processing.

**Test webhook manually:**
```bash
# Simulate a Radarr Download event
curl -X POST http://localhost:8080/webhook/radarr \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "Download",
    "movie": {
      "id": 123,
      "imdbId": "tt1674782",
      "title": "The Hobbit: An Unexpected Journey",
      "year": 2012
    },
    "movieFile": {
      "path": "/movies/The Hobbit An Unexpected Journey (2012) [imdb-tt1674782]/The Hobbit An Unexpected Journey (2012).mkv"
    }
  }'
```

### POST `/webhook/sonarr`
Sonarr webhook endpoint for TV shows.

**Test webhook manually:**
```bash
# Simulate a Sonarr Download event
curl -X POST http://localhost:8080/webhook/sonarr \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "Download",
    "series": {
      "imdbId": "tt0944947",
      "title": "Game of Thrones"
    },
    "episodes": [{
      "seasonNumber": 1,
      "episodeNumber": 1
    }]
  }'
```

## Manual Processing Endpoints

### POST `/manual/scan`
Trigger manual library scans.

**Examples:**
```bash
# Scan everything
curl -X POST "http://localhost:8080/manual/scan?scan_type=both"

# Scan only movies
curl -X POST "http://localhost:8080/manual/scan?scan_type=movies"

# Scan only TV shows
curl -X POST "http://localhost:8080/manual/scan?scan_type=tv"

# Scan specific path
curl -X POST "http://localhost:8080/manual/scan?path=/media/movies"
```

## Testing Database Performance

### Run Performance Tests
Use the included test script to compare database vs API performance:

```bash
# Inside NFOGuard container or with proper environment
python test_db_performance.py
```

### Environment Setup for Testing

**For PostgreSQL (Recommended):**
```env
RADARR_DB_TYPE=postgresql
RADARR_DB_HOST=postgres_host
RADARR_DB_PORT=5432
RADARR_DB_NAME=radarr-main
RADARR_DB_USER=postgres
RADARR_DB_PASSWORD=your_password
```

**For SQLite:**
```env
RADARR_DB_TYPE=sqlite
RADARR_DB_PATH=/config/radarr.db
```

## Performance Testing Workflow

1. **Test your existing command** (should now use database if configured):
   ```bash
   curl http://localhost:8080/debug/movie/tt1674782
   ```

2. **Check health** to verify database connectivity:
   ```bash
   curl http://localhost:8080/health
   ```

3. **Run performance comparison**:
   ```bash
   python test_db_performance.py
   ```

4. **Test webhook simulation** with a movie in your library:
   ```bash
   curl -X POST http://localhost:8080/webhook/radarr \
     -H "Content-Type: application/json" \
     -d '{
       "eventType": "Download",
       "movie": {"imdbId": "tt1674782", "title": "Test Movie"},
       "movieFile": {"path": "/path/to/movie.mkv"}
     }'
   ```

## Expected Performance Improvements

With database access enabled, you should see:
- **Movie lookups**: 5-10x faster
- **Import date detection**: 10-20x faster  
- **Bulk operations**: 50x+ faster
- **Reduced API calls**: 90%+ reduction
- **Log output**: Much cleaner, fewer "pages and pages" messages

## Troubleshooting

If database access fails, NFOGuard automatically falls back to API methods. Check the logs for:
- `"Enhanced performance mode: Direct database access enabled"` (success)
- `"Failed to initialize database client, using API fallback"` (fallback)

The `/health` endpoint will show detailed database status and any connection issues.