### Install komga-sdk

Source: https://komga-sdk.mintlify.site/quickstart

Install the SDK using your preferred Node.js package manager.

```bash
npm install komga-sdk
```

```bash
pnpm add komga-sdk
```

```bash
yarn add komga-sdk
```

```bash
bun add komga-sdk
```

--------------------------------

### Get Server Information Response Example

Source: https://komga-sdk.mintlify.site/api-reference/management/get-server-information

The response returns a JSON object containing git commit details, build metadata, Java environment specifications, and host OS information.

```json
{
  "git": {
    "branch": "master",
    "commit": {
      "id": "9be980d",
      "time": "2025-03-12T03:40:38Z"
    }
  },
  "build": {
    "artifact": "komga",
    "name": "komga",
    "version": "1.21.2",
    "group": "komga"
  },
  "java": {
    "version": "23.0.2",
    "vendor": {
      "name": "Eclipse Adoptium",
      "version": "Temurin-23.0.2+7"
    },
    "runtime": {
      "name": "OpenJDK Runtime Environment",
      "version": "23.0.2+7"
    },
    "jvm": {
      "name": "OpenJDK 64-Bit Server VM",
      "vendor": "Eclipse Adoptium",
      "version": "23.0.2+7"
    }
  },
  "os": {
    "name": "Linux",
    "version": "6.8.0-57-generic",
    "arch": "amd64"
  }
}
```

--------------------------------

### Save Global Settings JSON Example

Source: https://komga-sdk.mintlify.site/api-reference/client-settings/save-global-settings

Example payload for updating global settings, requiring an ADMIN role.

```json
{
  "application.key1": {
    "value": "a string value",
    "allowUnauthorized": true
  },
  "application.key2": {
    "value": "{\"json\":\"object\"}",
    "allowUnauthorized": false
  }
}
```

--------------------------------

### Save User Settings Request Body Example

Source: https://komga-sdk.mintlify.site/api-reference/client-settings/save-user-settings

Example payload for the PATCH request to save user settings. Keys must be lowercase strings in a namespace format.

```json
{
  "application.key1": {
    "value": "a string value"
  },
  "application.key2": {
    "value": "{\"json\":\"object\"}"
  }
}
```

--------------------------------

### GET /api/v1/client-settings/global/list

Source: https://komga-sdk.mintlify.site/api-reference/client-settings/retrieve-global-client-settings

Retrieves the list of global client settings.

```APIDOC
## GET /api/v1/client-settings/global/list

### Description
Retrieves the global client settings. For unauthenticated users, only settings with 'allowUnauthorized=true' will be returned.

### Method
GET

### Endpoint
/api/v1/client-settings/global/list
```

--------------------------------

### GET /api/v1/settings

Source: https://komga-sdk.mintlify.site/api-reference/server-settings/retrieve-server-settings

Retrieves the current server settings object.

```APIDOC
## GET /api/v1/settings

### Description
Retrieves the current server settings, including configuration sources and effective values for various server parameters.

### Method
GET

### Endpoint
/api/v1/settings

### Response
#### Success Response (200)
- **deleteEmptyCollections** (boolean) - Whether to delete empty collections.
- **deleteEmptyReadLists** (boolean) - Whether to delete empty read lists.
- **kepubifyPath** (object) - Path configuration for kepubify.
- **koboPort** (integer) - Kobo port number.
- **koboProxy** (boolean) - Whether Kobo proxy is enabled.
- **rememberMeDurationDays** (integer) - Duration in days for the remember me feature.
- **serverContextPath** (object) - Server context path configuration.
- **serverPort** (object) - Server port configuration.
- **taskPoolSize** (integer) - Size of the task pool.
- **thumbnailSize** (string) - Size of thumbnails (DEFAULT, MEDIUM, LARGE, XLARGE).
```

--------------------------------

### GET /api/v1/libraries

Source: https://komga-sdk.mintlify.site/api-reference/libraries/list-all-libraries

Retrieves all libraries available in the Komga instance.

```APIDOC
## GET /api/v1/libraries

### Description
Returns a list of all libraries configured in the system.

### Method
GET

### Endpoint
/api/v1/libraries

### Response
#### Success Response (200)
- **libraries** (array) - A list of LibraryDto objects.

#### Response Example
[
  {
    "id": "123",
    "name": "My Library",
    "root": "/data/comics",
    "scanInterval": "DAILY",
    "seriesCover": "FIRST",
    "unavailable": false
  }
]
```

--------------------------------

### Run example scripts

Source: https://komga-sdk.mintlify.site/quickstart

Commands to execute the SDK implementation using tsx or Bun runtimes.

```bash
npx tsx index.ts
```

```bash
bun run index.ts
```

--------------------------------

### Initialize client and fetch book by ID

Source: https://komga-sdk.mintlify.site/domain-services

Demonstrates creating a client instance and using it to fetch a book, utilizing unwrap to handle potential API errors.

```typescript
import { createKomgaClient, getBookById, unwrap } from 'komga-sdk';

const client = createKomgaClient({
  baseUrl: 'http://localhost:25600',
  auth: { type: 'basic', username: 'admin', password: 'password' },
});

const book = unwrap(await getBookById({ bookId: 'book-123' }, { client }));
console.log(book.metadata.title);
```

--------------------------------

### GET /api/v1/authors

