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
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());

    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

Examples

See the examples/ directory for more comprehensive usage examples:

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

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

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

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