Reclaimerr

https://jessielw.github.io/Reclaimerr/
Admin
Reclaimerr scans media libraries for eligible items, tracks protection and deletion requests, and...
Tokens:13,037
Snippets:177
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Start Frontend Development Server

Source: https://jessielw.github.io/Reclaimerr/getting-started/installation

Navigate to the frontend directory and start the development server using npm.

```bash
cd frontend
npm run dev

```

--------------------------------

### Install Reclaimerr from Source

Source: https://jessielw.github.io/Reclaimerr/getting-started/installation

Clone the repository, install Python dependencies using uv, and set up Node.js dependencies for frontend development.

```bash
git clone https://github.com/jessielw/Reclaimerr.git
cd Reclaimerr
uv sync
cd frontend
npm install
cd ..
uv run uvicorn --reload --reload-dir backend backend.api.main:app

```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://jessielw.github.io/Reclaimerr/development/contributing

Clone the Reclaimerr repository and install backend and frontend dependencies using uv and npm.

```bash
git clone https://github.com/jessielw/Reclaimerr.git
cd Reclaimerr
uv sync
cd frontend
npm install
cd ..

```

--------------------------------

### Example AND/OR Condition Group

Source: https://jessielw.github.io/Reclaimerr/usage/rules

This example demonstrates how to combine AND and OR groups to identify old, unwatched movies that are either large or have multiple versions. It uses specific numerical values for size and version count.

```plaintext
AND
  Never watched is true
  Days since added >= 180
  OR
    Size > 21474836480
    Movie version count > 1
```

--------------------------------

### Example Docker Compose Configuration

Source: https://jessielw.github.io/Reclaimerr/deployment/docker

A basic Docker Compose file to set up and run the Reclaimerr service. Ensure your .env file is in the same directory.

```yaml
services:
  reclaimerr:
    image: ghcr.io/jessielw/reclaimerr:latest
    container_name: reclaimerr
    restart: unless-stopped
    env_file: .env
    volumes:
      - ./data:/app/data
      - /media:/media
    ports:
      - "8000:8000"
```

--------------------------------

### Run Backend Development Server

Source: https://jessielw.github.io/Reclaimerr/development/contributing

Start the Reclaimerr backend API in development mode with automatic reloading.

```bash
uv run --reload --reload-dir backend backend.api.main:app

```

--------------------------------

### Create a Protection

Source: https://jessielw.github.io/Reclaimerr/reference/api

This example demonstrates how to create a protection for a media item, preventing both automatic and manual operations. It specifies the media type, TMDB ID, and a reason for the protection.

```curl
curl -X POST \
  -H "Authorization: Bearer $RECLAIMERR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"media_type":"movie","tmdb_id":550,"reason":"Keep for event"}' \
  "https://reclaimerr.example/api/v1/protections"

```

--------------------------------

### List Movies with Filters

Source: https://jessielw.github.io/Reclaimerr/reference/api

Example of how to list movies using the API, filtering by media type and TMDB ID. Ensure your bearer token has the necessary read scope.

```curl
curl -H "Authorization: Bearer $RECLAIMERR_TOKEN" \
  "https://reclaimerr.example/api/v1/candidates?media_type=movie&tmdb_id=550"

```

--------------------------------

### Cancel a Candidate with Idempotency

Source: https://jessielw.github.io/Reclaimerr/reference/api

This example shows how to cancel a candidate, suppressing automatic deletion. It includes an Idempotency-Key header for safe retries and specifies a reason for the action.

```curl
curl -X POST \
  -H "Authorization: Bearer $RECLAIMERR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: home-assistant-550-keep" \
  -d '{"reason":"Requester chose Keep"}' \
  "https://reclaimerr.example/api/v1/candidates/42/cancel"

```

--------------------------------

### Regex Example for Stale Tags

Source: https://jessielw.github.io/Reclaimerr/usage/rules

This example uses regex operators to select items that have a '-stale' variant but no active base tag. It combines 'matches_any_regex' to find stale variants and 'not_matches_any_regex' to exclude active tags.

```plaintext
AND
  matches_any_regex tag-.*-stale$
  not_matches_any_regex ^tag-.*(?<!-stale)$
```

--------------------------------

### Postpone a Candidate

Source: https://jessielw.github.io/Reclaimerr/reference/api

Example for postponing a candidate's automatic deletion until a specified time. This request requires the candidate ID and includes a reason for postponement.

```curl
curl -X POST \
  -H "Authorization: Bearer $RECLAIMERR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"until":"2026-08-15T12:00:00Z","reason":"Extended review period"}' \
  "https://reclaimerr.example/api/v1/candidates/42/postpone"

```

--------------------------------