Source: https://komga-sdk.mintlify.site/api-reference/deprecated/list-authors

This endpoint is deprecated since version 1.20.0. Users should migrate to GET /api/v2/authors.

```APIDOC
## GET /api/v1/authors

### Description
This endpoint is deprecated since version 1.20.0. Please use GET /api/v2/authors instead.

### Method
GET

### Endpoint
/api/v1/authors
```

--------------------------------

### Initialize Komga client

Source: https://komga-sdk.mintlify.site/authentication

Create a client instance using the SDK with API key authentication sourced from environment variables.

```typescript
import { createKomgaClient } from 'komga-sdk';

export const client = createKomgaClient({
  baseUrl: process.env.KOMGA_URL!,
  auth: {
    type: 'apiKey',
    key: process.env.KOMGA_API_KEY!,
  },
});
```

--------------------------------

### Get book progression OpenAPI definition

Source: https://komga-sdk.mintlify.site/api-reference/webpub-manifest/get-book-progression

The OpenAPI specification for the GET /api/v1/books/{bookId}/progression endpoint.

```yaml
openapi: 3.1.0
info:
  description: >-
    Komga REST API.


    ## Reference


    Check the API reference:

    - on the [Komga website](https://komga.org/docs/openapi/komga-api)

    - on any running Komga instance at `/swagger-ui.html`

    - on
    [GitHub](https://raw.githubusercontent.com/gotson/komga/refs/heads/master/komga/docs/openapi.json)


    ## Authentication


    Most endpoints require authentication. Authentication is done using either:

    - Basic Authentication

    - Passing an API Key in the `X-API-Key` header


    ## Sessions


    Upon successful authentication, a session is created, and can be reused.


    - By default, a `KOMGA-SESSION` cookie is set via `Set-Cookie` response
    header. This works well for browsers and clients that can handle cookies.

    - If you specify a header `X-Auth-Token` during authentication, the session
    ID will be returned via this same header. You can then pass that header
    again for subsequent requests to reuse the session.


    If you need to set the session cookie later on, you can call
    `/api/v1/login/set-cookie` with `X-Auth-Token`. The response will contain
    the `Set-Cookie` header.


    ## Remember Me


    During authentication, if a request parameter `remember-me` is passed and
    set to `true`, the server will also return a `komga-remember-me` cookie.
    This cookie will be used to login automatically even if the session has
    expired.


    ## Logout


    You can explicitly logout an existing session by calling `/api/logout`. This
    would return a `204`.


    ## Deprecation


    API endpoints marked as deprecated will be removed in the next major
    version.
  license:
    name: MIT
    url: https://github.com/gotson/komga/blob/master/LICENSE
  title: Komga API
  version: 1.25.0
servers:
  - url: https://demo.komga.org
    description: Demo server
  - url: http://localhost:{port}
    description: Local development server
    variables:
      port:
        enum:
          - '8080'
          - '25600'
        default: '25600'
security:
  - basicAuth: []
  - apiKey: []
tags:
  - name: Deprecated
  - description: Manage libraries.
    name: Libraries
  - description: Manage series.
    name: Series
  - description: Manage posters for series.
    name: Series Poster
  - description: Manage books.
    name: Books
  - description: Manage posters for books.
    name: Book Poster
  - name: Book Pages
  - name: WebPub Manifest
  - name: Import
  - description: Provide font files and CSS for the Epub Reader.
    name: Fonts
  - description: Manage duplicate pages. Duplicate pages are identified by a page hash.
    name: Duplicate Pages
  - description: Manage collections.
    name: Collections
  - description: Manage posters for collections.
    name: Collection Poster
  - name: Collection Series
  - description: Manage readlists.
    name: Readlists
  - description: Manage posters for readlists.
    name: Readlist Poster
  - name: Readlist Books
  - description: Retrieve referential metadata from all items in the Komga server.
    name: Referential metadata
  - description: Manage current user.
    name: Current user
  - description: Manage users.
    name: Users
  - description: Manage API Keys
    name: API Keys
  - name: User session
  - description: List registered OAuth2 providers
    name: OAuth2
  - description: Sync points are automatically created during a Kobo sync.
    name: Sync points
  - description: Claim a freshly installed Komga server.
    name: Claim
  - description: Manage server tasks
    name: Tasks
  - description: Server events history
    name: History
  - description: List files from the host server's file system
    name: File system
  - description: Store and retrieve server settings
    name: Server settings
  - description: Retrieve releases information
    name: Releases
  - description: Retrieve announcements from the Komga website
    name: Announcements
  - description: Manage server
    name: Management
  - name: Mihon
  - name: ComicRack
  - description: >-
      Store and retrieve global and per-user settings. Those settings are not
      used by Komga itself, but can be stored for convenience by client
      applications.
    name: Client settings
externalDocs:
  description: Komga documentation
  url: https://komga.org
paths:
  /api/v1/books/{bookId}/progression:
    get:
      tags:
        - WebPub Manifest
      summary: Get book progression
      description: >-
```

--------------------------------

### Configure Authentication in Komga SDK

Source: https://komga-sdk.mintlify.site/reference/configuration

Demonstrates initializing the client with Basic, API-key, or anonymous authentication.

