Skip to main content

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 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:

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:
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:
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:
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 is pinned to the same Komga API version.

Next steps

Quickstart

Install the package, create a client, and make a typed request.

Authentication

Configure Basic Auth, API keys, headers, sessions, and Fetch credentials.

Quick reference

Copy common flat-call, result, pagination, and TypeScript patterns.