API

Authentication

For writing custom scripts that access Kavita's API, you will need to authenticate against the API first. You can do this by sending a POST request to the /api/Plugin/authenticate (opens in a new tab) endpoint with an API key. It will return a JWT User Token that you can send in all your headers going forward.

You don't want to directly use JWT tokens in your scripts. They expire and rotate out on a frequent basis. API keys do not expire and only change if the user manually requests a new key.

Using the API key will always give you a valid JWT token.

Swagger UI

Kavita's REST API is documented using Swagger, however, the UI is disabled for non-dev instances. You can see Kavita's API Docs (opens in a new tab) on the main Kavita website.

OpenAPI

The link to the OpenAPI file is located here: https://raw.githubusercontent.com/Kareadita/Kavita/develop/openapi.json (opens in a new tab)

Python Example

Here's a small example written in Python for connecting to the /api/Plugin/authenticate endpoint, sending the API key, taking the 'token' response to add to the headers, then hitting the scan_endpoint with the JWT_Token attached in the headers.

import requests
import json
from urllib.parse import urlparse
 
url = input("Paste in your full ODPS URL from your Kavita user dashboard (/preferences#clients): ")
 
parsed_url = urlparse(url)
 
host_address = parsed_url.scheme + "://" + parsed_url.netloc
api_key = parsed_url.path.split('/')[-1]
 
login_endpoint = "/api/Plugin/authenticate"
try:
    apikeylogin = requests.post(host_address + login_endpoint + "?apiKey=" + api_key + "&pluginName=pythonScanScript")
    apikeylogin.raise_for_status() # check if the response code indicates an error
    jwt_token = apikeylogin.json()['token']
except requests.exceptions.RequestException as e:
    print("Error during authentication:", e)
    exit()
 
headers = {
    "Authorization": f"Bearer {jwt_token}",
    "Content-Type": "application/json"
}
scan_endpoint = "/api/Library/scan-all"
response = requests.post(host_address + scan_endpoint, headers=headers)

OPDS FAQ