```typescript
import { createKomgaClient } from 'komga-sdk';

const basicClient = createKomgaClient({
  baseUrl: 'https://komga.example.test',
  auth: { type: 'basic', username: 'admin', password: 'password' },
});

const apiKeyClient = createKomgaClient({
  baseUrl: 'https://komga.example.test',
  auth: { type: 'apiKey', key: 'your-api-key' },
});

const anonymousClient = createKomgaClient({
  baseUrl: 'https://komga.example.test',
});
```

--------------------------------

### OpenAPI definition for get next book in series

Source: https://komga-sdk.mintlify.site/api-reference/books/get-next-book-in-series

The OpenAPI specification for the GET /api/v1/books/{bookId}/next endpoint.

```yaml
openapi: 3.1.0
info:
  description: >-
    Komga REST API.


    ## Reference


    Check the API reference:

    - on the [Komga website](https://komga.org/docs/openapi/komga-api)

    - on any running Komga instance at `/swagger-ui.html`

    - on
    [GitHub](https://raw.githubusercontent.com/gotson/komga/refs/heads/master/komga/docs/openapi.json)


    ## Authentication


    Most endpoints require authentication. Authentication is done using either:

    - Basic Authentication

    - Passing an API Key in the `X-API-Key` header


    ## Sessions


    Upon successful authentication, a session is created, and can be reused.


    - By default, a `KOMGA-SESSION` cookie is set via `Set-Cookie` response
    header. This works well for browsers and clients that can handle cookies.

    - If you specify a header `X-Auth-Token` during authentication, the session
    ID will be returned via this same header. You can then pass that header
    again for subsequent requests to reuse the session.


    If you need to set the session cookie later on, you can call
    `/api/v1/login/set-cookie` with `X-Auth-Token`. The response will contain
    the `Set-Cookie` header.


    ## Remember Me


    During authentication, if a request parameter `remember-me` is passed and
    set to `true`, the server will also return a `komga-remember-me` cookie.
    This cookie will be used to login automatically even if the session has
    expired.


    ## Logout


    You can explicitly logout an existing session by calling `/api/logout`. This
    would return a `204`.


    ## Deprecation


    API endpoints marked as deprecated will be removed in the next major
    version.
  license:
    name: MIT
    url: https://github.com/gotson/komga/blob/master/LICENSE
  title: Komga API
  version: 1.25.0
servers:
  - url: https://demo.komga.org
    description: Demo server
  - url: http://localhost:{port}
    description: Local development server
    variables:
      port:
        enum:
          - '8080'
          - '25600'
        default: '25600'
security:
  - basicAuth: []
  - apiKey: []
tags:
  - name: Deprecated
  - description: Manage libraries.
    name: Libraries
  - description: Manage series.
    name: Series
  - description: Manage posters for series.
    name: Series Poster
  - description: Manage books.
    name: Books
  - description: Manage posters for books.
    name: Book Poster
  - name: Book Pages
  - name: WebPub Manifest
  - name: Import
  - description: Provide font files and CSS for the Epub Reader.
    name: Fonts
  - description: Manage duplicate pages. Duplicate pages are identified by a page hash.
    name: Duplicate Pages
  - description: Manage collections.
    name: Collections
  - description: Manage posters for collections.
    name: Collection Poster
  - name: Collection Series
  - description: Manage readlists.
    name: Readlists
  - description: Manage posters for readlists.
    name: Readlist Poster
  - name: Readlist Books
  - description: Retrieve referential metadata from all items in the Komga server.
    name: Referential metadata
  - description: Manage current user.
    name: Current user
  - description: Manage users.
    name: Users
  - description: Manage API Keys
    name: API Keys
  - name: User session
  - description: List registered OAuth2 providers
    name: OAuth2
  - description: Sync points are automatically created during a Kobo sync.
    name: Sync points
  - description: Claim a freshly installed Komga server.
    name: Claim
  - description: Manage server tasks
    name: Tasks
  - description: Server events history
    name: History
  - description: List files from the host server's file system
    name: File system
  - description: Store and retrieve server settings
    name: Server settings
  - description: Retrieve releases information
    name: Releases
  - description: Retrieve announcements from the Komga website
    name: Announcements
  - description: Manage server
    name: Management
  - name: Mihon
  - name: ComicRack
  - description: >-
      Store and retrieve global and per-user settings. Those settings are not
      used by Komga itself, but can be stored for convenience by client
      applications.
    name: Client settings
externalDocs:
  description: Komga documentation
  url: https://komga.org
paths:
  /api/v1/books/{bookId}/next:
    get:
      tags:
        - Books
      summary: Get next book in series
      operationId: getBookSiblingNext
      parameters:
        - in: path
          name: bookId
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
```

--------------------------------

### Komga SDK Client Usage

Source: https://komga-sdk.mintlify.site/domain-services

Demonstrates how to initialize the Komga client and invoke an operation function.

```APIDOC
## SDK Operation Invocation

### Description
Initialize a Komga client and use it to call generated operation functions like `getBookById`.

### Usage
```typescript
import { createKomgaClient, getBookById, unwrap } from 'komga-sdk';

const client = createKomgaClient({
  baseUrl: 'http://localhost:25600',
  auth: { type: 'basic', username: 'admin', password: 'password' },
});

const book = unwrap(await getBookById({ bookId: 'book-123' }, { client }));
```
```

--------------------------------

### GET /api/v1/authors

