yarr/yarr-api/README.md

yarr-api

A Rust client library for the Sonarr API.

Overview

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:

1. Base URL - The URL of your Sonarr instance (e.g., http://localhost:8989)
2. 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.

Related Projects

• yarr - TUI client for Sonarr built using this library