Generated API operations

Komga SDK 1.0 exposes the Komga API as generated operation functions. The functions map directly to the OpenAPI operations and use generated TypeScript types. The SDK no longer includes domain-service classes, handwritten DTO schemas, or service-specific error hierarchies.

The 1.0 call shape

Create a client once, then pass it in the operation options. Operation parameters are flat: endpoint inputs are properties of the first argument rather than nested transport-slot objects.

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);

The default result contains { data, error, request, response }. It does not throw for an API error by default. Use unwrap when a call site should throw a KomgaApiError instead.

For an operation with no endpoint parameters, the options object is the only argument. For example, call getLibraries({ client }).

Operation families

The generated barrel re-exports operation functions and their generated response and error types. Common operations include:

Operation	Parameters	Successful data
`getBooks`	`bookSearch`, `page`, `size`, `sort`, `unpaged`	`PageBookDto`
`getBookById`	`bookId`	`BookDto`
`getBookPages`	`bookId`	`PageDto[]`
`getSeriesById`	`seriesId`	`SeriesDto`
`getBooksBySeriesId`	`seriesId`, list parameters	`PageBookDto`
`getLibraries`	none	`LibraryDto[]`
`getLibraryById`	`libraryId`	`LibraryDto`
`getCollections`	`search`, `library_id`, page parameters	`PageCollectionDto`
`getReadLists`	`search`, `library_id`, page parameters	`PageReadListDto`

The generated types are the source of truth for each operation’s parameters and response. The API Reference links to the Komga 1.25.0 OpenAPI document used by the generated surface.

Build a domain workflow in your application

A domain workflow can compose operations without reintroducing a second SDK abstraction:

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 ?? [] };
}

Keep application-specific caching, authorization decisions, pagination state, and UI models in the wrapper. Do not silently assume that a successful result has every optional page field populated.

Common book workflows

Read book details and pages as separate generated operations:

import { getBookById, getBookPages } from 'komga-sdk';

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

if (book.error === undefined && pages.error === undefined) {
  console.log(`${book.data.metadata.title}: ${pages.data.length} pages`);
}

Metadata updates use the generated DTO property and return 204 No Content on success:

import { updateBookMetadata } from 'komga-sdk';

const result = await updateBookMetadata(
  {
    bookId: 'book-123',
    bookMetadataUpdateDto: { title: 'New title' },
  },
  { client },
);

if (result.error) {
  console.error(result.response?.status, result.error);
}

Read-progress updates follow the same result contract. Use page or completed according to the generated ReadProgressUpdateDto:

import { markBookReadProgress } from 'komga-sdk';

const result = await markBookReadProgress(
  {
    bookId: 'book-123',
    readProgressUpdateDto: { page: 12 },
  },
  { client },
);

Series, library, and administrative workflows

Series metadata and library configuration mutations carry permissions documented on the generated operation. For example:

import {
  getBooksBySeriesId,
  updateSeriesMetadata,
  updateLibraryById,
  libraryScan,
} from 'komga-sdk';

const books = await getBooksBySeriesId(
  { seriesId: 'series-123', page: 0, size: 50, sort: ['metadata.number,asc'] },
  { client },
);

const metadata = await updateSeriesMetadata(
  {
    seriesId: 'series-123',
    seriesMetadataUpdateDto: { title: 'Updated series' },
  },
  { client },
);

const library = await updateLibraryById(
  {
    libraryId: 'library-123',
    libraryUpdateDto: { name: 'Comics' },
  },
  { client },
);

const scan = await libraryScan({ libraryId: 'library-123', deep: true }, { client });

The generated comments mark operations that require ADMIN or another role. A 403 should be surfaced to the operator; do not retry unchanged credentials. Library scans are server-side work and may complete after the operation returns, so track task state through the Komga endpoints or UI rather than treating the request as a synchronous import.

Collections and read lists

These endpoints are not domain-service methods in 1.0. Call them directly with their generated query names:

import { getCollections, getReadLists } from 'komga-sdk';

const collections = await getCollections(
  { search: 'favorites', library_id: ['library-123'], page: 0, size: 20 },
  { client },
);
const readLists = await getReadLists({ search: 'to-read', page: 0, size: 20 }, { client });

Use content ?? [] and inspect error before rendering page data. See Pagination for list iteration and sorting.

Migration from service wrappers

Replace a service method with an operation import and a client option:

Previous wrapper call	1.0 operation call
`service.getById(id)` for a book	`getBookById({ bookId: id }, { client })`
`service.list({ page, size, search })` for books	`getBooks({ page, size, bookSearch: search }, { client })`
`service.getById(id)` for a series	`getSeriesById({ seriesId: id }, { client })`
`service.getAll()` for libraries	`getLibraries({ client })`
`service.getById(id)` for a library	`getLibraryById({ libraryId: id }, { client })`
`service.scan(id)` for a library	`libraryScan({ libraryId: id }, { client })`

Wrap the new call with unwrap only if throwing behavior is preferable. BookSearch currently contains fullTextSearch and an optional generated condition; pass that generated shape directly instead of the former service-layer search object.

What moved to the application

The core SDK intentionally stays close to Fetch and the generated contract:

Runtime response validation is optional and consumer-owned. See Runtime validation.
Retries, caching, pagination state, and query-library integration belong in the application layer.
Request and response lifecycle hooks are low-level generated-client interceptors. See Request customization.
HTTP failures are represented in the result or converted to KomgaApiError by unwrap. See Result handling.

Use generated operations and types directly; do not instantiate removed service classes or import runtime DTO schemas from the SDK.

Next steps

Direct API functions

Call generated operations with flat parameters.

Pagination

Handle generated page responses and list parameters.

Configuration

Configure authentication and Fetch behavior.

Get started

Core SDK

API guides

Reference

Generated API operations

The 1.0 call shape

Operation families

Build a domain workflow in your application

Common book workflows

Series, library, and administrative workflows

Collections and read lists

Migration from service wrappers

What moved to the application

Next steps

Direct API functions

Pagination

Configuration

​The 1.0 call shape

​Operation families

​Build a domain workflow in your application

​Common book workflows

​Series, library, and administrative workflows

​Collections and read lists

​Migration from service wrappers

​What moved to the application

​Next steps

Direct API functions

Pagination

Configuration

The 1.0 call shape

Operation families

Build a domain workflow in your application

Common book workflows

Series, library, and administrative workflows

Collections and read lists

Migration from service wrappers

What moved to the application

Next steps