Source: https://komga-sdk.mintlify.site/api-reference/deprecated/list-authors

Retrieves a list of authors. This endpoint is deprecated since version 1.20.0 and users should use GET /api/v2/authors instead.

```APIDOC
## GET /api/v1/authors

### Description
Retrieves a list of authors. This endpoint is deprecated since version 1.20.0 and users should use GET /api/v2/authors instead.

### Method
GET

### Endpoint
/api/v1/authors

### Parameters
#### Query Parameters
- **search** (string) - Optional - Search term to filter authors.
- **library_id** (string) - Optional - Filter authors by library ID.
- **collection_id** (string) - Optional - Filter authors by collection ID.
- **series_id** (string) - Optional - Filter authors by series ID.

### Response
#### Success Response (200)
- **Array of AuthorDto** (object) - A list of author objects containing name and role.
```

--------------------------------

### OpenAPI Specification for Get Library by ID

Source: https://komga-sdk.mintlify.site/api-reference/libraries/get-details-for-a-single-library

The OpenAPI definition for the GET /api/v1/libraries/{libraryId} endpoint, including server configurations and authentication methods.

```yaml
openapi: 3.1.0
info:
  description: >-
    Komga REST API.


    ## Reference


    Check the API reference:

    - on the [Komga website](https://komga.org/docs/openapi/komga-api)

    - on any running Komga instance at `/swagger-ui.html`

    - on
    [GitHub](https://raw.githubusercontent.com/gotson/komga/refs/heads/master/komga/docs/openapi.json)


    ## Authentication


    Most endpoints require authentication. Authentication is done using either:

    - Basic Authentication

    - Passing an API Key in the `X-API-Key` header


    ## Sessions


    Upon successful authentication, a session is created, and can be reused.


    - By default, a `KOMGA-SESSION` cookie is set via `Set-Cookie` response
    header. This works well for browsers and clients that can handle cookies.

    - If you specify a header `X-Auth-Token` during authentication, the session
    ID will be returned via this same header. You can then pass that header
    again for subsequent requests to reuse the session.


    If you need to set the session cookie later on, you can call
    `/api/v1/login/set-cookie` with `X-Auth-Token`. The response will contain
    the `Set-Cookie` header.


    ## Remember Me


    During authentication, if a request parameter `remember-me` is passed and
    set to `true`, the server will also return a `komga-remember-me` cookie.
    This cookie will be used to login automatically even if the session has
    expired.


    ## Logout


    You can explicitly logout an existing session by calling `/api/logout`. This
    would return a `204`.


    ## Deprecation


    API endpoints marked as deprecated will be removed in the next major
    version.
  license:
    name: MIT
    url: https://github.com/gotson/komga/blob/master/LICENSE
  title: Komga API
  version: 1.25.0
servers:
  - url: https://demo.komga.org
    description: Demo server
  - url: http://localhost:{port}
    description: Local development server
    variables:
      port:
        enum:
          - '8080'
          - '25600'
        default: '25600'
security:
  - basicAuth: []
  - apiKey: []
tags:
  - name: Deprecated
  - description: Manage libraries.
    name: Libraries
  - description: Manage series.
    name: Series
  - description: Manage posters for series.
    name: Series Poster
  - description: Manage books.
    name: Books
  - description: Manage posters for books.
    name: Book Poster
  - name: Book Pages
  - name: WebPub Manifest
  - name: Import
  - description: Provide font files and CSS for the Epub Reader.
    name: Fonts
  - description: Manage duplicate pages. Duplicate pages are identified by a page hash.
    name: Duplicate Pages
  - description: Manage collections.
    name: Collections
  - description: Manage posters for collections.
    name: Collection Poster
  - name: Collection Series
  - description: Manage readlists.
    name: Readlists
  - description: Manage posters for readlists.
    name: Readlist Poster
  - name: Readlist Books
  - description: Retrieve referential metadata from all items in the Komga server.
    name: Referential metadata
  - description: Manage current user.
    name: Current user
  - description: Manage users.
    name: Users
  - description: Manage API Keys
    name: API Keys
  - name: User session
  - description: List registered OAuth2 providers
    name: OAuth2
  - description: Sync points are automatically created during a Kobo sync.
    name: Sync points
  - description: Claim a freshly installed Komga server.
    name: Claim
  - description: Manage server tasks
    name: Tasks
  - description: Server events history
    name: History
  - description: List files from the host server's file system
    name: File system
  - description: Store and retrieve server settings
    name: Server settings
  - description: Retrieve releases information
    name: Releases
  - description: Retrieve announcements from the Komga website
    name: Announcements
  - description: Manage server
    name: Management
  - name: Mihon
  - name: ComicRack
  - description: >-
      Store and retrieve global and per-user settings. Those settings are not
      used by Komga itself, but can be stored for convenience by client
      applications.
    name: Client settings
externalDocs:
  description: Komga documentation
  url: https://komga.org
paths:
  /api/v1/libraries/{libraryId}:
    get:
      tags:
        - Libraries
      summary: Get details for a single library
      operationId: getLibraryById
      parameters:
        - in: path
          name: libraryId
          required: true
          schema:
            type: string
      responses:
```

--------------------------------

### Create a Komga Client

Source: https://komga-sdk.mintlify.site/direct-api

