# Auto-Tagger Guide

The Auto-Tagger applies tags to your Sonarr and Radarr items based on rule criteria — the same 50+ rule type DSL used by [[Library Cleanup]], plus composite (AND/OR) rules and real-time tagging via Sonarr/Radarr Connect webhooks. Pair with [[Label Sync]] to mirror those tags onto Plex, Jellyfin, or Emby labels.

## Overview

Auto-Tagger automates what you would otherwise do manually: walking your library to apply consistent tags to items that match a definition (genre + year, watch state, custom format score, list membership, etc.).

The workflow follows three stages:

1. **Configure** — Define an Auto-Tag rule with a single rule type or a composite (AND/OR) of multiple conditions, and the tag name to apply
2. **Match** — Either the 5-minute scheduler tick walks your `LibraryCache` or a Sonarr/Radarr Connect webhook fires within seconds of an import event
3. **Apply** — The rule walks matched items and merges the tag into the source-side *arr (creating it if absent)

Tags written by Auto-Tagger are real *arr tags. They appear in Sonarr/Radarr, can be filtered on in those tools, and can drive other Sonarr/Radarr automations (custom format profile assignment, release profiles, notifications) just like any manually-applied tag.

---

## Getting Started

### Prerequisites

1. At least one **Sonarr** or **Radarr** instance configured in Settings (Lidarr is not yet supported)
2. (Optional) **Plex**, **Jellyfin/Emby**, **Tautulli**, or **Seerr** for cross-service rule criteria (e.g., "tag items that have Plex label X" or "tag items requested in Seerr by user Y")
3. (Optional, for TMDb list-membership rules) A **TMDb v3 read-access token** in Settings → Account
4. (Optional, for Trakt list-membership rules) A **Trakt personal access token** in Settings → Account, plus the operator-side `TRAKT_CLIENT_ID` env var

### Access the Auto-Tagger

1. Log in to Arr Dashboard
2. Click **Auto-Tag** in the sidebar (Maintenance section)
3. The page lists your existing rules with last-run status and a "Run now" button per rule, plus the webhook configuration panel

---

## How It Works

### Two Trigger Paths

Auto-Tagger rules can match items in two ways:

| Trigger | When | Latency |
|---------|------|---------|
| **Scheduler tick** | Every 5 minutes | Up to 5 minutes for new rules; subsequent passes respect a 60-minute per-rule cooldown |
| **Connect webhook** | Sonarr/Radarr fires on import-related events | Sub-second |

Both triggers use the same evaluation engine and apply the same tag merge logic. Webhooks are optional — without them, the scheduler still tags imports within ~5 minutes when the next library cache refresh runs.

### Scheduler Tick

A scheduler runs every 5 minutes and selects rules that are either:

- Never run (no `lastRunAt`), or
- Last run more than 60 minutes ago

For each due rule, the scheduler walks every item in the user's `LibraryCache` and evaluates the rule. Items that match get the rule's tag merged in via a single `series.update` or `movie.update` call per item.

### Per-Rule Lock

A per-rule mutex prevents two concurrent executions from racing. If you click "Run now" while the scheduler tick is mid-execution for the same rule, the second request returns HTTP 409 with the message "Rule is currently running — try again in a moment."

This matters because two concurrent `series.update` or `movie.update` calls perform a read-modify-write on the same `tags: number[]` array; without a lock, one rule's tag merge can clobber another's.

### Sonarr/Radarr Connect Webhook

Sonarr and Radarr can fire HTTP webhooks via their **Connect → Webhook** notification setting. Auto-Tagger exposes a public endpoint that receives those events and tags the imported item within seconds.

**Allowed event types** (anything else is acknowledged with HTTP 202 and ignored):

- `Download`, `Grab`, `Rename`, `Upgrade`
- `MovieFile.Import`, `MovieFile.Download`
- `ManualInteraction`, `ManualInteractionRequired`
- `Test` — acknowledged with no-op so you can verify the wiring

The webhook handler:

