nfoguard/API_ENDPOINTS.md

NFOGuard API Endpoints

Health & Status Endpoints

GET /health

Health check endpoint with comprehensive status information.

Example:

curl http://localhost:8080/health

Response:

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

curl http://localhost:8080/stats

GET /batch/status

Current batch processing queue status.

Example:

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:

# 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:

# 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:

# 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:

# 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:

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

Environment Setup for Testing

For PostgreSQL (Recommended):

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:

RADARR_DB_TYPE=sqlite
RADARR_DB_PATH=/config/radarr.db

Performance Testing Workflow

1. Test your existing command (should now use database if configured):

   curl http://localhost:8080/debug/movie/tt1674782
   

2. Check health to verify database connectivity:

   curl http://localhost:8080/health
   

3. Run performance comparison:

   python test_db_performance.py
   

4. Test webhook simulation with a movie in your library:

   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.