Initializes a client instance with basic authentication. Supports various authentication methods and custom configurations.

```typescript
import { createKomgaClient } from 'komga-sdk';

const client = createKomgaClient({
  baseUrl: 'http://localhost:25600',
  auth: { type: 'basic', username: 'admin', password: 'password' },
});
```

--------------------------------

### OpenAPI Specification for Get Previous Book

Source: https://komga-sdk.mintlify.site/api-reference/books/get-previous-book-in-series

Defines the GET request structure for retrieving the previous book using a book ID path parameter.

```yaml
paths:
  /api/v1/books/{bookId}/previous:
    get:
      tags:
        - Books
      summary: Get previous book in series
      operationId: getBookSiblingPrevious
      parameters:
        - in: path
          name: bookId
          required: true
          schema:
            type: string
      responses:
        '200':
```

--------------------------------

### Initialize Komga Client with Environment Variables

Source: https://komga-sdk.mintlify.site/quick-reference

Uses environment variables to configure the base URL and API key for the Komga client instance.

```typescript
import { createKomgaClient } from 'komga-sdk';

const client = createKomgaClient({
  baseUrl: process.env.KOMGA_URL ?? 'http://localhost:25600',
  auth: {
    type: 'apiKey',
    key: process.env.KOMGA_API_KEY!,
  },
});
```

--------------------------------

### Initialize Komga Client

Source: https://komga-sdk.mintlify.site/guides/migration

Replaces the legacy createClient and service instance pattern with a single client configuration.

```typescript
createKomgaClient({ baseUrl, auth, headers, credentials, fetch })
```

--------------------------------

### GET /api/v1/fonts/families

Source: https://komga-sdk.mintlify.site/api-reference/fonts/list-font-families

Fetches all available font families.

```APIDOC
## GET /api/v1/fonts/families

### Description
List all available font families.

### Method
GET

### Endpoint
/api/v1/fonts/families
```

--------------------------------

### Initialize the Komga Client

Source: https://komga-sdk.mintlify.site/guides/migration

Use the createKomgaClient function to initialize the SDK. Ensure API key or Basic Auth is configured via the auth object.

```typescript
import { createKomgaClient } from 'komga-sdk';

const client = createKomgaClient({
  baseUrl: process.env.KOMGA_URL!,
  auth: {
    type: 'apiKey',
    key: process.env.KOMGA_API_KEY!,
  },
});
```

--------------------------------

### Create a new library

Source: https://komga-sdk.mintlify.site/guides/libraries

Creates a library using the LibraryCreationDto. Ensure paths provided are valid relative to the Komga server's filesystem.

```typescript
import { addLibrary, type LibraryCreationDto } from 'komga-sdk';

const libraryCreationDto: LibraryCreationDto = {
  name: 'Comics',
  root: '/data/comics',
  scanInterval: 'DAILY',
  seriesCover: 'FIRST',
  scanDirectoryExclusions: [],
  analyzeDimensions: false,
  convertToCbz: false,
  emptyTrashAfterScan: false,
  hashFiles: false,
  hashKoreader: false,
  hashPages: false,
  importBarcodeIsbn: false,
  importComicInfoBook: true,
  importComicInfoCollection: true,
  importComicInfoReadList: true,
  importComicInfoSeries: true,
  importComicInfoSeriesAppendVolume: false,
  importEpubBook: false,
  importEpubSeries: false,
  importLocalArtwork: true,
  importMylarSeries: false,
  repairExtensions: false,
  scanCbx: true,
  scanEpub: false,
  scanPdf: true,
  scanForceModifiedTime: false,
  scanOnStartup: true,
};

const result = await addLibrary({ libraryCreationDto }, { client });

if (result.error) {
  console.error('Library creation failed', result.error);
} else if (result.data) {
  console.log(`Created ${result.data.name} (${result.data.id})`);
}
```

--------------------------------

### GET /api/v1/collections

Source: https://komga-sdk.mintlify.site/api-reference/collections/list-collections

Retrieves a paginated list of collections.

```APIDOC
## GET /api/v1/collections

### Description
Retrieves a paginated list of collections available in the system.

### Method
GET

### Endpoint
/api/v1/collections

### Parameters
#### Query Parameters
- **unpaged** (boolean) - Optional - If true, returns all items without pagination.
- **page** (integer) - Optional - Zero-based page index (0..N).
- **size** (integer) - Optional - The size of the page to be returned.

### Response
#### Success Response (200)
- **content** (array) - List of CollectionDto objects.
- **totalElements** (integer) - Total number of elements.
- **totalPages** (integer) - Total number of pages.
- **size** (integer) - Number of elements per page.

#### Error Response (400)
- **violations** (array) - List of validation errors.
```

--------------------------------

### Get a specific thumbnail

Source: https://komga-sdk.mintlify.site/guides/book-content

Retrieves a specific thumbnail by its ID.

```typescript
import { getBookThumbnailById } from 'komga-sdk';

const result = await getBookThumbnailById(
  { bookId: 'book-123', thumbnailId: 'thumb-456' },
  { client },
);

if (result.error) {
  console.error('Thumbnail request failed', result.error);
} else if (result.data) {
  const thumbnailUrl = URL.createObjectURL(result.data);
}
```

--------------------------------

### Initialize Komga Client

Source: https://komga-sdk.mintlify.site/quick-reference

