> ## Documentation Index
> Fetch the complete documentation index at: https://komga-sdk.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Generated API operations

> Use generated Komga API operations and application-owned domain workflows

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.

```typescript theme={null}
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`](/errors) when a call site should throw a `KomgaApiError` instead.

> [!NOTE]
>
> 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](/reference/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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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`:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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](/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](/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](/interceptors).
* HTTP failures are represented in the result or converted to `KomgaApiError` by `unwrap`. See [Result handling](/errors).

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](/direct-api)**
>
> Call generated operations with flat parameters.

> **[Pagination](/pagination)**
>
> Handle generated page responses and list parameters.

> **[Configuration](/reference/configuration)**
>
> Configure authentication and Fetch behavior.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.