Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/kagisearch/kite-public/llms.txt

Use this file to discover all available pages before exploring further.

Kagi News follows a local-first model: all settings live in your browser’s localStorage and work without any account. Sync is an optional layer on top that mirrors those settings to Kagi’s servers so every device you sign in on starts with the same configuration.
Sync requires a Kagi account. Sign in via Settings → Sync & Privacy → Sign In. Sync works on web browsers and PWA installs. Native iOS and Android apps do not yet support settings sync.

​
Enabling sync

1

Sign in to your Kagi account

Open Settings (gear icon) and navigate to the Sync & Privacy tab. If you are not signed in, click the Sign In link, which redirects you to kagi.com/signin.
2

Enable Settings Sync

Toggle Sync Settings on. When you first enable it, your current local settings are immediately pushed to the server so all your devices receive your preferences.
3

(Optional) Enable Read History Sync

Toggle Sync Read History on. This performs an initial bulk upload of your local read history and then keeps it in sync incrementally. Stories you have already read on one device will appear as read on others.

​
What gets synced

Settings are grouped by category. Each category syncs as a unit:
CategorySettings included
appearanceTheme, font size
displayStory count, expand mode, open mode, maps provider, layout width
languageInterface language, data language, content languages
categoriesCategory order, enabled categories, disabled categories, single-page mode
contentContent filter level, custom keywords, filter presets, filter mode and scope, reading levels
sectionsSection visibility (summary, highlights, perspectives, Q&A, timeline, sources, etc.)
Sync is opt-in per category: you can sync settings without syncing read history, and vice versa.

​
How sync works

The SyncManager class (src/lib/client/sync-manager.ts) manages all sync operations as a singleton. Here is the flow for a typical settings change:
  1. You change a setting in the UI.
  2. The Setting class records the change and calls syncManager.trackSettingChange(key, value).
  3. The manager debounces the change — waiting 2 seconds to batch rapid sequential edits — then calls POST /api/sync with the pending changes.
  4. The server returns any remote changes made on other devices.
  5. The manager applies remote changes to localStorage and updates the reactive Svelte state so the UI reflects the new values immediately.

​
Conflict resolution

The default conflict resolution strategy is 'merge'. When the same setting is changed on two devices before either syncs, the server provides a merged resolution value. Alternative strategies ('local' — keep local; 'remote' — always use server) can be set programmatically via syncManager.setConflictStrategy().

​
Device identity

Each browser/device is assigned a unique deviceId (UUID v4) stored in localStorage. This ID is included in every sync request so the server can attribute changes to the correct device and skip sending a device its own changes.

​
Sync triggers

The SyncManager syncs in response to multiple events:
TriggerNotes
Settings changeDebounced 2 s after the last change in a batch
App becomes visibleFires on document.visibilitychange when the tab regains focus
Device comes back onlineFires on the window.online event
LoginPerforms a full sync immediately on syncManager.initialize(userId)
Another browser tab changes a settingCross-tab via localStorage storage events

​
SyncState

The current sync status is exposed through the SyncState interface: 
interface SyncState {
  isSyncing: boolean;       // A sync request is in flight
  lastSyncedAt: Date | null; // Timestamp of the last successful sync
  pendingChanges: number;   // Number of local changes not yet uploaded
  syncError: string | null; // Error message from the last failed sync, if any
  isOnline: boolean;        // Whether the browser reports network connectivity
}
Subscribe to state changes with syncManager.onSyncStateChange(listener).

​
Exporting your synced data

Use the export feature as a backup before making major changes to your settings. The exported file contains all your synced settings and can be used to restore or migrate your configuration.
To download a full JSON export of everything stored on Kagi’s servers for your account:
  1. Go to Settings → Sync & Privacy.
  2. Click Export Data.
  3. A file named kagi-news-sync-data-YYYY-MM-DD.json is downloaded automatically.
The export endpoint is: 
GET /api/sync/export
Requires an active session cookie (credentials: 'include').

​
Privacy

Your synced data is stored on Kagi’s servers and associated with your account. It is:
  • Not used for any purpose other than sync — Kagi does not analyse or monetise your settings or read history.
  • Not shared with third parties.
  • Fully deletable at any time: go to Settings → Sync & Privacy → Clear All Synced Data. This calls POST /api/sync/clear and permanently removes all server-side data. Your local localStorage data is not affected.
Settings are transmitted over HTTPS. Both settings sync and read history sync are enabled by default for signed-in users; you can turn either off individually in Settings → Sync & Privacy.

Build docs developers (and LLMs) love

Get started for freeTalk to us