Configure the client with different authentication strategies. Ensure the baseUrl is provided and keep sensitive credentials secure on the server side.

```typescript
import { createKomgaClient } from 'komga-sdk';

const client = createKomgaClient({
  baseUrl: 'https://komga.example.com',
  auth: {
    type: 'basic',
    username: process.env.KOMGA_USER!,
    password: process.env.KOMGA_PASSWORD!,
  },
});
```

```typescript
import { createKomgaClient } from 'komga-sdk';

const client = createKomgaClient({
  baseUrl: 'https://komga.example.com',
  auth: { type: 'apiKey', key: process.env.KOMGA_API_KEY! },
});
```

```typescript
import { createKomgaClient } from 'komga-sdk';

const client = createKomgaClient({
  baseUrl: 'https://komga.example.com',
  credentials: 'include',
  headers: { 'X-Request-Source': 'reader-web' },
});
```

--------------------------------

### POST /api/v1/libraries

Source: https://komga-sdk.mintlify.site/api-reference/libraries/create-a-library

Creates a new library with the specified configuration settings.

```APIDOC
## POST /api/v1/libraries

### Description
Creates a new library in the system using the provided configuration object.

### Method
POST

### Endpoint
/api/v1/libraries

### Request Body
- **name** (string) - Required - The name of the library.
- **root** (string) - Required - The root directory path for the library.
- **analyzeDimensions** (boolean) - Required - Whether to analyze image dimensions.
- **convertToCbz** (boolean) - Required - Whether to convert files to CBZ format.
- **emptyTrashAfterScan** (boolean) - Required - Whether to empty trash after scanning.
- **hashFiles** (boolean) - Required - Whether to hash files.
- **hashKoreader** (boolean) - Required - Whether to hash Koreader metadata.
- **hashPages** (boolean) - Required - Whether to hash individual pages.
- **importBarcodeIsbn** (boolean) - Required - Whether to import ISBN from barcodes.
- **importComicInfoBook** (boolean) - Required - Whether to import ComicInfo for books.
- **importComicInfoCollection** (boolean) - Required - Whether to import ComicInfo for collections.
- **importComicInfoReadList** (boolean) - Required - Whether to import ComicInfo for read lists.
- **importComicInfoSeries** (boolean) - Required - Whether to import ComicInfo for series.
- **importComicInfoSeriesAppendVolume** (boolean) - Required - Whether to append volume info from ComicInfo.
- **importEpubBook** (boolean) - Required - Whether to import EPUB book metadata.
- **importEpubSeries** (boolean) - Required - Whether to import EPUB series metadata.
- **importLocalArtwork** (boolean) - Required - Whether to import local artwork.
- **importMylarSeries** (boolean) - Required - Whether to import Mylar series metadata.
- **repairExtensions** (boolean) - Required - Whether to repair file extensions.
- **scanCbx** (boolean) - Required - Whether to scan CBX files.
- **scanDirectoryExclusions** (array) - Required - List of directory paths to exclude from scanning.
- **scanEpub** (boolean) - Required - Whether to scan EPUB files.
- **scanForceModifiedTime** (boolean) - Required - Whether to force scan based on modified time.
- **scanInterval** (string) - Required - Scan frequency (DISABLED, HOURLY, EVERY_6H, EVERY_12H, DAILY, WEEKLY).
- **scanOnStartup** (boolean) - Required - Whether to scan on application startup.
- **scanPdf** (boolean) - Required - Whether to scan PDF files.
- **seriesCover** (string) - Required - Strategy for series cover selection (FIRST, FIRST_UNREAD_OR_FIRST, FIRST_UNREAD_OR_LAST, LAST).

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created library.
```

--------------------------------

### GET /api/v1/readlists

Source: https://komga-sdk.mintlify.site/api-reference/readlists/list-readlists

Retrieves a paginated list of read lists.

```APIDOC
## GET /api/v1/readlists

### Description
Retrieves a paginated list of read lists.

### Method
GET

### Endpoint
/api/v1/readlists

### Parameters
#### Query Parameters
- **unpaged** (boolean) - Optional - Whether to return all results without pagination.
- **page** (integer) - Optional - Zero-based page index (0..N).
- **size** (integer) - Optional - The size of the page to be returned.

### Response
#### Success Response (200)
- **content** (array) - List of ReadListDto objects.
- **empty** (boolean) - Whether the page is empty.
- **first** (boolean) - Whether this is the first page.
- **last** (boolean) - Whether this is the last page.
- **number** (integer) - Current page number.
- **numberOfElements** (integer) - Number of elements on this page.
- **pageable** (object) - Pagination information.
- **size** (integer) - Page size.
- **sort** (object) - Sorting information.
- **totalElements** (integer) - Total number of elements.
- **totalPages** (integer) - Total number of pages.

#### Error Response (400)
- **violations** (array) - List of validation errors.
```

--------------------------------

### Implement a reading order navigator with TypeScript

Source: https://komga-sdk.mintlify.site/guides/series-discovery

A class-based helper to navigate between sibling books in a series.

