Kavita

Kavita API

Configuration

All settings are loaded from the .env file in the workspace root.

KAVITA_HOST=http://localhost/kavita
KAVITA_USERNAME=your_username
KAVITA_PASSWORD=your_password
KAVITA_API_KEY=your_api_key

Reference

• Kavita API documentation: https://www.kavitareader.com/docs/api/
• Code Snippets: scripts/

Note: Scripts use config.py to load credentials from .env.

Available Scripts

| Script | Purpose | |--------|---------| | config.py | Configuration loader (from .env) | | list_libraries.py | List all libraries (JWT auth demo) | | get_library_books.py | Get all books/series from a library | | get_series_metadata.py | Detailed metadata (authors, genres, tags) | | dump_library_to_json.py | Export all books with full metadata | | scan_library.py | Trigger library rescan (supports force mode) |

Key Patterns

JWT Authentication

url = f"{SERVER_URL}/api/account/login"
payload = {"username": USERNAME, "password": PASSWORD}
response = requests.post(url, json=payload, timeout=10)
token = response.json().get('token')
headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}

Important: Library Filtering

libraryId must be a query parameter, not in the request body:

# Correct
params = {"libraryId": library_id, "PageNumber": 0, "PageSize": 0}
response = requests.post(f"{SERVER_URL}/api/series/all", headers=headers, params=params, json={})

# Wrong - returns ALL books from ALL libraries
response = requests.post(f"{SERVER_URL}/api/series/all", headers=headers, json={"libraryIds": [library_id]})

Usage Examples

cd skills/kavita/scripts
uv run python list_libraries.py
uv run python get_library_books.py
uv run python dump_library_to_json.py
uv run python scan_library.py

Notes

• Temporary files go in $WORKSPACE_PATH/temp/.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hevangel
• Source: hevangel/media-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.