Fetch configuration

createKomgaClient creates an isolated generated client backed by the platform Fetch API. The required option is baseUrl; authentication and transport settings are optional.

KomgaClientOptions

import type { KomgaClientOptions } from 'komga-sdk';

const options: KomgaClientOptions = {
  baseUrl: 'https://komga.example.test',
  auth: { type: 'apiKey', key: 'your-api-key' },
  headers: { 'X-Client-Version': '1.0' },
  credentials: 'same-origin',
  fetch: globalThis.fetch,
};

The public convenience options are:

Option	Type	Purpose
`baseUrl`	`string`	Base URL for generated requests. Required.
`auth`	`AuthConfig`	Optional Basic or API-key authentication.
`headers`	`HeadersInit`	Headers added to every request, except auth-owned headers.
`credentials`	`RequestCredentials`	Fetch credentials mode, such as `include` for browser cookies.
`fetch`	`typeof fetch`	Fetch implementation used by this client instance.

The client also accepts generated Fetch configuration fields that are not reserved by createKomgaClient, including signal. Per-operation options can additionally override parseAs, responseStyle, and throwOnError. Keep operation-specific overrides in the second argument to an operation. Standard RequestInit fields such as method, body, and generated path/query slots are controlled by each operation and should not be supplied to createKomgaClient.

Authentication

AuthConfig supports Basic and API-key authentication:

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',
});

AuthConfig is limited to the Basic and API-key variants shown above. If a server-specific header is required, add it with headers or an application-owned interceptor. The SDK does not provide Bearer/JWT token configuration. Auth-owned headers take precedence over entries with the same name in headers: Basic auth sets Authorization, and API-key auth sets X-API-Key. Do not print a client’s resolved config because it may contain secrets.

Headers, credentials, and Fetch

Use custom headers for application metadata or server-specific headers:

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

credentials: 'include' asks browser Fetch to include cookies in cross-origin requests; Komga and the browser must also permit the exact origin through CORS. It does not create a session or log a user in. A custom Fetch wrapper is useful for tracing, proxies, or application-owned retry/cancellation behavior:

const fetchWithTiming: typeof fetch = async (input, init) => {
  const started = Date.now();
  try {
    return await fetch(input, init);
  } finally {
    console.log(`Komga request completed in ${Date.now() - started}ms`);
  }
};

const client = createKomgaClient({
  baseUrl: 'https://komga.example.test',
  fetch: fetchWithTiming,
});

The SDK core uses native Fetch and has no default retry, cache, timeout, or runtime-validation layer. Supply a custom Fetch implementation or compose policies around operation calls when your application owns those concerns. A client instance keeps its own configuration; create separate clients when environments or policies differ.

Use HTTPS when sending Basic credentials. In production, the SDK warns when Basic auth is configured with an http: base URL; use HTTPS rather than suppressing the warning.

Per-operation options

The second argument to a generated operation can override client behavior for one call:

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

const book = await getBookById(
  { bookId: 'book-123' },
  { client, signal: AbortSignal.timeout(10_000) },
);

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

Generated operations still own their endpoint URL, method, path, query, and body mapping. Do not replace those slots with the removed grouped call shape.

Generated client access

For advanced integrations, the package also re-exports the generated createClient function and its GeneratedClientConfig type. createKomgaClient is the convenience entry point that applies Komga authentication and headers before creating that generated client. Most applications should use createKomgaClient so the auth precedence and per-instance configuration remain explicit.

Next steps

Call operations with flat parameters: Direct API functions
Observe the generated Fetch lifecycle: Request customization
Handle { data, error, request, response }: Result handling

Get started

Core SDK

API guides

Reference

Fetch configuration

KomgaClientOptions

Authentication

Headers, credentials, and Fetch

Per-operation options

Generated client access

Next steps

​KomgaClientOptions

​Authentication

​Headers, credentials, and Fetch

​Per-operation options

​Generated client access

​Next steps

KomgaClientOptions

Authentication

Headers, credentials, and Fetch

Per-operation options

Generated client access

Next steps