```typescript
import { getBookSiblingNext, getBookSiblingPrevious } from 'komga-sdk';

class ReadingNavigator {
  constructor(private currentBookId: string) {}

  async next() {
    const result = await getBookSiblingNext({ bookId: this.currentBookId }, { client });
    if (result.error) throw result.error;
    if (!result.data) return null;

    this.currentBookId = result.data.id;
    return result.data;
  }

  async previous() {
    const result = await getBookSiblingPrevious({ bookId: this.currentBookId }, { client });
    if (result.error) throw result.error;
    if (!result.data) return null;

    this.currentBookId = result.data.id;
    return result.data;
  }
}
```

--------------------------------

### GET /api/v1/readlists/{id}

Source: https://komga-sdk.mintlify.site/api-reference/readlists/get-readlist-details

Retrieves the details of a readlist by its ID.

```APIDOC
## GET /api/v1/readlists/{id}

### Description
Retrieves the details of a specific readlist using its unique identifier.

### Method
GET

### Endpoint
/api/v1/readlists/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the readlist.

### Response
#### Success Response (200)
- **bookIds** (array) - List of book IDs in the readlist
- **createdDate** (string) - Creation date in date-time format
- **filtered** (boolean) - Whether the readlist is filtered
- **id** (string) - The readlist ID
- **lastModifiedDate** (string) - Last modification date in date-time format
- **name** (string) - The name of the readlist
- **ordered** (boolean) - Whether the readlist is ordered
- **summary** (string) - A summary of the readlist

#### Error Response (400)
- **violations** (array) - List of validation errors
```

--------------------------------

### Using compile-time types

Source: https://komga-sdk.mintlify.site/validation

Demonstrates importing and using generated DTOs and search types from the SDK.

```typescript
import type { BookDto, BookSearch, GetBookByIdError, PageBookDto } from 'komga-sdk';

const search: BookSearch = { fullTextSearch: 'manga' };

function title(book: BookDto): string {
  return book.metadata.title;
}

function items(page: PageBookDto): BookDto[] {
  return page.content ?? [];
}
```

--------------------------------

### GET /api/v1/oauth2/providers

Source: https://komga-sdk.mintlify.site/api-reference/oauth2/list-registered-oauth2-providers

Retrieves a list of all registered OAuth2 providers.

```APIDOC
## GET /api/v1/oauth2/providers

### Description
Retrieves a list of all registered OAuth2 providers configured on the server.

### Method
GET

### Endpoint
/api/v1/oauth2/providers

### Response
#### Success Response (200)
- **Array** (OAuth2ClientDto) - A list of registered OAuth2 providers.

#### Response Example
[
  {
    "name": "Google",
    "registrationId": "google"
  }
]
```

--------------------------------

### createKomgaClient

Source: https://komga-sdk.mintlify.site/direct-api

Initializes a new Komga client instance with base URL and authentication configuration.

```APIDOC
## createKomgaClient

### Description
Initializes a client instance to interact with the Komga API. Supports basic auth, API-key, and custom fetch configurations.

### Signature
`createKomgaClient(options: { baseUrl: string, auth?: { type: string, username?: string, password?: string } })`

### Example
```typescript
import { createKomgaClient } from 'komga-sdk';

const client = createKomgaClient({
  baseUrl: 'http://localhost:25600',
  auth: { type: 'basic', username: 'admin', password: 'password' },
});
```
```

--------------------------------

### GET /api/v1/historical-events

Source: https://komga-sdk.mintlify.site/api-reference/history/list-historical-events

Retrieves a paginated list of historical events.

```APIDOC
## GET /api/v1/historical-events

### Description
Retrieves a paginated list of historical events.

### Method
GET

### Endpoint
/api/v1/historical-events

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number to be returned
- **size** (integer) - Optional - The size of the page to be returned
- **sort** (array) - Optional - Sorting criteria in the format: property(,asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

### Response
#### Success Response (200)
- **content** (array) - List of HistoricalEventDto
- **empty** (boolean) - Whether the page is empty
- **first** (boolean) - Whether this is the first page
- **last** (boolean) - Whether this is the last page
- **number** (integer) - Current page number
- **numberOfElements** (integer) - Number of elements on this page
- **pageable** (object) - Pagination information
- **size** (integer) - Page size
- **sort** (object) - Sorting information
- **totalElements** (integer) - Total number of elements
- **totalPages** (integer) - Total number of pages

#### Error Response (400)
- **violations** (array) - List of validation errors
```

--------------------------------

### Configure Headers, Credentials, and Fetch

Source: https://komga-sdk.mintlify.site/reference/configuration

Shows how to add custom headers, enable credential inclusion for CORS, and provide a custom fetch implementation.

```typescript
const client = createKomgaClient({
  baseUrl: 'https://komga.example.test',
  headers: {
    'X-Request-Source': 'reader-web',
  },
  credentials: 'include',
  fetch: globalThis.fetch,
});
```

--------------------------------

### Claim the server

Source: https://komga-sdk.mintlify.site/guides/admin

Create the initial admin account using email and password headers. This endpoint can only be called once.

```typescript
import { claimServer } from 'komga-sdk';

const result = await claimServer(
  {
    'X-Komga-Email': 'admin@example.com',
    'X-Komga-Password': 'secure-admin-password',
  },
  { client },
);

if (result.error) {
  console.error(result.response?.status, result.error);
} else {
  console.log(`Created admin user ${result.data?.id}`);
}
```

--------------------------------

### GET /api/v1/fonts/families

Source: https://komga-sdk.mintlify.site/api-reference/fonts/list-font-families

