Watcharr-JF-sync.md

Feature Request / Documentation: Automate Jellyfin Sync via API

I spent some time with GPT to figure out how to automate the jellyfin sync feature. This is what I got. It is working for me.

Below is GPT's summary of what we did to make it work.

Many users want an automated way to keep Watcharr's Jellyfin watch status in sync without manually clicking the "Sync w Jellyfin" button.

---

How to automate Jellyfin sync with Watcharr's API

What works

Watcharr exposes an API endpoint to trigger a Jellyfin sync:

GET /api/jellyfin/sync

This endpoint starts a sync job and returns a JSON response with a jobId if successful:

{"jobId": "some-unique-id"}

You can optionally query the job status using:

GET /api/job/{jobId}/status

to check if the sync job is running, completed, or failed.

---

Why this works

• The /api/jellyfin/sync endpoint triggers a background job inside Watcharr to fetch the current watch status from Jellyfin.
• The returned jobId is your handle to track the progress asynchronously.
• This API is the same one the frontend UI uses when you press the manual sync button.

---

Important caveats

• Authentication: The API requires an Authorization header with a JWT token. Without it, you will get a 404 page or unauthorized response.

• Finding your JWT token:

  1. Open Watcharr in your browser and log in.
  2. Open Developer Tools (F12), go to the Network tab.
  3. Click the Sync w Jellyfin button.
  4. Find the request to /api/jellyfin/sync.
  5. Inspect the request headers for an Authorization header.
  6. Copy the token string (without the Bearer prefix).

• Token lifetime:

  • Currently, Watcharr's JWT token does not refresh automatically.
  • The token may expire or be revoked depending on your server config.
  • If expired, you must manually update the token in your automation scripts.

---

Example curl command to trigger sync

curl -X GET "http://your-watcharr-server:3080/api/jellyfin/sync" \
  -H "Authorization: <your-jwt-token>"

Expected response:

{"jobId":"some-unique-job-id"}

---

Automating with a cron job (example script)

#!/bin/bash
BASE="http://your-watcharr-server:3080"
AUTH="<your-jwt-token>"

# Trigger sync
JOB_JSON=$(curl -s -X GET "$BASE/api/jellyfin/sync" -H "Authorization: $AUTH")
JOBID=$(echo "$JOB_JSON" | jq -r .jobId)
echo "$(date): Sync triggered, jobId=$JOBID"

# Optionally poll status after delay
sleep 60
STATUS_JSON=$(curl -s -X GET "$BASE/api/job/$JOBID/status" -H "Authorization: $AUTH")
STATUS=$(echo "$STATUS_JSON" | jq -r .status)
echo "$(date): Job $JOBID status: $STATUS"

---

Summary

• This API approach mimics what the UI does but can be automated via cron or other schedulers.
• Keep your JWT token updated to maintain authentication.
• If Watcharr adds token refresh or API keys in the future, this method will become even more robust.

---

If you want, I can help create a wiki page or PR with this info for Watcharr's docs!