### Run Desktop Development Mode

Source: https://jessielw.github.io/Reclaimerr/development/contributing

Execute the desktop application in development mode using uv.

```bash
uv run --extra desktop python -m desktop

```

--------------------------------

### Verify Backend Formatting with Ruff

Source: https://jessielw.github.io/Reclaimerr/development/contributing

Check backend code formatting without modifying files, mimicking CI behavior.

```bash
ruff format --check .

```

--------------------------------

### Frontend Code Style Check and Formatting

Source: https://jessielw.github.io/Reclaimerr/development/contributing

Check for and format frontend code using npm scripts.

```bash
npm run format
npm run check

```

--------------------------------

### Backend Code Style Check and Formatting

Source: https://jessielw.github.io/Reclaimerr/development/contributing

Check for and format backend code using Ruff. Ensure code is formatted before pushing.

```bash
ruff check .
ruff format .

```

--------------------------------

### Generate New Alembic Migration

Source: https://jessielw.github.io/Reclaimerr/development/migrations

Run this command after modifying backend/database/models.py to create a new migration script. Ensure you provide a descriptive message for the change.

```bash
uv run alembic revision --autogenerate -m "describe the change"
```

--------------------------------

### Changelog Release Heading Format

Source: https://jessielw.github.io/Reclaimerr/reference/changelog

Specifies the expected format for release entries in the CHANGELOG.md file.

```markdown
## [0.1.0] - 2026-06-02


```

--------------------------------

### Tasks and System Endpoints

Source: https://jessielw.github.io/Reclaimerr/reference/api

Endpoints for retrieving system status, task information, and triggering task runs.

```APIDOC
## GET /api/v1/system

### Description
Retrieves system information, including API version and capabilities.

### Method
GET

### Endpoint
/api/v1/system
```

```APIDOC
## GET /api/v1/tasks

### Description
Retrieves a list of all tasks, including their schedules and current state.

### Method
GET

### Endpoint
/api/v1/tasks
```

```APIDOC
## GET /api/v1/tasks/{task_id}

### Description
Retrieves details for a specific task.

### Method
GET

### Endpoint
/api/v1/tasks/{task_id}

### Parameters
#### Path Parameters
- **task_id** (integer) - Required - The ID of the task to retrieve.
```

```APIDOC
## GET /api/v1/tasks/{task_id}/runs

### Description
Retrieves the run history for a specific task.

### Method
GET

### Endpoint
/api/v1/tasks/{task_id}/runs

### Parameters
#### Path Parameters
- **task_id** (integer) - Required - The ID of the task for which to retrieve run history.
```

```APIDOC
## POST /api/v1/tasks/{task_id}/run

### Description
Triggers an enabled task to run immediately.

### Method
POST

### Endpoint
/api/v1/tasks/{task_id}/run

### Parameters
#### Path Parameters
- **task_id** (integer) - Required - The ID of the task to run.
```

--------------------------------

### API Discovery

Source: https://jessielw.github.io/Reclaimerr/reference/api

Retrieves API discovery links and the scopes granted to the current token. This is the entry point for integration clients.

```APIDOC
## GET /api/v1

### Description
Returns API discovery links and the scopes granted to the current token. Integration clients should use these versioned endpoints.

### Method
GET

### Endpoint
/api/v1
```

--------------------------------

### Candidate Endpoints

Source: https://jessielw.github.io/Reclaimerr/reference/api

Endpoints for managing candidate media items, including listing, retrieving details, canceling, postponing, resetting timers, and protecting candidates.

```APIDOC
## GET /api/v1/candidates

### Description
Lists candidate media items. Supports filtering by media type, TMDB ID, internal series ID, season or episode number, and auto-delete state.

### Method
GET

### Endpoint
/api/v1/candidates

### Parameters
#### Query Parameters
- **media_type** (string) - Optional - Filter by media type (movie, series).
- **tmdb_id** (integer) - Optional - Filter by TMDB ID.
- **series_id** (integer) - Optional - Filter by internal series ID.
- **season_number** (integer) - Optional - Filter by season number.
- **episode_number** (integer) - Optional - Filter by episode number.
- **state** (string) - Optional - Filter by auto-delete state.

### Request Example
```
curl -H "Authorization: Bearer $RECLAIMERR_TOKEN" \
  "https://reclaimerr.example/api/v1/candidates?media_type=movie&tmdb_id=550"
```
```

```APIDOC
## GET /api/v1/candidates/{candidate_id}

### Description
Retrieves details for a specific candidate media item.

### Method
GET

### Endpoint
/api/v1/candidates/{candidate_id}

### Parameters
#### Path Parameters
- **candidate_id** (integer) - Required - The ID of the candidate to retrieve.
```

