Kavita Plugin API

The Plugin API from Kavita — 5 operation(s) for plugin.

GitHub OpenAPI

Operations 5

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

POST /api/Plugin/authenticate Authenticate a plugin with Kavita · Authenticate with the Server given an auth key. #
Ask an LLM
“How does a plugin authenticate against the Kavita server?”
“What do I need to send to get a user token from a plugin?”
Tell an agent
Authenticate plugin {pluginName} with auth key {apiKey}.
Log in the {pluginName} plugin using auth key {apiKey}.
GET /api/Plugin/version Get the Kavita server version · Returns the version of the Kavita install #
Ask an LLM
“Which version of Kavita is my server running?”
“Can I check the Kavita install version from a plugin?”
Tell an agent
Get the Kavita server version.
Show which Kavita version this install is on.
GET /api/Plugin/authkey-expires Check when the plugin auth key expires · Returns the expiration (UTC) of the authenticated Auth key (or null if none set) #
Ask an LLM
“When does the auth key my plugin uses expire?”
“Is there a way to see how long my plugin auth key lasts?”
Tell an agent
Show when my plugin's auth key expires.
Check the expiry of the auth key used by this plugin.
GET /api/Plugin/parse Parse a media name into its parts · Parse a string and return Parsed information from it. #
Ask an LLM
“How do I break a media title like 'Naruto S01E01' into its show, season and episode?”
“Can I parse a name against a library type's pattern?”
Tell an agent
Parse {name} as a {libraryType} title.
Break {name} into its parsed components.
POST /api/Plugin/parse-bulk Parse many media names at once · Create api plugin parse bulk #
Ask an LLM
“Can I parse a whole list of media titles in one request?”
“Is there a bulk parse for a comic or manga library type?”
Tell an agent
Parse {names} as {libraryType} titles.
Bulk parse these media names {names}.

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/kavita:kavita-plugin-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

kavita-plugin-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Kavita Plugin API
  description: Kavita provides a set of APIs authenticated via an Auth Key passed in the `x-api-key` header. Generate an Auth Key under User Settings → Manage Auth Keys, paste it into the Authorize panel, and all Try It requests will include it. Assume all fields of a payload are required unless marked optional. Built against v0.9.1.15
  license:
    name: GPL-3.0
    url: https://github.com/Kareadita/Kavita/blob/develop/LICENSE
  version: 0.9.1.15
servers:
- url: '{protocol}://{hostpath}'
  variables:
    protocol:
      default: http
      enum:
      - http
      - https
    hostpath:
      default: localhost:5000
security:
- AuthKey: []
tags:
- name: Plugin
paths:
  /api/Plugin/authenticate:
    post:
      tags:
      - Plugin
      summary: Authenticate with the Server given an auth key.
      description: This API is not fully built out and may require more information in later releases
      parameters:
      - name: apiKey
        in: query
        description: Auth key which will be used to authenticate and return a valid user token back
        required: true
        schema:
          type: string
      - name: pluginName
        in: query
        description: Name of the Plugin
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/UserDto'
            application/json:
              schema:
                $ref: '#/components/schemas/UserDto'
            text/json:
              schema:
                $ref: '#/components/schemas/UserDto'
      operationId: postApiPluginAuthenticate
      x-operation-id-source: derived
  /api/Plugin/version:
    get:
      tags:
      - Plugin
      summary: Returns the version of the Kavita install
      description: This will log unauthorized requests to Security log
      parameters:
      - name: apiKey
        in: query
        description: Required for authenticating to get result
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                type: string
            text/json:
              schema:
                type: string
      operationId: getApiPluginVersion
      x-operation-id-source: derived
  /api/Plugin/authkey-expires:
    get:
      tags:
      - Plugin
      summary: Returns the expiration (UTC) of the authenticated Auth key (or null if none set)
      description: Will always return null if the Auth Key does not belong to this account
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/AuthKeyExpiresAtDto'
            application/json:
              schema:
                $ref: '#/components/schemas/AuthKeyExpiresAtDto'
            text/json:
              schema:
                $ref: '#/components/schemas/AuthKeyExpiresAtDto'
      operationId: getApiPluginAuthkeyExpires
      x-operation-id-source: derived
  /api/Plugin/parse:
    get:
      tags:
      - Plugin
      summary: Parse a string and return Parsed information from it.
      parameters:
      - name: name
        in: query
        description: String to parse
        schema:
          maxLength: 1000
          minLength: 0
          type: string
      - name: libraryType
        in: query
        description: Determines the set of pattern matching to use
        schema:
          $ref: '#/components/schemas/LibraryType'
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ParseResultDto'
            application/json:
              schema:
                $ref: '#/components/schemas/ParseResultDto'
            text/json:
              schema:
                $ref: '#/components/schemas/ParseResultDto'
      operationId: getApiPluginParse
      x-operation-id-source: derived
  /api/Plugin/parse-bulk:
    post:
      tags:
      - Plugin
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParseBulkRequestDto'
          text/json:
            schema:
              $ref: '#/components/schemas/ParseBulkRequestDto'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ParseBulkRequestDto'
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ParseBulkResponseDto'
            application/json:
              schema:
                $ref: '#/components/schemas/ParseBulkResponseDto'
            text/json:
              schema:
                $ref: '#/components/schemas/ParseBulkResponseDto'
      summary: Create api plugin parse bulk
      x-summary-source: derived
      operationId: postApiPluginParseBulk
      x-operation-id-source: derived
