yarr-api provides a strongly-typed, async Rust client for interacting with Sonarr instances. It handles authentication, request/response serialization, and provides convenient methods for all major Sonarr API endpoints.

Features

Async/await support - Built on tokio and reqwest
Type-safe API - All API responses are strongly typed with serde
Error handling - Comprehensive error types with detailed error information
Easy to use - Simple client interface with intuitive method names
Download after search - Search for releases and automatically download the best quality
Release management - Full support for searching, filtering, and downloading releases
Well documented - Extensive documentation and examples

Installation

Add this to your Cargo.toml:

[dependencies]
yarr-api = "0.1.0"

Quick Start

use yarr_api::{SonarrClient, Result};

#[tokio::main]
async fn main() -> Result<()> {
    // Create a client
    let client = SonarrClient::new(
        "http://localhost:8989".to_string(),
        "your-api-key".to_string()
    );

    // Get system status
    let status = client.get_system_status().await?;
    println!("Sonarr version: {}", status.version.unwrap_or_default());

    // Get all series
    let series = client.get_series().await?;
    println!("Total series: {}", series.len());

    // Get download queue
    let queue = client.get_queue().await?;
    println!("Items in queue: {}", queue.records.len());

    // Search and download the best release for a series
    let downloaded = client.search_and_download_best(Some(1), None, None).await?;
    if let Some(release) = downloaded {
        println!("Downloaded: {}", release.title.unwrap_or_default());
    }

    Ok(())
}

API Coverage

System

✅ System status
✅ Health check

Series Management

✅ List all series
✅ Get series by ID
✅ Search for series
✅ Add new series

Episodes

✅ Get episodes for series/season
✅ Get calendar (upcoming episodes)
✅ Get missing episodes

Downloads

✅ Get download queue
✅ Get download history

Releases

✅ Search for releases by series/episode/season
✅ Download specific releases
✅ Automatic best quality selection
✅ Advanced filtering and sorting

Examples

See the examples/ directory for more comprehensive usage examples:

# Run the basic usage example
cargo run --example basic_usage

# Run the download after search example
cargo run --example download_after_search

# Make sure to set your Sonarr URL and API key first:
export SONARR_URL="http://localhost:8989"
export SONARR_API_KEY="your-api-key-here"

Download After Search

The library provides powerful functionality for searching and automatically downloading releases:

use yarr_api::SonarrClient;

let client = SonarrClient::new(url, api_key);

// Search and download the first available release
let success = client.search_and_download(Some(series_id), None, None).await?;

// Search and download the best quality release
let best_release = client.search_and_download_best(Some(series_id), None, Some(season)).await?;

// Manual search with custom filtering
let releases = client.search_releases(Some(series_id), Some(episode_id), None).await?;
for release in releases {
    if release.download_allowed.unwrap_or(false) && !release.rejected.unwrap_or(true) {
        client.download_release(&release).await?;
        break;
    }
}

Error Handling

The library uses a custom ApiError type that provides detailed error information:

use yarr_api::{SonarrClient, ApiError};

let client = SonarrClient::new(url, api_key);

match client.get_series().await {
    Ok(series) => println!("Found {} series", series.len()),
    Err(ApiError::Authentication) => println!("Invalid API key"),
    Err(ApiError::NotFound) => println!("Endpoint not found"),
    Err(ApiError::ServerError) => println!("Sonarr server error"),
    Err(e) => println!("Other error: {}", e),
}

Configuration

The client requires two pieces of information:

Base URL - The URL of your Sonarr instance (e.g., http://localhost:8989)
API Key - Your Sonarr API key (found in Settings > General > Security)

Data Types

All Sonarr API responses are represented as strongly-typed Rust structs:

SystemStatus - System information and status
Series - TV series information
Episode - Episode details
QueueItem - Download queue items
HistoryItem - Download history
HealthResource - Health check results
ReleaseResource - Release/torrent information with download metadata
QualityModel - Quality information and settings
CustomFormatResource - Custom format definitions

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

yarr - TUI client for Sonarr built using this library

README.md

yarr-api

Overview