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

# Quickstart

> Install komga-sdk, create a client, and make your first typed request

Install `komga-sdk` and make a request against a Komga server.

## Prerequisites

> [!TIP]
>
> A Komga server that is reachable from your application. The default local server URL is `http://localhost:25600`.

> [!TIP]
>
> Node.js 18 or newer, a modern browser, or another runtime with Fetch, Web Crypto, `Headers`, `Request`, and `Response` APIs.

> [!TIP]
>
> A Komga username and password or an API key, unless your application supplies its own session headers.

## Install

**npm**

```bash theme={null}
npm install komga-sdk
```

**pnpm**

```bash theme={null}
pnpm add komga-sdk
```

**yarn**

```bash theme={null}
yarn add komga-sdk
```

**bun**

```bash theme={null}
bun add komga-sdk
```

The package is ESM. In a TypeScript project, use a current ESM-capable runtime or compile with `moduleResolution: "bundler"`; [TypeScript reference](/reference/typescript) includes a minimal configuration.

## Configure environment variables

Keep the server URL and credentials out of source control:

```dotenv title=".env" theme={null}
KOMGA_URL=http://localhost:25600
KOMGA_USER=admin@example.com
KOMGA_PASSWORD=replace-me
# Or use KOMGA_API_KEY instead of the Basic credentials.
KOMGA_API_KEY=replace-me
```

Load these values through your runtime's environment mechanism. Do not expose a long-lived API key or Basic password in a browser bundle; create a server-side boundary when the browser must access a private Komga server.

## Create a client

`createKomgaClient` requires a `baseUrl`. Authentication is optional:

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

export const client = createKomgaClient({
  baseUrl: process.env.KOMGA_URL ?? 'http://localhost:25600',
  auth: {
    type: 'basic',
    username: process.env.KOMGA_USER!,
    password: process.env.KOMGA_PASSWORD!,
  },
});
```

For a production integration, prefer `https://` whenever credentials leave the local machine. The client uses native Fetch and does not configure retries, timeouts, caching, or response validation. Add those concerns in your application or through a custom Fetch implementation when you need them.

## Make your first request

Generated operation parameters are flat. The client is passed in the optional second argument:

```typescript title="index.ts" theme={null}
import { getLibraries } from 'komga-sdk';
import { client } from './lib/komga.js';

const result = await getLibraries({ client });

if (result.error) {
  console.error('Komga request failed', result.response?.status, result.error);
} else {
  for (const library of result.data ?? []) {
    console.log(`${library.id}: ${library.name}`);
  }
}
```

A generated request resolves to `{ data, error, request, response }` by default. It does not throw for an HTTP error. Check `error` before reading `data`; `response` can be absent for a network or request-construction failure.

## Query a paginated endpoint

`getBooks` requires a `bookSearch` object and accepts pagination values in the same flat parameter object:

```typescript theme={null}
import { getBooks } from 'komga-sdk';
import { client } from './lib/komga.js';

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

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

## Browser session example

A browser application that already has a Komga session cookie can ask Fetch to include it:

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

const browserClient = createKomgaClient({
  baseUrl: 'https://komga.example.com',
  credentials: 'include',
});

const session = await getCurrentUser({ 'remember-me': true }, { client: browserClient });
if (session.error) {
  console.error('Session is not available', session.response?.status);
}
```

The SDK does not implement a login page or token exchange. For cross-origin requests, Komga and the browser must agree on an allowed origin and credentialed CORS policy.

## Use `unwrap` when you want exceptions

`unwrap` is the explicit throwing boundary. It returns generated data or throws `KomgaApiError`:

```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 && error.status === 404) {
    console.log('Book not found');
  } else {
    throw error;
  }
}
```

## Run the example

**tsx**

```bash theme={null}
npx tsx index.ts
```

**Bun**

```bash theme={null}
bun run index.ts
```

Replace `http://localhost:25600` with the URL of your Komga server. Keep credentials in environment variables or a secrets manager rather than source code.

## What's next?

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

> **[Quick reference](/quick-reference)**
>
> Review flat operation signatures, result handling, and pagination.

> **[Best practices](/best-practices)**
>
> Decide where to add application-owned retries, caching, and validation.


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