Client Settings

Client settings store reader and UI preferences as key-to-setting maps. Global settings provide defaults for every user; user settings override a global value when the same key is present. Each generated operation returns { data, error, request, response }. Operations with parameters take a flat parameter object first and { client } second.

Global settings

List global settings

import { getGlobalSettings } from 'komga-sdk';

const result = await getGlobalSettings({ client });
for (const [key, setting] of Object.entries(result.data ?? {})) {
  console.log(`${key} = ${setting.value}`);
}

Unauthenticated requests receive only settings whose allowUnauthorized value is true. An authenticated response is still a map keyed by setting name, not an array.

Save global settings

Requires the ADMIN role.

saveGlobalSetting accepts a map. Every global value contains value and allowUnauthorized; setting the latter to false prevents unauthenticated clients from seeing the key:

import { saveGlobalSetting } from 'komga-sdk';

await saveGlobalSetting(
  {
    body: {
      'webui.theme.mode': { value: 'dark', allowUnauthorized: false },
      'reader.background': { value: 'BLACK', allowUnauthorized: true },
    },
  },
  { client },
);

Setting names are namespaced lower-case keys such as application.domain.key. The patch returns no content; inspect result.error if the save needs confirmation.

Delete global settings

Requires the ADMIN role.

Pass setting keys as the flat body parameter:

import { deleteGlobalSettings } from 'komga-sdk';

await deleteGlobalSettings(
  { body: ['webui.theme.mode', 'reader.background'] },
  { client },
);

Deleting a global key removes the default; it does not remove a user’s override of the same key.

User settings

List user settings

import { getUserSettings } from 'komga-sdk';

const result = await getUserSettings({ client });
for (const [key, setting] of Object.entries(result.data ?? {})) {
  console.log(`${key} = ${setting.value}`);
}

Save user settings

User setting values use the same map shape without allowUnauthorized:

import { saveUserSetting } from 'komga-sdk';

await saveUserSetting(
  {
    body: {
      'reader.pageFit': { value: 'WIDTH' },
      'reader.background': { value: 'BLACK' },
    },
  },
  { client },
);

Delete user settings

Deleting a key exposes the global default again when one exists:

import { deleteUserSettings } from 'komga-sdk';

await deleteUserSettings(
  { body: ['reader.pageFit', 'reader.background'] },
  { client },
);

Workflows

Apply global defaults with user overrides

Both responses are maps. Copy global entries first, then overwrite them with user entries:

import { getGlobalSettings, getUserSettings } from 'komga-sdk';

async function getEffectiveSettings() {
  const [global, user] = await Promise.all([
    getGlobalSettings({ client }),
    getUserSettings({ client }),
  ]);

  const effective = new Map<string, string>();
  for (const [key, setting] of Object.entries(global.data ?? {})) {
    effective.set(key, setting.value);
  }
  for (const [key, setting] of Object.entries(user.data ?? {})) {
    effective.set(key, setting.value);
  }
  return effective;
}

Reset user settings to defaults

Read the user map, collect its keys, then send those keys to the delete operation. An empty map needs no request:

import { deleteUserSettings, getUserSettings } from 'komga-sdk';

async function resetUserSettings() {
  const current = await getUserSettings({ client });
  const keys = Object.keys(current.data ?? {});
  if (keys.length === 0) return;

  await deleteUserSettings({ body: keys }, { client });
}

Update one setting while preserving others

Because save accepts a map, send only the key being changed; other user settings remain untouched:

import { saveUserSetting } from 'komga-sdk';

async function setPageFit(value: string) {
  return saveUserSetting(
    { body: { 'reader.pageFit': { value } } },
    { client },
  );
}

Handle failures

Generated calls do not throw for an HTTP error by default. A 401 indicates missing authentication; a 403 on global writes indicates that the caller is not an admin:

import { getGlobalSettings } from 'komga-sdk';

const result = await getGlobalSettings({ client });
if (result.error) {
  console.error('Settings request failed', result.response?.status, result.error);
}

Use unwrap when your application wants exceptions; it throws KomgaApiError for an unsuccessful result. See Quickstart for the pattern.

Next steps

Users

Manage users and per-user preferences.

Admin

Configure server-level administrative settings.

Authentication

Configure the client used by these operations.

Get started

Core SDK

API guides

Reference

Global settings

List global settings

Save global settings

Delete global settings

User settings

List user settings

Save user settings

Delete user settings

Workflows

Apply global defaults with user overrides

Reset user settings to defaults

Update one setting while preserving others

Handle failures

Next steps

Users

Admin

Authentication

​Global settings

​List global settings

​Save global settings

​Delete global settings

​User settings

​List user settings

​Save user settings

​Delete user settings

​Workflows

​Apply global defaults with user overrides

​Reset user settings to defaults

​Update one setting while preserving others

​Handle failures

​Next steps

Users

Admin

Authentication

Global settings

List global settings

Save global settings

Delete global settings

User settings

List user settings

Save user settings

Delete user settings

Workflows

Apply global defaults with user overrides

Reset user settings to defaults

Update one setting while preserving others

Handle failures

Next steps