> ## 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.

# Introduction

> Start using the generated TypeScript client for Komga API 1.25.0

# Komga SDK

`komga-sdk` 1.0 is a generated TypeScript client for the Komga REST API. It targets Komga API **1.25.0**, exposes **165 operations**, and has **zero runtime dependencies**.

The package gives you:

* TypeScript types generated from the Komga API description
* Direct operation functions with flat endpoint parameters
* Nonthrowing request results containing `data`, `error`, `request`, and `response`
* An explicit `unwrap` helper when an exception boundary is useful
* A native Fetch client for Node.js, browsers, and compatible edge runtimes

> **Generated operations**
>
> Call the endpoint you need directly. Parameters match the generated operation signature.

> **Structured results**
>
> Requests return their result fields by default. Inspect `error` or `response` without wrapping every call in a `try`/`catch`.

> **Native Fetch**
>
> The SDK uses the platform Fetch API and accepts a custom Fetch implementation when your runtime needs one.

> **Basic and API-key auth**
>
> Configure HTTP Basic credentials or an `X-API-Key` once when you create the client.

## What is Komga?

[Komga](https://komga.org) is a media server for comics, manga, BDs, magazines, and ebooks. It organizes a digital library, manages metadata, and serves content to readers.

This SDK maps Komga's documented HTTP operations to typed functions. It intentionally does not add response validation, retries, caching, or logging on top of Fetch; those are application policies you can add at the boundary where they make sense.

## Choose an integration style

### Generated operations

Use a generated operation when you need the complete API surface or want the request and result contract visible at the call site. Each endpoint input is a property of one flat first argument; client configuration is the optional second argument:

```typescript theme={null}
import { createKomgaClient, getBookById, getLibraries } from 'komga-sdk';

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

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

if (book.error === undefined) {
  console.log(book.data.metadata.title);
}
```

### Application-owned wrappers

The 1.0 package does not include `BookService`, `SeriesService`, or `LibraryService` classes. If your application wants domain-oriented methods, compose a small repository around generated functions and choose whether it returns `KomgaResult` or calls `unwrap`. This keeps caching, pagination state, and business rules with the application that owns them.

## Make a request

Create a client, pass it as the second argument to an operation, and inspect the returned fields:

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

Generated requests are nonthrowing by default. A successful result has `data`; an HTTP, parsing, or network error has `error`. `request` and `response` are optional because a failure can occur before a `Request` or `Response` exists.

## Request and result anatomy

An operation's first object contains only endpoint inputs. The generated client maps those fields to path, query, or body slots:

```typescript theme={null}
import { getBooks } from 'komga-sdk';

const result = await getBooks(
  {
    page: 0,
    size: 20,
    sort: ['metadata.title,asc'],
    bookSearch: { fullTextSearch: 'manga' },
  },
  {
    client,
    // Per-call Fetch/generated-client options can be overridden here.
    headers: { 'X-Request-Source': 'search-screen' },
  },
);

if (result.error === undefined) {
  for (const book of result.data.content ?? []) {
    console.log(book.metadata.title);
  }
}
```

On success, `result.data` is the generated response type. On failure, `result.error` is the generated error payload (or a transport/parsing error), and `result.response?.status` gives the HTTP status when the server responded. The `request` and `response` objects are the original Fetch objects, which is useful for headers, tracing, and status-specific handling.

Successful empty responses, such as a `204 No Content` mutation, have `data: undefined`. Binary and text endpoints can be requested with generated Fetch options such as `parseAs: 'blob'`, `parseAs: 'arrayBuffer'`, or `parseAs: 'text'` when the endpoint's generated response type supports that representation.

## Opt into throwing errors

Use `unwrap` at the boundary where your application wants exceptions. It returns response data on success and throws `KomgaApiError` when the generated result contains an API error:

```typescript theme={null}
import { KomgaApiError, getBookById, unwrap } from 'komga-sdk';

try {
  const book = unwrap(await getBookById({ bookId: 'book-123' }, { client }));
  console.log(book.metadata.title);
} catch (error) {
  if (error instanceof KomgaApiError) {
    console.error('Komga returned', error.status, error.body);
  }
  throw error;
}
```

Keep calls nonthrowing when a response is an expected branch. Use `unwrap` when an exception is the clearer boundary for a repository, job, or request handler.

## Runtime requirements

The SDK uses platform APIs rather than a bundled HTTP library:

* Node.js 18 or newer
* A modern browser with Fetch, `Headers`, `Request`, `Response`, `TextEncoder`, and Web Crypto support
* An edge runtime that provides those same Web APIs

In a browser, avoid putting long-lived Basic credentials or API keys in a public bundle. Cookie sessions require the browser's `credentials` mode and server-side CORS permission. In Node or another host with a wrapped transport, pass a compatible implementation with the client's `fetch` option.

## API coverage

The generated client targets Komga API **1.25.0** with:

* **165 operations**
* Typed request parameters, response types, and documented error types
* Deprecated operations represented according to the generated API surface
* Zero runtime dependencies in the core package

The [API reference](/reference/api-reference) is pinned to the same Komga API version.

## Next steps

> **[Quickstart](/quickstart)**
>
> Install the package, create a client, and make a typed request.

> **[Authentication](/authentication)**
>
> Configure Basic Auth, API keys, headers, sessions, and Fetch credentials.

> **[Quick reference](/quick-reference)**
>
> Copy common flat-call, result, pagination, and TypeScript patterns.


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