components:
  schemas:
    AppUserOpdsPreferences:
      type: object
      properties:
        embedProgressIndicator:
          type: boolean
        includeContinueFrom:
          type: boolean
      additionalProperties: false
    PageLayoutMode:
      enum:
      - 0
      - 1
      type: integer
      description: 'Members:

        - `0` — Cards

        - `1` — List'
      format: int32
      x-enum-varnames:
      - Cards
      - List
      x-enum-descriptions:
      - Cards
      - List
    RgbaColor:
      type: object
      properties:
        r:
          type: integer
          format: int32
        g:
          type: integer
          format: int32
        b:
          type: integer
          format: int32
        a:
          type: number
          format: float
      additionalProperties: false
    LibraryType:
      enum:
      - 0
      - 1
      - 2
      - 3
      - 4
      - 5
      type: integer
      description: 'Members:

        - `0` — Manga

        - `1` — Comic (Flexible) (Comic)

        - `2` — Book

        - `3` — Image

        - `4` — Light Novel (LightNovel)

        - `5` — Comic (ComicVine)'
      format: int32
      x-enum-varnames:
      - Manga
      - Comic
      - Book
      - Image
      - LightNovel
      - ComicVine
      x-enum-descriptions:
      - Manga
      - Comic (Flexible)
      - Book
      - Image
      - Light Novel
      - Comic
    AppUserSocialPreferences:
      type: object
      properties:
        shareReviews:
          type: boolean
        shareAnnotations:
          type: boolean
        viewOtherAnnotations:
          type: boolean
        socialLibraries:
          type:
          - array
          - 'null'
          items:
            type: integer
            format: int32
        socialMaxAgeRating:
          $ref: '#/components/schemas/AgeRating'
        socialIncludeUnknowns:
          type: boolean
        shareProfile:
          type: boolean
      additionalProperties: false
    ParseResultDto:
      type: object
      properties:
        seriesName:
          type:
          - string
          - 'null'
        seriesYear:
          type:
          - string
          - 'null'
        minChapterNumber:
          type: number
          format: float
        maxChapterNumber:
          type: number
          format: float
        minVolumeNumber:
          type: number
          format: float
        maxVolumeNumber:
          type: number
          format: float
      additionalProperties: false
    AgeRating:
      enum:
      - 0
      - 1
      - 2
      - 3
      - 4
      - 5
      - 6
      - 7
      - 8
      - 9
      - 10
      - 11
      - 12
      - 13
      - 14
      - -1
      type: integer
      description: 'Members:

        - `0` — Unknown

        - `1` — Rating Pending (RatingPending)

        - `2` — Early Childhood (EarlyChildhood)

        - `3` — Everyone

        - `4` — G

        - `5` — Everyone 10+ (Everyone10Plus)

        - `6` — PG

        - `7` — Kids to Adults (KidsToAdults)

        - `8` — Teen

        - `9` — MA15+ (Mature15Plus)

        - `10` — Mature 17+ (Mature17Plus)

        - `11` — M (Mature)

        - `12` — R18+ (R18Plus)

        - `13` — Adults Only 18+ (AdultsOnly)

        - `14` — X18+ (X18Plus)

        - `-1` — Not Applicable (NotApplicable)'
      format: int32
      x-enum-varnames:
      - Unknown
      - RatingPending
      - EarlyChildhood
      - Everyone
      - G
      - Everyone10Plus
      - PG
      - KidsToAdults
      - Teen
      - Mature15Plus
      - Mature17Plus
      - Mature
      - R18Plus
      - AdultsOnly
      - X18Plus
      - NotApplicable
      x-enum-descriptions:
      - Unknown
      - Rating Pending
      - Early Childhood
      - Everyone
      - G
      - Everyone 10+
      - PG
      - Kids to Adults
      - Teen
      - MA15+
      - Mature 17+
      - M
      - R18+
      - Adults Only 18+
      - X18+
      - Not Applicable
    ParseBulkRequestDto:
      type: object
      properties:
        names:
          type:
          - array
          - 'null'
          items:
            type: string
        libraryType:
          $ref: '#/components/schemas/LibraryType'
      additionalProperties: false
    KeyBind:
      required:
      - key
      type: object
      properties:
        key:
          type:
          - string
          - 'null'
        control:
          type: boolean
        shift:
          type: boolean
        meta:
          type: boolean
        alt:
          type: boolean
        controllerSequence:
          type:
          - array
          - 'null'
          items:
            type: string
      additionalProperties: false
    AuthKeyDto:
      required:
      - key
      - name
      type: object
      properties:
        id:
          type: integer
          format: int32
        key:
          type:
          - string
          - 'null'
        name:
          type:
          - string
          - 'null'
        createdAtUtc:
          type: string
          format: date-time
        expiresAtUtc:
          type:
          - string
          - 'null'
          format: date-time
        lastAccessedAtUtc:
          type:
          - string
          - 'null'
          format: date-time
        provider:
          $ref: '#/components/schemas/AuthKeyProvider'
      additionalProperties: false
    AuthKeyProvider:
      enum:
      - 0
      - 1
      type: integer
      description: 'Members:

        - `0` — User

        - `1` — System'
      format: int32
      x-enum-varnames:
      - User
      - System
      x-enum-descriptions:
      - User
      - System
    AuthKeyExpiresAtDto:
      required:
      - expiresAt
      type: object
      properties:
        expiresAt:
          type:
          - string
          - 'null'
          format: date-time
      additionalProperties: false
    UserDto:
      type: object
      properties:
        id:
          type: integer
          format: int32
        oidcId:
          type:
          - string
          - 'null'
        username:
          type:
          - string
          - 'null'
        email:
          type:
          - string
          - 'null'
        roles:
          type:
          - array
          - 'null'
          items:
            type: string
        token:
          type:
          - string
          - 'null'
        refreshToken:
          type:
          - string
          - 'null'
        apiKey:
          type:
          - string
          - 'null'
        preferences:
          $ref: '#/components/schemas/UserPreferencesDto'
        ageRestriction:
          $ref: '#/components/schemas/AgeRestrictionDto'
        kavitaVersion:
          type:
          - string
          - 'null'
        identityProvider:
          $ref: '#/components/schemas/IdentityProvider'
        created:
          type: string
          format: date-time
        createdUtc:
          type: string
          format: date-time
        authKeys:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AuthKeyDto'
        coverImage:
          type:
          - string
          - 'null'
        primaryColor:
          type:
          - string
          - 'null'
        secondaryColor:
          type:
          - string
          - 'null'
      additionalProperties: false
    SiteThemeDto:
      required:
      - fileName
      - name
      - normalizedName
      type: object
      properties:
        id:
          type: integer
          format: int32
        name:
          type:
          - string
          - 'null'
        normalizedName:
          type:
          - string
          - 'null'
        fileName:
          type:
          - string
          - 'null'
        isDefault:
          type: boolean
        provider:
          $ref: '#/components/schemas/ThemeProvider'
        previewUrls:
          type:
          - array
          - 'null'
          items:
            type: string
        description:
          type:
          - string
          - 'null'
        author:
          type:
          - string
          - 'null'
        compatibleVersion:
          type:
          - string
          - 'null'
        selector:
          type:
          - string
          - 'null'
          readOnly: true
      additionalProperties: false
    AgeRestrictionDto:
      required:
      - ageRating
      - includeUnknowns
      type: object
      properties:
        ageRating:
          $ref: '#/components/schemas/AgeRating'
        includeUnknowns:
          type: boolean
      additionalProperties: false
    UserPreferencesDto:
      required:
      - blurUnreadSummaries
      - bookReaderHighlightSlots
      - collapseSeriesRelationships
      - colorScapeEnabled
      - customKeyBinds
      - dataSaver
      - locale
      - noTransitions
      - onDeckProgressDays
      - onDeckUpdateDays
      - opdsPreferences
      - promptForDownloadSize
      - promptForRereadsAfter
      - socialPreferences
      - theme
      type: object
      properties:
        theme:
          $ref: '#/components/schemas/SiteThemeDto'
        globalPageLayoutMode:
          $ref: '#/components/schemas/PageLayoutMode'
        blurUnreadSummaries:
          type: boolean
        promptForDownloadSize:
          type: boolean
        noTransitions:
          type: boolean
        collapseSeriesRelationships:
          type: boolean
        locale:
          minLength: 1
          type: string
        colorScapeEnabled:
          type: boolean
        dataSaver:
          type: boolean
        promptForRereadsAfter:
          type: integer
          format: int32
        onDeckProgressDays:
          type: integer
          format: int32
        onDeckUpdateDays:
          type: integer
          format: int32
        customKeyBinds:
          type: object
          properties:
            NavigateToSettings:
              type: array
              items:
                $ref: '#/components/schemas/KeyBind'
            OpenSearch:
              type: array
              items:
                $ref: '#/components/schemas/KeyBind'
            NavigateToScrobbling:
              type: array
              items:
                $ref: '#/components/schemas/KeyBind'
            ToggleFullScreen:
              type: array
              items:
                $ref: '#/components/schemas/KeyBind'
            BookmarkPage:
              type: array
              items:
                $ref: '#/components/schemas/KeyBind'
            OpenHelp:
              type: array
              items:
                $ref: '#/components/schemas/KeyBind'
            GoTo:
              type: array
              items:
                $ref: '#/components/schemas/KeyBind'
            ToggleMenu:
              type: array
              items:
                $ref: '#/components/schemas/KeyBind'
            PageLeft:
              type: array
              items:
                $ref: '#/components/schemas/KeyBind'
            PageRight:
              type: array
              items:
                $ref: '#/components/schemas/KeyBind'
            Escape:
              type: array
              items:
                $ref: '#/components/schemas/KeyBind'
            PageUp:
              type: array
              items:
                $ref: '#/components/schemas/KeyBind'
            PageDown:
              type: array
              items:
                $ref: '#/components/schemas/KeyBind'
            OffsetDoublePage:
              type: array
              items:
                $ref: '#/components/schemas/KeyBind'
            NextChapter:
              type: array
              items:
                $ref: '#/components/schemas/KeyBind'
            PreviousChapter:
              type: array
              items:
                $ref: '#/components/schemas/KeyBind'
            FirstPage:
              type: array
              items:
                $ref: '#/components/schemas/KeyBind'
            LastPage:
              type: array
              items:
                $ref: '#/components/schemas/KeyBind'
            NavigateHome:
              type: array
              items:
                $ref: '#/components/schemas/KeyBind'
            OpenEventWidget:
              type: array
              items:
                $ref: '#/components/schemas/KeyBind'
          additionalProperties: false
        aniListScrobblingEnabled:
          type: boolean
        wantToReadSync:
          type: boolean
        bookReaderHighlightSlots:
          type: array
          items:
            $ref: '#/components/schemas/HighlightSlot'
        socialPreferences:
          $ref: '#/components/schemas/AppUserSocialPreferences'
        opdsPreferences:
          $ref: '#/components/schemas/AppUserOpdsPreferences'
      additionalProperties: false
    IdentityProvider:
      enum:
      - 0
      - 1
      type: integer
      description: 'Members:

        - `0` — Kavita

        - `1` — OpenID Connect (OpenIdConnect)'
      format: int32
      x-enum-varnames:
      - Kavita
      - OpenIdConnect
      x-enum-descriptions:
      - Kavita
      - OpenID Connect
    ParseBulkResponseDto:
      type: object
      properties:
        results:
          type:
          - object
          - 'null'
          additionalProperties:
            $ref: '#/components/schemas/ParseResultDto'
        errors:
          type:
          - object
          - 'null'
          additionalProperties:
            type:
            - string
            - 'null'
        errorCounts:
          type: integer
          format: int32
          readOnly: true
      additionalProperties: false
    ThemeProvider:
      enum:
      - 1
      - 2
      type: integer
      description: 'Members:

        - `1` — System

        - `2` — Custom'
      format: int32
      x-enum-varnames:
      - System
      - Custom
      x-enum-descriptions:
      - System
      - Custom
    HighlightSlot:
      type: object
      properties:
        id:
          type: integer
          format: int32
        slotNumber:
          type: integer
          format: int32
        color:
          $ref: '#/components/schemas/RgbaColor'
      additionalProperties: false
  securitySchemes:
    AuthKey:
      type: apiKey
      description: Auth Key authentication. Enter your Auth key from your user settings
      name: x-api-key
      in: header