Retrieves a list of all available font families.

```APIDOC
## GET /api/v1/fonts/families

### Description
List all available font families.

### Method
GET

### Endpoint
/api/v1/fonts/families

### Response
#### Success Response (200)
- **body** (array of strings) - A list of unique font family names.

#### Error Response (400)
- **violations** (array) - A list of validation errors if the request is invalid.
```

--------------------------------

### Make a request with basic authentication

Source: https://komga-sdk.mintlify.site/

Shows how to configure the client with basic authentication and handle non-throwing request results.

```typescript
import { createKomgaClient, getBookById } from 'komga-sdk';

const client = createKomgaClient({
  baseUrl: 'http://localhost:25600',
  auth: {
    type: 'basic',
    username: 'admin@example.com',
    password: 'your-password',
  },
});

const result = await getBookById({ bookId: 'book-123' }, { client });

if (result.error) {
  console.error('Request failed', result.response?.status, result.error);
} else {
  console.log(result.data.metadata.title);
}
```

--------------------------------

### GET /api/v2/users/me

Source: https://komga-sdk.mintlify.site/api-reference/current-user/retrieve-current-user

Retrieves the details of the currently authenticated user.

```APIDOC
## GET /api/v2/users/me

### Description
Retrieves the profile information for the currently authenticated user.

### Method
GET

### Endpoint
/api/v2/users/me

### Parameters
#### Query Parameters
- **remember-me** (boolean) - Optional - Whether to set a remember-me cookie.
```

--------------------------------

### GET /api/v1/claim

Source: https://komga-sdk.mintlify.site/api-reference/claim/retrieve-claim-status

Check whether this server has already been claimed.

```APIDOC
## GET /api/v1/claim

### Description
Check whether this server has already been claimed.

### Method
GET

### Endpoint
/api/v1/claim

### Response
#### Success Response (200)
- **isClaimed** (boolean) - Indicates if the server is claimed.

#### Response Example
{
  "isClaimed": true
}
```

--------------------------------

### Compose a domain workflow for series overview

Source: https://komga-sdk.mintlify.site/domain-services

Demonstrates how to chain multiple SDK operations to fetch series and book data while handling potential errors.

```typescript
import { getBooks, getSeriesById } from 'komga-sdk';

export async function loadSeriesOverview(seriesId: string) {
  const seriesResult = await getSeriesById({ seriesId }, { client });
  if (seriesResult.error) {
    return { series: undefined, books: undefined, error: seriesResult.error };
  }

  const booksResult = await getBooks(
    {
      bookSearch: {},
      page: 0,
      size: 20,
      sort: ['metadata.number,asc'],
    },
    { client },
  );

  if (booksResult.error) {
    return { series: seriesResult.data, books: undefined, error: booksResult.error };
  }

  return { series: seriesResult.data, books: booksResult.data.content ?? [] };
}
```

--------------------------------

### Initialize the Komga client

Source: https://komga-sdk.mintlify.site/quickstart

Requires a baseUrl and optional authentication. The client uses native Fetch and does not include built-in retries or caching.

```typescript
import { createKomgaClient } from 'komga-sdk';

export const client = createKomgaClient({
  baseUrl: process.env.KOMGA_URL ?? 'http://localhost:25600',
  auth: {
    type: 'basic',
    username: process.env.KOMGA_USER!,
    password: process.env.KOMGA_PASSWORD!,
  },
});
```

--------------------------------

### GET /api/v1/claim

Source: https://komga-sdk.mintlify.site/api-reference/claim/retrieve-claim-status

Check whether this server has already been claimed.

```APIDOC
## GET /api/v1/claim

### Description
Check whether this server has already been claimed.

### Method
GET

### Endpoint
/api/v1/claim
```

--------------------------------

### Configure Komga Client for Integration Testing

Source: https://komga-sdk.mintlify.site/guides/testing

Use environment variables to manage server credentials and URLs for end-to-end testing.

```typescript
import { createKomgaClient, getCurrentUser } from 'komga-sdk';

const client = createKomgaClient({
  baseUrl: process.env.KOMGA_URL ?? 'http://localhost:25600',
  auth: {
    type: 'basic',
    username: process.env.KOMGA_USER ?? 'admin',
    password: process.env.KOMGA_PASSWORD ?? 'password',
  },
});

const result = await getCurrentUser(undefined, { client });
if (result.error) {
  throw new Error(`Komga request failed: ${result.response?.status}`);
}

console.log(result.data?.email);
```

--------------------------------

### addLibrary

Source: https://komga-sdk.mintlify.site/guides/libraries

Creates a new library in the Komga system.

```APIDOC
## addLibrary

### Description
Creates a new library with the provided configuration settings.

### Signature
`addLibrary({ libraryCreationDto }, { client })`

### Parameters
- **libraryCreationDto** (LibraryCreationDto) - Required - The configuration object containing library settings such as name, root path, and scanning preferences.
- **client** (object) - Required - The Komga client instance.
```

--------------------------------

### Configure environment variables

Source: https://komga-sdk.mintlify.site/authentication

Define the base URL and authentication credentials in a .env file.

```dotenv
KOMGA_URL=https://komga.example.com
KOMGA_USER=admin@example.com
KOMGA_PASSWORD=replace-me
KOMGA_API_KEY=replace-me
```