```APIDOC
## POST /api/v1/candidates/{candidate_id}/cancel

### Description
Cancels a candidate, suppressing automatic deletion while it continuously qualifies. Does not prevent manual deletion by an administrator.

### Method
POST

### Endpoint
/api/v1/candidates/{candidate_id}/cancel

### Parameters
#### Path Parameters
- **candidate_id** (integer) - Required - The ID of the candidate to cancel.
#### Request Body
- **reason** (string) - Optional - The reason for cancellation.

### Request Example
```
curl -X POST \
  -H "Authorization: Bearer $RECLAIMERR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: home-assistant-550-keep" \
  -d '{"reason":"Requester chose Keep"}' \
  "https://reclaimerr.example/api/v1/candidates/42/cancel"
```
```

```APIDOC
## POST /api/v1/candidates/{candidate_id}/postpone

### Description
Postpones a candidate's automatic deletion for a specified period.

### Method
POST

### Endpoint
/api/v1/candidates/{candidate_id}/postpone

### Parameters
#### Path Parameters
- **candidate_id** (integer) - Required - The ID of the candidate to postpone.
#### Request Body
- **until** (string) - Required - The timestamp until which the candidate is postponed (ISO 8601 format).
- **reason** (string) - Optional - The reason for postponement.
```

```APIDOC
## POST /api/v1/candidates/{candidate_id}/reset-timer

### Description
Resets the timer for a candidate, effectively restarting its qualification period.

### Method
POST

### Endpoint
/api/v1/candidates/{candidate_id}/reset-timer

### Parameters
#### Path Parameters
- **candidate_id** (integer) - Required - The ID of the candidate to reset the timer for.
```

```APIDOC
## POST /api/v1/candidates/{candidate_id}/protect

### Description
Applies permanent protection to a candidate, blocking both automatic and manual operations.

### Method
POST

### Endpoint
/api/v1/candidates/{candidate_id}/protect

### Parameters
#### Path Parameters
- **candidate_id** (integer) - Required - The ID of the candidate to protect.
```

--------------------------------

### Common Environment Variables for Reclaimerr

Source: https://jessielw.github.io/Reclaimerr/deployment/docker

Essential environment variables for configuring Reclaimerr's data directory, API host and port, timezone, and proxy settings.

```dotenv
DATA_DIR=./data
API_HOST=0.0.0.0
API_PORT=8000
TZ=America/New_York
UMASK=022
PROXY_TRUSTED_HOSTS=127.0.0.1,::1
# Advanced; default 2, supported range 1-8
RECLAIMERR_COMMAND_WORKERS=2
```

--------------------------------

### Protections Endpoints

Source: https://jessielw.github.io/Reclaimerr/reference/api

Endpoints for managing media protections, including listing, retrieving, creating, and deleting protections.

```APIDOC
## GET /api/v1/protections

### Description
Retrieves a list of all media protections.

### Method
GET

### Endpoint
/api/v1/protections
```

```APIDOC
## GET /api/v1/protections/{protection_id}

### Description
Retrieves details for a specific protection.

### Method
GET

### Endpoint
/api/v1/protections/{protection_id}

### Parameters
#### Path Parameters
- **protection_id** (integer) - Required - The ID of the protection to retrieve.
```

```APIDOC
## POST /api/v1/protections

### Description
Creates a new media protection. Can target a movie, movie version, series, season, or episode. Omitting `expires_at` creates a permanent protection.

### Method
POST

### Endpoint
/api/v1/protections

### Parameters
#### Request Body
- **media_type** (string) - Required - The type of media to protect (movie, series, season, episode).
- **tmdb_id** (integer) - Optional - The TMDB ID of the root media item.
- **reclaimerr_id** (integer) - Optional - The Reclaimerr ID of the root media item.
- **season_id** (integer) - Optional - The ID of the season to protect.
- **episode_id** (integer) - Optional - The ID of the episode to protect.
- **expires_at** (string) - Optional - The timestamp when the protection expires (ISO 8601 format). If omitted, the protection is permanent.
- **reason** (string) - Optional - The reason for the protection.

### Request Example
```
curl -X POST \
  -H "Authorization: Bearer $RECLAIMERR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"media_type":"movie","tmdb_id":550,"reason":"Keep for event"}' \
  "https://reclaimerr.example/api/v1/protections"
```
```

```APIDOC
## DELETE /api/v1/protections/{protection_id}

### Description
Deletes a specific media protection.

### Method
DELETE

### Endpoint
/api/v1/protections/{protection_id}

### Parameters
#### Path Parameters
- **protection_id** (integer) - Required - The ID of the protection to delete.
```

