Kavita Annotation API

The Annotation API from Kavita — 12 operation(s) for annotation.

GitHub OpenAPI

Operations 12

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/Annotation/all-filtered Search annotations across the library · Returns a list of annotations for browsing #
Ask an LLM
“How do I find annotations that match a series, reading list or person?”
“Can I combine several annotation filters with an AND or OR?”
Tell an agent
Find annotations matching {statements} on {entityType}.
Search annotations for {statements} using {combination} logic.
GET /api/Annotation/all List annotations on a chapter · Returns the annotations for the given chapter #
Ask an LLM
“What annotations exist on a particular chapter?”
“Can I see the highlights and comments on one chapter?”
Tell an agent
List annotations on chapter {chapterId}.
Show the annotations made on chapter {chapterId}.
GET /api/Annotation/all-for-series List annotations across a series · Returns all annotations by Series #
Ask an LLM
“Can I see every annotation made across a whole manga series?”
“Which annotations exist in a series regardless of chapter?”
Tell an agent
List annotations for series {seriesId}.
Show every annotation made in series {seriesId}.
GET /api/Annotation/{annotationId} Get one annotation · Returns the Annotation by Id. User must have access to annotation #
Ask an LLM
“How do I look up a single annotation by its ID?”
“Can I check whether I have access to a specific annotation?”
Tell an agent
Get annotation {annotationId}.
Show me annotation {annotationId}.
POST /api/Annotation/create Create an annotation on a chapter · Create a new Annotation for the user against a Chapter #
Ask an LLM
“How do I highlight a passage and leave a comment on a chapter?”
“Can I mark an annotation as containing a spoiler?”
Tell an agent
Create an annotation on chapter {chapterId} in series {seriesId} at {xPath}.
Annotate {selectedText} on chapter {chapterId} with comment {comment}.
POST /api/Annotation/update Update an annotation · Update the modifiable fields (Spoiler, highlight slot, and comment) for an… #
Ask an LLM
“Can I change the comment or spoiler flag on an annotation I made?”
“Is it possible to move an existing annotation to a different highlight slot?”
Tell an agent
Update annotation {id} on chapter {chapterId} to comment {comment}.
Mark annotation {id} as spoiler {containsSpoiler}.
POST /api/Annotation/like Like an annotation · Adds a like for the currently authenticated user if not already from the… #
Ask an LLM
“How do I like an annotation I found helpful?”
“Can I upvote an annotation?”
Tell an agent
Like the annotation I'm currently viewing.
Upvote this annotation with my user account.
POST /api/Annotation/unlike Remove my like on an annotation · Removes likes for the currently authenticated user if present from the… #
Ask an LLM
“Can I take back a like I gave on an annotation?”
“What happens if I dislike an annotation I liked?”
Tell an agent
Remove my like from the annotation I'm viewing.
Unupvote this annotation.
DELETE /api/Annotation Delete an annotation · Delete the annotation for the user #
Ask an LLM
“How do I delete an annotation I made by mistake?”
“Can I remove one annotation from a chapter?”
Tell an agent destructive · confirm first
Delete annotation {annotationId}.
Remove my annotation {annotationId} from the chapter.
POST /api/Annotation/bulk-delete Delete several annotations at once · Removes annotations in bulk. #
Ask an LLM
“Can I delete many annotations in one request?”
“Is there a bulk delete for annotations?”
Tell an agent destructive · confirm first
Bulk delete the annotations I selected.
Remove all of these annotations in one call.
POST /api/Annotation/export-filter Export annotations matching a filter · Exports annotations for the given users #
Ask an LLM
“How do I export annotations that match a series or reading list?”
“Can I export annotations for a specific user?”
Tell an agent
Export annotations matching {statements} on {entityType}.
Export annotations for {statements} using {combination} logic.
POST /api/Annotation/export Export my annotations · Exports Annotations for the User #
Ask an LLM
“Can I download all of my annotations as a file?”
“Where do I get a copy of my annotations?”
Tell an agent
Export all of my annotations.
Download my annotations as a file.

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-annotation-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-annotation-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Kavita Annotation 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: Annotation
paths:
  /api/Annotation/all-filtered:
    post:
      tags:
      - Annotation
      summary: Returns a list of annotations for browsing
      parameters:
      - name: PageNumber
        in: query
        schema:
          type: integer
          format: int32
      - name: PageSize
        in: query
        schema:
          type: integer
          format: int32
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnnotationFilterDto'
          text/json:
            schema:
              $ref: '#/components/schemas/AnnotationFilterDto'
          application/*+json:
            schema:
              $ref: '#/components/schemas/AnnotationFilterDto'
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AnnotationDto'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AnnotationDto'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AnnotationDto'
      operationId: postApiAnnotationAllFiltered
      x-operation-id-source: derived
  /api/Annotation/all:
    get:
      tags:
      - Annotation
      summary: Returns the annotations for the given chapter
      parameters:
      - name: chapterId
        in: query
        description: ''
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AnnotationDto'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AnnotationDto'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AnnotationDto'
      operationId: getApiAnnotationAll
      x-operation-id-source: derived
  /api/Annotation/all-for-series:
    get:
      tags:
      - Annotation
      summary: Returns all annotations by Series
      parameters:
      - name: seriesId
        in: query
        description: ''
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/AnnotationDto'
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationDto'
            text/json:
              schema:
                $ref: '#/components/schemas/AnnotationDto'
      operationId: getApiAnnotationAllForSeries
      x-operation-id-source: derived
  /api/Annotation/{annotationId}:
    get:
      tags:
      - Annotation
      summary: Returns the Annotation by Id. User must have access to annotation
      parameters:
      - name: annotationId
        in: path
        description: ''
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/AnnotationDto'
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationDto'
            text/json:
              schema:
                $ref: '#/components/schemas/AnnotationDto'
      operationId: getApiAnnotationByAnnotationId
      x-operation-id-source: derived
  /api/Annotation/create:
    post:
      tags:
      - Annotation
      summary: Create a new Annotation for the user against a Chapter
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnnotationDto'
          text/json:
            schema:
              $ref: '#/components/schemas/AnnotationDto'
          application/*+json:
            schema:
              $ref: '#/components/schemas/AnnotationDto'
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/AnnotationDto'
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationDto'
            text/json:
              schema:
                $ref: '#/components/schemas/AnnotationDto'
      operationId: postApiAnnotationCreate
      x-operation-id-source: derived
  /api/Annotation/update:
    post:
      tags:
      - Annotation
      summary: Update the modifiable fields (Spoiler, highlight slot, and comment) for an…
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnnotationDto'
          text/json:
            schema:
              $ref: '#/components/schemas/AnnotationDto'
          application/*+json:
            schema:
              $ref: '#/components/schemas/AnnotationDto'
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/AnnotationDto'
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationDto'
            text/json:
              schema:
                $ref: '#/components/schemas/AnnotationDto'
      operationId: postApiAnnotationUpdate
      x-operation-id-source: derived
  /api/Annotation/like:
    post:
      tags:
      - Annotation
      summary: Adds a like for the currently authenticated user if not already from the…
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: array
              items:
                type: integer
                format: int32
          text/json:
            schema:
              type: array
              items:
                type: integer
                format: int32
          application/*+json:
            schema:
              type: array
              items:
                type: integer
                format: int32
      responses:
        '200':
          description: OK
      operationId: postApiAnnotationLike
      x-operation-id-source: derived
  /api/Annotation/unlike:
    post:
      tags:
      - Annotation
      summary: Removes likes for the currently authenticated user if present from the…
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: array
              items:
                type: integer
                format: int32
          text/json:
            schema:
              type: array
              items:
                type: integer
                format: int32
          application/*+json:
            schema:
              type: array
              items:
                type: integer
                format: int32
      responses:
        '200':
          description: OK
      operationId: postApiAnnotationUnlike
      x-operation-id-source: derived
  /api/Annotation:
    delete:
      tags:
      - Annotation
      summary: Delete the annotation for the user
      parameters:
      - name: annotationId
        in: query
        description: ''
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
      operationId: deleteApiAnnotation
      x-operation-id-source: derived
  /api/Annotation/bulk-delete:
    post:
      tags:
      - Annotation
      summary: Removes annotations in bulk.
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: array
              items:
                type: integer
                format: int32
          text/json:
            schema:
              type: array
              items:
                type: integer
                format: int32
          application/*+json:
            schema:
              type: array
              items:
                type: integer
                format: int32
      responses:
        '200':
          description: OK
      operationId: postApiAnnotationBulkDelete
      x-operation-id-source: derived
  /api/Annotation/export-filter:
    post:
      tags:
      - Annotation
      summary: Exports annotations for the given users
      parameters:
      - name: PageNumber
        in: query
        schema:
          type: integer
          format: int32
      - name: PageSize
        in: query
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnnotationFilterDto'
          text/json:
            schema:
              $ref: '#/components/schemas/AnnotationFilterDto'
          application/*+json:
            schema:
              $ref: '#/components/schemas/AnnotationFilterDto'
      responses:
        '200':
          description: OK
      operationId: postApiAnnotationExportFilter
      x-operation-id-source: derived
  /api/Annotation/export:
    post:
      tags:
      - Annotation
      summary: Exports Annotations for the User
      requestBody:
        description: Export annotations with the given ids
        content:
          application/json:
            schema:
              type: array
              items:
                type: integer
                format: int32
          text/json:
            schema:
              type: array
              items:
                type: integer
                format: int32
          application/*+json:
            schema:
              type: array
              items:
                type: integer
                format: int32
      responses:
        '200':
          description: OK
      operationId: postApiAnnotationExport
      x-operation-id-source: derived
components:
  schemas:
    FilterCombination:
      enum:
      - 0
      - 1
      type: integer
      description: 'Members:

        - `0` — Or

        - `1` — And'
      format: int32
      x-enum-varnames:
      - Or
      - And
      x-enum-descriptions:
      - Or
      - And
    AnnotationFilterStatementDto:
      type: object
      properties:
        comparison:
          $ref: '#/components/schemas/FilterComparison'
        field:
          $ref: '#/components/schemas/AnnotationFilterField'
        value:
          type:
          - string
          - 'null'
      additionalProperties: false
    AnnotationSortField:
      enum:
      - 1
      - 2
      - 3
      - 4
      type: integer
      description: 'Members:

        - `1` — Owner

        - `2` — Created

        - `3` — LastModified

        - `4` — Color'
      format: int32
      x-enum-varnames:
      - Owner
      - Created
      - LastModified
      - Color
      x-enum-descriptions:
      - Owner
      - Created
      - LastModified
      - Color
    AnnotationFilterField:
      enum:
      - 1
      - 2
      - 3
      - 4
      - 5
      - 6
      - 7
      - 8
      - 9
      type: integer
      description: 'Members:

        - `1` — Owner

        - `2` — Library

        - `3` — Spoiler

        - `4` — HighlightSlot

        - `5` — Selection

        - `6` — Comment

        - `7` — Series

        - `8` — Likes

        - `9` — LikedBy'
      format: int32
      x-enum-varnames:
      - Owner
      - Library
      - Spoiler
      - HighlightSlot
      - Selection
      - Comment
      - Series
      - Likes
      - LikedBy
      x-enum-descriptions:
      - Owner
      - Library
      - Spoiler
      - HighlightSlot
      - Selection
      - Comment
      - Series
      - Likes
      - LikedBy
    AnnotationDto:
      required:
      - chapterId
      - libraryId
      - ownerUserId
      - seriesId
      - volumeId
      - xPath
      type: object
      properties:
        id:
          type: integer
          format: int32
        xPath:
          type:
          - string
          - 'null'
        endingXPath:
          type:
          - string
          - 'null'
        selectedText:
          type:
          - string
          - 'null'
        comment:
          type:
          - string
          - 'null'
        commentHtml:
          type:
          - string
          - 'null'
        commentPlainText:
          type:
          - string
          - 'null'
        chapterTitle:
          type:
          - string
          - 'null'
        context:
          type:
          - string
          - 'null'
        highlightCount:
          type: integer
          format: int32
        containsSpoiler:
          type: boolean
        pageNumber:
          type: integer
          format: int32
        selectedSlotIndex:
          type: integer
          format: int32
        likes:
          type:
          - array
          - 'null'
          items:
            type: integer
            format: int32
        seriesName:
          type:
          - string
          - 'null'
        libraryName:
          type:
          - string
          - 'null'
        chapterId:
          type: integer
          format: int32
        volumeId:
          type: integer
          format: int32
        seriesId:
          type: integer
          format: int32
        libraryId:
          type: integer
          format: int32
        ownerUserId:
          type: integer
          format: int32
        ownerUsername:
          type:
          - string
          - 'null'
        ageRating:
          $ref: '#/components/schemas/AgeRating'
        createdUtc:
          type: string
          format: date-time
        lastModifiedUtc:
          type: string
          format: date-time
      additionalProperties: false
    FilterEntityType:
      enum:
      - 0
      - 1
      - 2
      - 3
      type: integer
      description: 'Members:

        - `0` — Series

        - `1` — Reading List (ReadingList)

        - `2` — Person

        - `3` — Annotation'
      format: int32
      x-enum-varnames:
      - Series
      - ReadingList
      - Person
      - Annotation
      x-enum-descriptions:
      - Series
      - Reading List
      - Person
      - Annotation
    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
    FilterComparison:
      enum:
      - 0
      - 1
      - 2
      - 3
      - 4
      - 5
      - 6
      - 7
      - 8
      - 9
      - 10
      - 11
      - 12
      - 13
      - 14
      - 15
      - 16
      - 17
      type: integer
      description: 'Members:

        - `0` — Equal

        - `1` — GreaterThan

        - `2` — GreaterThanEqual

        - `3` — LessThan

        - `4` — LessThanEqual

        - `5` — Contains

        - `6` — MustContains

        - `7` — Matches

        - `8` — NotContains

        - `9` — NotEqual

        - `10` — BeginsWith

        - `11` — EndsWith

        - `12` — IsBefore

        - `13` — IsAfter

        - `14` — IsInLast

        - `15` — IsNotInLast

        - `16` — IsEmpty

        - `17` — IsNotEmpty'
      format: int32
      x-enum-varnames:
      - Equal
      - GreaterThan
      - GreaterThanEqual
      - LessThan
      - LessThanEqual
      - Contains
      - MustContains
      - Matches
      - NotContains
      - NotEqual
      - BeginsWith
      - EndsWith
      - IsBefore
      - IsAfter
      - IsInLast
      - IsNotInLast
      - IsEmpty
      - IsNotEmpty
      x-enum-descriptions:
      - Equal
      - GreaterThan
      - GreaterThanEqual
      - LessThan
      - LessThanEqual
      - Contains
      - MustContains
      - Matches
      - NotContains
      - NotEqual
      - BeginsWith
      - EndsWith
      - IsBefore
      - IsAfter
      - IsInLast
      - IsNotInLast
      - IsEmpty
      - IsNotEmpty
    AnnotationSortOptionDto:
      type: object
      properties:
        sortField:
          $ref: '#/components/schemas/AnnotationSortField'
        isAscending:
          type: boolean
      additionalProperties: false
    AnnotationFilterDto:
      type: object
      properties:
        id:
          type: integer
          format: int32
        name:
          type:
          - string
          - 'null'
        statements:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AnnotationFilterStatementDto'
        combination:
          $ref: '#/components/schemas/FilterCombination'
        sortOptions:
          $ref: '#/components/schemas/AnnotationSortOptionDto'
        entityType:
          $ref: '#/components/schemas/FilterEntityType'
        limitTo:
          type: integer
          format: int32
      additionalProperties: false
  securitySchemes:
    AuthKey:
      type: apiKey
      description: Auth Key authentication. Enter your Auth key from your user settings
      name: x-api-key
      in: header