Kavita License API

openapi: 3.2.0
info:
  title: Kavita License 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: License
paths:
  /api/License/valid-license:
    get:
      tags:
      - License
      summary: Checks if the user's license is valid or not
      parameters:
      - name: forceCheck
        in: query
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: boolean
            application/json:
              schema:
                type: boolean
            text/json:
              schema:
                type: boolean
      operationId: getApiLicenseValidLicense
      x-operation-id-source: derived
  /api/License/has-license:
    get:
      tags:
      - License
      summary: Has any license registered with the instance.
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: boolean
            application/json:
              schema:
                type: boolean
            text/json:
              schema:
                type: boolean
      operationId: getApiLicenseHasLicense
      x-operation-id-source: derived
  /api/License/info:
    get:
      tags:
      - License
      summary: Asks Kavita+ for the latest license info
      parameters:
      - name: forceCheck
        in: query
        description: Force checking the API and skip the 8-hour cache
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/LicenseInfoDto'
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseInfoDto'
            text/json:
              schema:
                $ref: '#/components/schemas/LicenseInfoDto'
      operationId: getApiLicenseInfo
      x-operation-id-source: derived
  /api/License:
    delete:
      tags:
      - License
      summary: Remove the Kavita+ License on the Server
      responses:
        '200':
          description: OK
      operationId: deleteApiLicense
      x-operation-id-source: derived
    post:
      tags:
      - License
      summary: Updates server license
      description: Caches the result when successful
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLicenseDto'
          text/json:
            schema:
              $ref: '#/components/schemas/UpdateLicenseDto'
          application/*+json:
            schema:
              $ref: '#/components/schemas/UpdateLicenseDto'
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/KavitaPlusRegisterResultDto'
            application/json:
              schema:
                $ref: '#/components/schemas/KavitaPlusRegisterResultDto'
            text/json:
              schema:
                $ref: '#/components/schemas/KavitaPlusRegisterResultDto'
      operationId: postApiLicense
      x-operation-id-source: derived
  /api/License/reset:
    post:
      tags:
      - License
      summary: Break the registration between Kavita+ and this instance
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLicenseDto'
          text/json:
            schema:
              $ref: '#/components/schemas/UpdateLicenseDto'
          application/*+json:
            schema:
              $ref: '#/components/schemas/UpdateLicenseDto'
      responses:
        '200':
          description: OK
      operationId: postApiLicenseReset
      x-operation-id-source: derived
  /api/License/resend-license:
    post:
      tags:
      - License
      summary: Resend the welcome email to the user
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: boolean
            application/json:
              schema:
                type: boolean
            text/json:
              schema:
                type: boolean
      operationId: postApiLicenseResendLicense
      x-operation-id-source: derived
  /api/License/provider-health:
    get:
      tags:
      - License
      summary: Provides a 15 min snapshot of Kavita+ Providers (Hardcover, AniList, MangaBaka…
      parameters:
      - name: forceCheck
        in: query
        description: Bypass cache and force a reload from Kavita+ server
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KavitaPlusProviderHealthSnapshotDto'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KavitaPlusProviderHealthSnapshotDto'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KavitaPlusProviderHealthSnapshotDto'
      operationId: getApiLicenseProviderHealth
      x-operation-id-source: derived
  /api/License/stats:
    get:
      tags:
      - License
      summary: Providers how many interactions this license has had with Kavita+ over a…
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/KavitaPlusLicenseUsageDto'
            application/json:
              schema:
                $ref: '#/components/schemas/KavitaPlusLicenseUsageDto'
            text/json:
              schema:
                $ref: '#/components/schemas/KavitaPlusLicenseUsageDto'
      operationId: getApiLicenseStats
      x-operation-id-source: derived
  /api/License/cancel:
    delete:
      tags:
      - License
      summary: Cancels the active Kavita+ Subscription tied to this server.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelKavitaPlusLicenseDto'
          text/json:
            schema:
              $ref: '#/components/schemas/CancelKavitaPlusLicenseDto'
          application/*+json:
            schema:
              $ref: '#/components/schemas/CancelKavitaPlusLicenseDto'
      responses:
        '200':
          description: OK
      operationId: deleteApiLicenseCancel
      x-operation-id-source: derived
  /api/License/products:
    get:
      tags:
      - License
      summary: Returns the available Kavita+ products (billing interval and list price) the…
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KavitaPlusProductInfoDto'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KavitaPlusProductInfoDto'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KavitaPlusProductInfoDto'
      operationId: getApiLicenseProducts
      x-operation-id-source: derived
  /api/License/renew:
    post:
      tags:
      - License
      summary: Renews the subscription on the given billing interval and returns the Stripe…
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenewKavitaPlusLicenseDto'
          text/json:
            schema:
              $ref: '#/components/schemas/RenewKavitaPlusLicenseDto'
          application/*+json:
            schema:
              $ref: '#/components/schemas/RenewKavitaPlusLicenseDto'
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                type: string
            text/json:
              schema:
                type: string
      operationId: postApiLicenseRenew
      x-operation-id-source: derived
  /api/License/change-email:
    post:
      tags:
      - License
      summary: Change email on Kavita+ License/Stripe - Sends a confirmation email on Kavita+…
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeEmailOnLicenseDto'
          text/json:
            schema:
              $ref: '#/components/schemas/ChangeEmailOnLicenseDto'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ChangeEmailOnLicenseDto'
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: boolean
            application/json:
              schema:
                type: boolean
            text/json:
              schema:
                type: boolean
      operationId: postApiLicenseChangeEmail
      x-operation-id-source: derived
components:
  schemas:
    ChangeEmailOnLicenseDto:
      required:
      - newEmail
      - oldEmail
      type: object
      properties:
        oldEmail:
          type:
          - string
          - 'null'
        newEmail:
          type:
          - string
          - 'null'
      additionalProperties: false
    KavitaPlusProviderIncidentDto:
      type: object
      properties:
        startedAtUtc:
          type: string
          format: date-time
        endedAtUtc:
          type:
          - string
          - 'null'
          format: date-time
        type:
          $ref: '#/components/schemas/KavitaPlusProviderHealthIncidentType'
      additionalProperties: false
    RenewKavitaPlusLicenseDto:
      required:
      - billingInterval
      - email
      type: object
      properties:
        email:
          minLength: 1
          type: string
          format: email
        billingInterval:
          $ref: '#/components/schemas/KavitaPlusBillingInterval'
      additionalProperties: false
    DailyBucketDto:
      type: object
      properties:
        date:
          type: string
          format: date
        count:
          type: integer
          format: int64
      additionalProperties: false
    KavitaPlusRegistrationErrorCode:
      enum:
      - 0
      - 1
      - 2
      - 3
      - 4
      type: integer
      description: 'Members:

        - `0` — None

        - `1` — Registration Failed (RegistrationFailed)

        - `2` — Already Registered (AlreadyRegistered)

        - `3` — Subscription Inactive (SubscriptionInactive)

        - `4` — Internal Error (InternalError)'
      format: int32
      x-enum-varnames:
      - None
      - RegistrationFailed
      - AlreadyRegistered
      - SubscriptionInactive
      - InternalError
      x-enum-descriptions:
      - None
      - Registration Failed
      - Already Registered
      - Subscription Inactive
      - Internal Error
    KavitaPlusProviderHealthIncidentType:
      enum:
      - 1
      - 2
      type: integer
      description: 'Members:

        - `1` — Degraded

        - `2` — Down'
      format: int32
      x-enum-varnames:
      - Degraded
      - Down
      x-enum-descriptions:
      - Degraded
      - Down
    KavitaPlusProviderHealthSnapshotDto:
      type: object
      properties:
        provider:
          $ref: '#/components/schemas/ScrobbleProvider'
        avgLatencyMs:
          type: number
          format: double
        status:
          $ref: '#/components/schemas/KavitaPlusProviderHealthStatus'
        lastIncident:
          $ref: '#/components/schemas/KavitaPlusProviderIncidentDto'
      additionalProperties: false
    KavitaPlusLicenseUsageDto:
      type: object
      properties:
        generatedAtUtc:
          type: string
          format: date-time
        stats:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ApiUsageDto'
      additionalProperties: false
    ScrobbleProvider:
      enum:
      - 0
      - 1
      - 2
      - 4
      - 5
      - 6
      type: integer
      description: 'Members:

        - `0` — Kavita

        - `1` — AniList

        - `2` — Mal

        - `4` — Cbr

        - `5` — Hardcover

        - `6` — MangaBaka'
      format: int32
      x-enum-varnames:
      - Kavita
      - AniList
      - Mal
      - Cbr
      - Hardcover
      - MangaBaka
      x-enum-descriptions:
      - Kavita
      - AniList
      - Mal
      - Cbr
      - Hardcover
      - MangaBaka
    ApiUsageDto:
      type: object
      properties:
        apiName:
          $ref: '#/components/schemas/KavitaPlusApiName'
        lifetimeCount:
          type: integer
          format: int64
        last30DaysCount:
          type: integer
          format: int64
        dailyBuckets:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/DailyBucketDto'
      additionalProperties: false
    CancelKavitaPlusLicenseDto:
      required:
      - email
      type: object
      properties:
        email:
          type:
          - string
          - 'null'
        comment:
          type:
          - string
          - 'null'
      additionalProperties: false
    KavitaPlusApiName:
      enum:
      - 1
      - 2
      - 3
      - 4
      - 5
      - 6
      - 7
      - 8
      type: integer
      description: 'Members:

        - `1` — CoverRequests

        - `2` — MetadataSync

        - `3` — SeriesMatched

        - `4` — Scrobbles

        - `5` — MalStackImport

        - `6` — WantToRead

        - `7` — Recommendations

        - `8` — Reviews'
      format: int32
      x-enum-varnames:
      - CoverRequests
      - MetadataSync
      - SeriesMatched
      - Scrobbles
      - MalStackImport
      - WantToRead
      - Recommendations
      - Reviews
      x-enum-descriptions:
      - CoverRequests
      - MetadataSync
      - SeriesMatched
      - Scrobbles
      - MalStackImport
      - WantToRead
      - Recommendations
      - Reviews
    UpdateLicenseDto:
      required:
      - email
      - license
      type: object
      properties:
        license:
          type:
          - string
          - 'null'
        email:
          type:
          - string
          - 'null'
        discordId:
          type:
          - string
          - 'null'
      additionalProperties: false
    KavitaPlusProductInfoDto:
      type: object
      properties:
        productName:
          type:
          - string
          - 'null'
        priceAmount:
          type: integer
          format: int64
        priceCurrency:
          type:
          - string
          - 'null'
        billingInterval:
          $ref: '#/components/schemas/KavitaPlusBillingInterval'
      additionalProperties: false
    KavitaPlusSubscriptionState:
      enum:
      - 0
      - 1
      - 2
      - 3
      - 4
      type: integer
      description: 'Members:

        - `0` — Active

        - `1` — Cancelled

        - `2` — Paused

        - `3` — Cancelling

        - `4` — Expired'
      format: int32
      x-enum-varnames:
      - Active
      - Cancelled
      - Paused
      - Cancelling
      - Expired
      x-enum-descriptions:
      - Active
      - Cancelled
      - Paused
      - Cancelling
      - Expired
    LicenseInfoDto:
      type: object
      properties:
        state:
          $ref: '#/components/schemas/KavitaPlusSubscriptionState'
        isActive:
          type: boolean
        isCancelled:
          type: boolean
        expirationDate:
          type: string
          format: date-time
        nextChargeDate:
          type:
          - string
          - 'null'
          format: date-time
        subscribedSince:
          type:
          - string
          - 'null'
          format: date-time
        productName:
          type:
          - string
          - 'null'
        priceAmount:
          type:
          - integer
          - 'null'
          format: int64
        priceCurrency:
          type:
          - string
          - 'null'
        billingInterval:
          $ref: '#/components/schemas/KavitaPlusBillingInterval'
        hasActiveDiscount:
          type: boolean
        isValidVersion:
          type: boolean
        registeredEmail:
          type:
          - string
          - 'null'
        totalMonthsSubbed:
          type: integer
          format: int32
        hasLicense:
          type: boolean
        installId:
          type:
          - string
          - 'null'
        pastDue:
          type: boolean
        discordId:
          type:
          - string
          - 'null'
        discordUsername:
          type:
          - string
          - 'null'
        hasDiscordSet:
          type: boolean
          readOnly: true
      additionalProperties: false
    KavitaPlusBillingInterval:
      enum:
      - 0
      - 1
      - 2
      - 3
      type: integer
      description: 'Members:

        - `0` — Day

        - `1` — Week

        - `2` — Month

        - `3` — Year'
      format: int32
      x-enum-varnames:
      - Day
      - Week
      - Month
      - Year
      x-enum-descriptions:
      - Day
      - Week
      - Month
      - Year
    KavitaPlusRegisterResultDto:
      type: object
      properties:
        success:
          type: boolean
        isSubscriptionActive:
          type: boolean
        errorCode:
          $ref: '#/components/schemas/KavitaPlusRegistrationErrorCode'
      additionalProperties: false
    KavitaPlusProviderHealthStatus:
      enum:
      - 0
      - 1
      - 2
      - 3
      type: integer
      description: 'Members:

        - `0` — Unknown

        - `1` — Operational

        - `2` — Degraded

        - `3` — Down'
      format: int32
      x-enum-varnames:
      - Unknown
      - Operational
      - Degraded
      - Down
      x-enum-descriptions:
      - Unknown
      - Operational
      - Degraded
      - Down
  securitySchemes:
    AuthKey:
      type: apiKey
      description: Auth Key authentication. Enter your Auth key from your user settings
      name: x-api-key
      in: header