--------------------------------

### Changelog Unreleased Entry Format

Source: https://jessielw.github.io/Reclaimerr/reference/changelog

Specifies the format for the unreleased changes section in the CHANGELOG.md file.

```markdown
## [Unreleased]


```

--------------------------------

### SWAG Reverse Proxy Configuration for Reclaimerr

Source: https://jessielw.github.io/Reclaimerr/deployment/swag

This Nginx configuration block is used for SWAG to proxy requests to the Reclaimerr application. It sets up SSL, defines the server name, and configures the upstream application details.

```nginx
server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name reclaimerr.*;

    include /config/nginx/ssl.conf;

    client_max_body_size 0;

    location / {
        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app reclaimerr;
        set $upstream_port 8000;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
    }
}

```

--------------------------------

### Media Endpoints

Source: https://jessielw.github.io/Reclaimerr/reference/api

Endpoints for accessing movie and series catalog information. Supports searching, filtering, and pagination.

```APIDOC
## GET /api/v1/movies

### Description
Retrieves a list of movies. Supports title search, canonical provider IDs, status, pagination, and sorting.

### Method
GET

### Endpoint
/api/v1/movies

### Parameters
#### Query Parameters
- **title** (string) - Optional - Search by movie title.
- **provider_id** (string) - Optional - Filter by canonical provider ID.
- **status** (string) - Optional - Filter by status.
- **page** (integer) - Optional - Page number for pagination.
- **sort** (string) - Optional - Sorting order (e.g., 'title.asc').
- **include_removed** (boolean) - Optional - Include removed items.
```

```APIDOC
## GET /api/v1/movies/{media_id}

### Description
Retrieves details for a specific movie.

### Method
GET

### Endpoint
/api/v1/movies/{media_id}

### Parameters
#### Path Parameters
- **media_id** (integer) - Required - The ID of the movie to retrieve.
```

```APIDOC
## GET /api/v1/series

### Description
Retrieves a list of series. Supports title search, canonical provider IDs, status, pagination, and sorting.

### Method
GET

### Endpoint
/api/v1/series

### Parameters
#### Query Parameters
- **title** (string) - Optional - Search by series title.
- **provider_id** (string) - Optional - Filter by canonical provider ID.
- **status** (string) - Optional - Filter by status.
- **page** (integer) - Optional - Page number for pagination.
- **sort** (string) - Optional - Sorting order (e.g., 'title.asc').
- **include_removed** (boolean) - Optional - Include removed items.
```

```APIDOC
## GET /api/v1/series/{media_id}

### Description
Retrieves details for a specific series.

### Method
GET

### Endpoint
/api/v1/series/{media_id}

### Parameters
#### Path Parameters
- **media_id** (integer) - Required - The ID of the series to retrieve.
```

--------------------------------

### API Authentication Header

Source: https://jessielw.github.io/Reclaimerr/reference/api

Use this header to authenticate your API requests with a bearer token. The token secret is provided by administrators and is displayed only once.

```http
Authorization: Bearer rcl_prefix_secret

```

--------------------------------

### Events Endpoint

Source: https://jessielw.github.io/Reclaimerr/reference/api

Retrieves the durable lifecycle event feed. Supports filtering and pagination to recover activity when an external automation was offline.

```APIDOC
## GET /api/v1/events

### Description
Retrieves the durable lifecycle event feed, ordered oldest-first. Supports filtering by event type, candidate ID, or occurrence time. Use `next_cursor` for pagination.

### Method
GET

### Endpoint
/api/v1/events

### Parameters
#### Query Parameters
- **event_type** (string) - Optional - Filter by event type.
- **candidate_id** (integer) - Optional - Filter by candidate ID.
- **start_time** (string) - Optional - Filter by occurrence start time (ISO 8601 format).
- **end_time** (string) - Optional - Filter by occurrence end time (ISO 8601 format).
- **cursor** (string) - Optional - The cursor for fetching the next page of results.
```

--------------------------------

### Sonarr Rule: Latest Season Has Unaired Episodes

Source: https://jessielw.github.io/Reclaimerr/usage/rules

Checks if the latest regular season of a series has any upcoming episodes. This condition relies on Sonarr's metadata and may be false if the finale metadata hasn't been updated.

```yaml
Latest season has unaired episodes is true

```

--------------------------------

### Sonarr Rule: Latest Season Has Finale

Source: https://jessielw.github.io/Reclaimerr/usage/rules

Checks if the latest regular season of a series is marked as a finale in Sonarr's metadata. This condition may remain false even if the season is incomplete or its finale metadata is not yet updated.

```yaml
Latest season has finale is false

```
Tokens:
Raw