1. Authenticates via Bearer token (the user's hashed webhook secret)
2. Verifies the instance ID in the URL belongs to the authenticated user
3. Live-fetches the imported item from the *arr API (the LibraryCache row may not exist yet — sync runs every 6h, but Connect fires within seconds)
4. Evaluates every enabled rule whose scope includes the instance
5. Merges all matching rule tags into the item

#### One-click auto-install (2.18.2+)

You no longer need to hand-paste the URL and Bearer header into each *arr's Connect settings. Inside Settings → Auto-Tagger → **Real-time webhook**, the **Auto-install** sub-panel discovers your enabled Sonarr/Radarr instances and installs the canonical `arr-dashboard auto-tagger` Connect notification on selected instances in a single click.

**Prerequisites**

1. Click **Rotate secret** in the Real-time webhook panel — the plaintext is only displayed at generation time and is required for the install button to be enabled.
2. The instances you target must be **enabled** in Settings → Services. Disabled instances are excluded from the discovery list.

**What gets installed**

For each selected instance, the dashboard creates (or updates, on re-run) a Connect notification named `arr-dashboard auto-tagger` with:

- `implementation: Webhook`
- `url`: the auto-tag webhook URL with the instance ID baked in
- `headers`: `Authorization: Bearer <your-webhook-secret>`
- Event flags from the **Events** checkboxes (default: `onDownload` + `onUpgrade`, no `onGrab`)

**Idempotency**

The installer matches by notification name, so re-running it updates the existing entry instead of creating duplicates. Rotating the webhook secret invalidates the old Bearer header — re-run the install on every instance after rotation.

**Per-instance failures**

If an *arr is offline, has a stale API key, or otherwise rejects the create call, that instance reports its error inline (e.g. `401 Invalid API key`) without aborting the rest of the batch. The dashboard's Bearer secret is never sent for failed instances.

**URL resolution**

The installer prefers `SystemSettings.externalUrl` when set (System → Settings → External URL). If unset, it falls back to the request's protocol + hostname as observed by Fastify's `trustProxy`-aware request fields. If your dashboard is behind a reverse proxy, set `externalUrl` explicitly to avoid relying on `X-Forwarded-*` headers.

### Library Cache Dependency

Scheduled rule evaluation reads from `LibraryCache`. The cache is populated by background sync; rules will not match items until the cache contains them. Webhook-driven evaluation does not depend on the cache — it live-fetches the item directly.

---

## Configuration

### Creating a Rule

1. Click **Add Rule** on the Auto-Tag page
2. Give the rule a **Name** (shown in the rules list and in scheduler logs)
3. Pick a **Tag Name** — the tag to apply to matched items. Created on the *arr side automatically if it does not exist.
4. Configure a **Single criterion** OR a **Composite (AND/OR)** of conditions (see Rule Types below)
5. Optionally set **Scope filters** to narrow which items the rule sees:
   - **Service Filter** — Limit to Sonarr or Radarr only
   - **Instance Filter** — Limit to specific instances
   - **Exclude Tags** — Skip items that already carry one of these *arr tag IDs
   - **Exclude Titles** — Skip items whose title matches any of these regex patterns
   - **Plex Library Filter** — Limit to items in specific Plex sections (only meaningful for rules that depend on Plex data)
6. Toggle **Enabled** — disabled rules are skipped by both the scheduler and the webhook
7. Save the rule

### Composite (AND/OR) Rules

Composite rules combine multiple conditions with a single boolean operator. Examples:

- `Genre is "Anime" AND Audio Channels >= 6 AND Custom Format Score > 1000` → tag "Premium Anime"
- `Year >= 2020 AND HDR Type is HDR10 AND Plex Watch Count = 0` → tag "New 4K Unwatched"
- `tmdb_list_member is_in 8068 OR Plex Label is "Award Winner"` → tag "Awards"

Each condition uses the same parameter schema as its standalone rule type. Composite rules and single-criterion rules cannot be mixed in the same rule — switch the rule's mode in the dialog.

### Run Now

Each rule has a **Run now** button. This:

- Acquires the per-rule lock; returns HTTP 409 if a scheduler tick or another run is already executing this rule
- Walks every cached library item once
- Persists `lastRunAt`, `lastRunStatus` (`success` / `partial` / `failed`), and `lastRunMessage` (count summary or failure reason)

---

## Rule Types

The Auto-Tagger uses the same rule criteria DSL as [[Library Cleanup]]. See the [[Library Cleanup#Rule Types|Library Cleanup rule types reference]] for the full table covering Content Attributes, File Metadata, Seerr/Plex/Jellyfin/Tautulli integration rules, and Behavior-Aware rules.

In addition, Auto-Tagger ships with two **list-membership** rule types not yet exposed in Library Cleanup:

### List-Membership Rules

| Rule Type | Description | Key Parameters |
|-----------|-------------|----------------|
| **TMDb List Member** | Match items in a TMDb curated list | List ID (e.g., `8068`), Operator (`is_in` / `not_in`) |
| **Trakt List Member** | Match items in a Trakt curated list | List slug (e.g., `trakt-official/oscar-winners`), Operator (`is_in` / `not_in`) |

Both use cached membership tables refreshed every 4 hours by background schedulers. Lists referenced by enabled rules get refreshed; cache rows for unreferenced lists are garbage-collected.

**TMDb requirements:** A TMDb v3 read-access token in Settings → Account (the same token Discover uses). Public lists only — private list support would need TMDb v4 OAuth.

**Trakt requirements:** A per-user Trakt personal access token in Settings → Account, plus the operator-side `TRAKT_CLIENT_ID` env var (issued from `trakt.tv/oauth/applications`). Without `TRAKT_CLIENT_ID` set, the Trakt scheduler logs `"skipped — TRAKT_CLIENT_ID not configured"` and trakt rules will not match.

---

## Connect Webhook Setup

The webhook gives you sub-second tagging on import, instead of waiting up to 5 minutes for the scheduler tick.

### Generate the Webhook Secret

1. Open the **Webhook Configuration** panel on the Auto-Tag page
2. Click **Generate Secret** if no secret exists yet, or **Rotate Secret** to invalidate the old one
3. **Copy the plaintext secret immediately** — Arr Dashboard hashes it before storing, so the plaintext is shown only at generation or rotation. If you lose it, you must rotate to get a new one. (This is intentional: a database compromise no longer yields a usable webhook credential.)

### Configure Sonarr or Radarr

In your Sonarr or Radarr instance:

1. Go to **Settings → Connect → Add → Webhook**
2. Set **URL** to: `https://your-arr-dashboard-host/api/auto-tag/webhook/<INSTANCE_ID>`
   - Replace `<INSTANCE_ID>` with the instance's UUID from Arr Dashboard's Settings → Services page (shown next to each instance)
3. Set **Method** to `POST`
4. Add a custom header `Authorization: Bearer <your-webhook-secret>`
5. Enable the events you want to react to: **On Grab**, **On Import / On Download**, **On Upgrade**, **On Rename**, **On Manual Interaction Required** are all supported
6. Click **Test** — the webhook should return a 200 status with `{"status": "test", "message": "Test webhook received."}`
7. Save

### Webhook Response Codes

| Code | Meaning |
|------|---------|
| `200` | Event processed; check response body for tag application count |
| `202` | Event ignored (unsupported event type) |
| `400` | Bad payload, instance/payload type mismatch, or tag-update failure |
| `401` | Missing or invalid Bearer token |
| `404` | Instance not found, disabled, or not owned by the token's user |

Failed webhooks do not retry. If a Connect call fails, the next scheduler tick (within 5 minutes) will catch the item.

---

## Composition with Label Sync

Auto-Tagger writes tags to the source-side *arr (Sonarr or Radarr). To mirror those tags into Plex, Jellyfin, or Emby labels, pair with a [[Label Sync]] rule:

```
[Auto-Tagger]                       [Label Sync]
  Sonarr "Anime" tag      ──→        Plex "Anime" label
  Radarr "Premium" tag    ──→        Jellyfin "Premium" label
```

This split keeps the two engines simple. Auto-Tagger seeds the source-of-truth tag based on criteria. Label Sync propagates that tag to other services on its own cadence.

You can also use Auto-Tagger and Label Sync independently. Auto-Tagger is useful on its own if you only need *arr tags. Label Sync is useful on its own if you maintain tags manually in Sonarr/Radarr.

---

## Operations

### Status and Telemetry

Each rule row on the Auto-Tag page shows:

| Field | Meaning |
|-------|---------|
| **Last Run At** | Timestamp of the last execution (scheduled or on-demand) |
| **Last Run Status** | `success` (all matched items tagged), `partial` (some items failed), or `failed` (rule errored before any application) |
| **Last Run Message** | Count summary like `"Applied tag to 12 items across 2 instances"` or a failure reason |

### Operator Environment Variables

| Variable | Purpose | Required For |
|----------|---------|--------------|
| `TRAKT_CLIENT_ID` | Trakt API app credential | `trakt_list_member` rules |

TMDb list-membership has no operator-side env requirement — it uses the user's TMDb v3 token from Settings → Account.

### Public Routes

The inbound Connect webhook (`POST /api/auto-tag/webhook/:instanceId`) is mounted as a **public route** (no session cookie required). Authentication is the per-user Bearer token. All other Auto-Tagger endpoints require a session cookie like the rest of the app.

---

## Best Practices

### Start Small, Measure, Then Expand

Create one or two rules first, click **Run now**, and check the resulting tag count and `lastRunMessage`. Once you trust the rule's match set, enable additional rules.

### Use Composite Rules to Avoid Tag Storms

A single broad rule like `genre includes "Action"` may match thousands of items on the first run. Composite rules (`Genre is "Action" AND Year >= 2020 AND Custom Format Score > 500`) keep the match set targeted.

### Pair with Label Sync for Cross-Service Tagging

Don't write two rules — one in Auto-Tagger applying the Sonarr tag, one in Label Sync mirroring it to Plex — for two separate match sets. Use a single Auto-Tagger rule as the source of truth and let Label Sync propagate.

### Rotate the Webhook Secret if Logs Show Unexpected Calls

Bearer tokens in Connect webhook headers are visible to anyone with access to the Sonarr/Radarr config. If you suspect leakage, rotate via the Webhook Configuration panel — the old secret stops authenticating immediately.

### Use Exclude Tags as a Safety Net

Tag certain items in Sonarr/Radarr with a "no-auto-tag" tag and add that tag ID to every Auto-Tagger rule's **Exclude Tags** list. This gives you an opt-out per item without disabling the whole rule.

---

## Troubleshooting

### "Rule shows last_run_status: success but no tag was applied"

**Causes:**

- Items already carried the tag (the tag is merged additively, so re-running on items already tagged is a no-op)
- Rule criteria do not match any cached items
- Rule's scope filters exclude the instances containing matching items

**Solutions:**

1. Check `lastRunMessage` — it reports the application count, not just the match count
2. Use the [[Library Cleanup#Explain Feature|Explain]] feature on a known item to see whether the rule would match
3. Verify scope filters (service, instance, library) include the instances you expect

### "Webhook returns 401 Invalid or missing webhook secret"

**Causes:**

- The Bearer token in the Connect header is wrong or has been rotated
- The Authorization header is missing or malformed (must be exactly `Authorization: Bearer <token>`)
- The token is shorter than 16 characters (rejected outright as malformed)

**Solutions:**

1. Open the Webhook Configuration panel and rotate the secret to get a fresh one
2. Copy the plaintext value directly into the Sonarr/Radarr Webhook custom header
3. Test with the Sonarr/Radarr "Test" button before saving

### "Webhook returns 404 Instance not found or disabled"

**Causes:**

- The `<INSTANCE_ID>` in the URL is wrong
- The instance is disabled in Settings → Services
- The instance belongs to a different user

**Solutions:**

1. Check Settings → Services and copy the exact instance UUID
2. Confirm the instance is enabled
3. Confirm you generated the webhook secret as the same user that owns the instance

### "Webhook returns 400 with payload type mismatch"

**Cause:** The Sonarr Connect webhook is pointing at a Radarr instance ID (or vice versa). The webhook payload contains a `series` object but the URL targets a Radarr instance.

**Solution:** Each instance gets its own webhook URL. Configure Sonarr Connect to target a Sonarr instance ID and Radarr Connect to target a Radarr instance ID.

### "Trakt rules show no matches"

**Causes:**

- `TRAKT_CLIENT_ID` env var not set in the API process — Trakt scheduler skips with a one-line log notice
- Trakt PAT not configured in Settings → Account
- List slug uses a wrong format (must be `username/list-slug`, e.g., `trakt-official/oscar-winners`)
- Cache has not refreshed yet — first refresh takes up to 4 hours after the rule is created

**Solutions:**

1. Confirm `TRAKT_CLIENT_ID` is in the API container's environment
2. Add the Trakt PAT in Settings → Account
3. Verify the list slug is in `username/list-slug` form
4. Wait for the next 4-hour refresh, or restart the API to fire the startup tick

### "TMDb rules show no matches"

**Causes:**

- TMDb v3 token not configured in Settings → Account
- List ID is wrong (TMDb list IDs are integers like `8068`, not URL slugs)
- The TMDb list is private (only public lists work in v1)

**Solutions:**

1. Confirm the TMDb v3 token in Settings → Account is the same one used by Discover
2. Use the numeric list ID from the TMDb URL
3. Use a public list

### "Rule is currently running" (HTTP 409 on Run Now)

**Cause:** A scheduler tick or a concurrent on-demand run is already executing this rule. The per-rule lock prevents racing.

**Solution:** Wait a moment and retry. Scheduled ticks complete in seconds for most rules.

---

## API Reference

All endpoints require a session cookie except `POST /api/auto-tag/webhook/:instanceId`, which uses Bearer-token authentication.

### List Rules

```
GET /api/auto-tag/rules
```

Returns the user's rules sorted by `createdAt` descending.

### Create Rule

```
POST /api/auto-tag/rules
Content-Type: application/json

{
  "name": "Premium Anime",
  "enabled": true,
  "ruleType": "composite",
  "operator": "AND",
  "conditions": [
    { "ruleType": "genre", "parameters": { "operator": "includes_any", "genres": ["Anime"] } },
    { "ruleType": "audio_channels", "parameters": { "operator": "greater_than_or_equal", "channels": 6 } }
  ],
  "tagName": "premium-anime",
  "serviceFilter": ["sonarr"]
}
```

For single-criterion rules, set `ruleType` to the rule type and `parameters` to its parameters; omit `operator` and `conditions`.

### Update Rule

```
PATCH /api/auto-tag/rules/:id
Content-Type: application/json

{ "enabled": false }
```

Any subset of fields can be updated. The validator re-evaluates the post-PATCH composite-vs-leaf shape and rejects mode mismatches.

### Delete Rule

```
DELETE /api/auto-tag/rules/:id
```

### Run Rule On Demand

```
POST /api/auto-tag/rules/:id/run
```

Returns the updated rule with `lastRunAt`, `lastRunStatus`, `lastRunMessage`. Returns HTTP 409 if the rule is already executing.

### Get Webhook Configuration

```
GET /api/auto-tag/webhook-config
```

Returns `{ secret: "...", configured: true, freshlyGenerated: true }` on the first-ever access (the secret is generated lazily). On subsequent accesses returns `{ secret: null, configured: true, freshlyGenerated: false }` — the plaintext is not stored, only its SHA-256 hash.

### Rotate Webhook Secret

```
POST /api/auto-tag/webhook-config/regenerate
```

Generates a new 256-bit secret, stores its hash, and returns the plaintext once. Invalidates the old secret immediately.

### Inbound Connect Webhook

```
POST /api/auto-tag/webhook/:instanceId
Authorization: Bearer <your-webhook-secret>
Content-Type: application/json

(Sonarr or Radarr Connect payload)
```

Public endpoint — no session cookie required. The Bearer token resolves to the user; the path's `instanceId` must reference an enabled instance owned by that user.

Returns:

```json
{
  "status": "ok",
  "message": "Applied 2 tags from 2 rules.",
  "tagsApplied": 2,
  "rulesEvaluated": 2
}
```