FAQ

What does komga-sdk 1.0 contain?

komga-sdk 1.0 is generated from Komga API 1.25.0. It exposes 165 typed operations and has zero runtime dependencies. The core package provides generated operation functions, generated TypeScript types, createKomgaClient, unwrap, and KomgaApiError.The package does not include the former domain-service classes, handwritten DTO schemas, legacy error hierarchy, or built-in retry/cache middleware. Add those policies in your application when they are useful.

How do I call an operation?

Pass endpoint parameters as one flat object. Pass the configured client as the optional second argument:

import { getBookById } from 'komga-sdk';

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

Operations without endpoint parameters accept only the options object:

import { getLibraries } from 'komga-sdk';

const result = await getLibraries({ client });

The removed grouped { path, query, body } shape is not part of the 1.0 public operation signatures. Check the generated function or Direct API when an operation has a body plus query fields.

Which authentication methods are supported?

createKomgaClient supports:

HTTP Basic Auth with auth: { type: 'basic', username, password }
Komga API keys with auth: { type: 'apiKey', key }
No built-in authentication, when auth is omitted
Application-owned headers through headers
Fetch cookie credentials through credentials: 'include'

The SDK does not implement OAuth login, JWT/Bearer authentication, or a browser login UI. getOAuth2Providers can list server-configured providers, but the application must own any provider flow and session handoff. See Authentication for examples.

Can I use the SDK in a browser or Node.js?

Yes. The client uses native Fetch APIs and runs in Node.js 18+, modern browsers, and compatible edge runtimes. The runtime must provide Fetch, Headers, Request, Response, TextEncoder, and Web Crypto. Pass a custom fetch implementation to createKomgaClient when the host runtime needs one.For a browser session, configure credentials: 'include' and ensure Komga’s CORS and cookie policies allow the exact origin. Do not ship long-lived Basic credentials or API keys in a public bundle.

Do requests throw errors?

Not by default. A generated operation resolves to fields containing data, error, request, and response:

import { getBookById } from 'komga-sdk';

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

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

request and response are optional for request-construction and network failures. Use unwrap when your application wants a throwing boundary; it returns response data or throws KomgaApiError with status, body, request, and response fields.

What happens for void, binary, or text responses?

A successful 204 No Content operation has data: undefined; success is represented by error === undefined. Generated binary and text operations can use Fetch parser options:

import { getBookPageByNumber } from 'komga-sdk';

const result = await getBookPageByNumber(
  { bookId: 'book-123', pageNumber: 1 },
  { client, parseAs: 'blob' },
);

Use blob, arrayBuffer, or text only for an endpoint whose generated response supports that representation. Inspect the generated type before assuming a JSON object.

Does the SDK validate response bodies at runtime?

No. Generated TypeScript types provide compile-time guidance; the core client does not validate response bodies at runtime and does not export Zod schemas or validation helpers. Add an application-owned validator at the boundary where untrusted data enters your system. See Runtime validation.

Are retries, caching, or timeouts enabled?

No. The core client uses native Fetch and does not enable retries, caching, timeout handling, or debug logging by default. Add those policies around operation calls or provide a custom Fetch implementation. Any retry policy should account for whether an operation is safe to repeat, honor Retry-After, and avoid retrying 401 or 403 unchanged.

How do I customize Fetch or add logging?

Pass standard client options when creating the client:

import { createKomgaClient } from 'komga-sdk';

const client = createKomgaClient({
  baseUrl: 'https://komga.example.com',
  headers: { 'X-Request-Source': 'dashboard' },
  credentials: 'include',
  fetch: async (input, init) => fetch(input, init),
});

For lifecycle hooks, register client.interceptors.request, .response, or .error; use returns an id that can be passed to eject. Redact credentials and cookies, and remember that hooks run for every operation made with that client.

How do I paginate book results?

Use getBooks with its required bookSearch field and the flat page, size, sort, or unpaged parameters:

import { getBooks } from 'komga-sdk';

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

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

Page indexes are zero-based. Use last, totalPages, and content defensively because generated page fields may be optional. See Pagination.

What does a 401, 403, or 404 mean?

Inspect result.response?.status and result.error on the nonthrowing result. A 401 usually means configured credentials or a session were rejected, a 403 means the authenticated user lacks permission, and a 404 means the endpoint or resource was not found. If you use unwrap, inspect error instanceof KomgaApiError and its status and body fields.

Can I use separate clients for separate servers?

Yes. createKomgaClient returns an isolated client instance. Create one client per Komga server or distinct authentication context, then pass the appropriate { client } options object to each operation. Interceptors and custom Fetch implementations are also instance-local.

How do I use generated TypeScript types?

Import DTOs, search types, page types, and operation result types as type-only imports:

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

const search: BookSearch = { fullTextSearch: 'manga' };
function firstBook(page: PageBookDto): BookDto | undefined {
  return page.content?.[0];
}

Types describe the API contract to TypeScript; they do not prove that a runtime response is valid. Use an application-owned schema if your boundary needs runtime checks.

Get started

Core SDK

API guides

Reference

More information

​More information

More information