API

API Reference

This document describes Questarr’s external software interfaces: the REST API exposed by the Express server, and the real-time events pushed over Socket.io. It complements docs/ARCHITECTURE.md (system actors and data flow) and docs/SECURITY_ASSESSMENT.md (risk assessment).

Update policy: re-run documentation generation for the affected route group whenever server/routes.ts changes; manually update the Steam/ PCGamingWiki sections when server/steam-routes.ts or server/pcgamingwiki-router.ts change.

Overview

• Base URL: all endpoints are served under /api on the same origin as the app (default http://localhost:5000).
• Format: JSON request/response bodies throughout, except file uploads (multipart/form-data for SSL certificate upload) and the download bundle endpoint (application/zip response).
• Authentication: a JWT bearer token obtained from POST /api/auth/login (or POST /api/auth/setup for the first account), sent as Authorization: Bearer <token> on subsequent requests. Verified by authenticateToken/optionalAuthenticateToken in server/auth.ts. A global gate — app.use("/api", authenticateToken) in server/routes.ts — requires a valid JWT for every route registered after it; a small set of routes registered earlier remain public (see the Authentication section below). The /api/integration subtree additionally accepts a long-lived integration API key (see the Integration API section); every other route, including key management, is JWT-only.
• Rate limiting: generalApiLimiter (600 req/min/IP) applies to all /api routes; authRateLimiter additionally guards login; sensitiveEndpointLimiter additionally guards write-heavy/sensitive endpoints; igdbRateLimiter additionally guards IGDB proxy endpoints. See server/middleware.ts.

Authentication

Method	Path	Auth Required	Request Body	Response
GET	/api/auth/status	None (public)	—	{ hasUsers: boolean }
POST	/api/auth/setup	None (public; blocked once a user exists)	{ username: string, password: string, igdbClientId?: string, igdbClientSecret?: string } — manual type-checking only, not express-validator/Zod	{ token, user: { id, username } }; 403 if setup already completed; 400 on invalid input
POST	/api/auth/login	authRateLimiter (20 req / 15 min)	{ username: string, password: string } — manual type-checking only, no express-validator/Zod schema	{ token, user: { id, username } }; 401 on invalid credentials
GET	/api/auth/me	authenticateToken (JWT)	—	{ id, username, steamId64 }
PATCH	/api/auth/password	authenticateToken + sensitiveEndpointLimiter	{ currentPassword: string, newPassword: string } — validated via Zod updatePasswordSchema	{ success: true, message }; 401 if current password wrong; 400 { error, details } on Zod failure

/api/auth/setup and /api/auth/login are the two security-sensitive endpoints that rely on inline typeof checks plus manual length/if validation instead of an express-validator chain or a Zod schema (see the risk register in docs/SECURITY_ASSESSMENT.md). /api/auth/password uses a proper Zod schema (updatePasswordSchema).

Routes registered before the global authenticateToken gate (server/routes.ts, before the auth-gate line) are public unless they explicitly list authenticateToken: /api/auth/*, /api/health, /api/settings/ssl (GET/PATCH), /api/settings/ssl/generate, /api/settings/ssl/upload, /api/system/filesystem, /api/config. Everything registered after that line — including /api/ready and every resource group below — requires a JWT even where a table row doesn’t repeat authenticateToken.

Games

Method	Path	Auth Required	Request Body	Response
GET	/api/games	JWT (global gate)	Query: search?, includeHidden?, status? (comma-separated or array)	Game[]
GET	/api/games/status/:status	JWT	Query: includeHidden?	Game[]
GET	/api/games/search	JWT + sanitizeSearchQuery, validateRequest	Query: q (1–200 chars, required), search? (≤200), limit? (1–100)	Game[]; 400 if q missing
POST	/api/games	JWT + sensitiveEndpointLimiter, sanitizeGameData, validateRequest	{ title (1–500), igdbId?, summary? (≤5000), coverUrl? (URL), releaseDate? (YYYY-MM-DD), rating? (0–10), platforms?, genres?, publishers?, developers? }, re-parsed via insertGameSchema (Zod)	201 Game; 409 { error, game } if duplicate; 400 { error, details } on Zod failure
PATCH	/api/games/:id/status	JWT + sensitiveEndpointLimiter, sanitizeGameId, sanitizeGameStatus, validateRequest	{ status: "wanted"|"owned"|"completed"|"downloading" } via updateGameStatusSchema	Updated Game; 404 if not found
PATCH	/api/games/:id/hidden	JWT + sensitiveEndpointLimiter, sanitizeGameId, validateRequest	{ hidden: boolean } via updateGameHiddenSchema	Updated Game; 404 if not found
PATCH	/api/games/:id/user-rating	JWT + sensitiveEndpointLimiter, sanitizeGameId, validateRequest	{ userRating: number|null } (0.5–10, step 0.5) via updateGameUserRatingSchema	Updated Game; 404 if not found
PATCH	/api/games/:id/installed-version	JWT + sensitiveEndpointLimiter, sanitizeGameId, validateRequest	{ installedVersion: string|null } (free text, trimmed, ≤64; blank clears) via updateGameInstalledVersionSchema	Updated Game; 404 if not found. Auto-search skips update releases whose version is not newer than this
POST	/api/games/refresh-metadata	JWT + igdbRateLimiter	—	{ success, message, updatedCount, errorCount }
DELETE	/api/games/:id	JWT + sensitiveEndpointLimiter, sanitizeGameId, validateRequest	Query: deleteFiles? (“true” to also remove the game’s files on disk)	{ success: true, fileDeletion }; 404 if not found. fileDeletion is null when deleteFiles wasn’t set, otherwise { deleted: true, path } or { deleted: false, reason: "outside-library-root"|"delete-failed", path }. Files are only deleted when libraryPath resolves inside the configured library root or inside a root folder with allowDelete: true (see Root Folders below)
GET	/api/games/:id/downloads	JWT + sanitizeGameId, validateRequest (verifies game ownership)	—	GameDownload[]; 404 game not found, 403 not owner
GET	/api/games/discover	JWT + igdbRateLimiter	Query: limit?	Game[] (IGDB-formatted recommendations)
POST	/api/games/match-and-add	JWT	{ title: string } — manual typeof check, no validator	201 Game; 404 if no IGDB match; 409 if already in collection
POST	/api/games/:gameId/blacklist	JWT (explicit)	{ releaseTitle: string (required, ≤500) } via insertReleaseBlacklistSchema.safeParse	201 blacklist entry; 400 invalid; 403/404 via ownership check
GET	/api/games/:gameId/blacklist	JWT (explicit)	—	Blacklist entries array; 403/404 via ownership check
GET	/api/games/:gameId/files	JWT (explicit) + scanRateLimiter (10 req / min per user)	—	{ files: { name, path, category, size }[], truncated: boolean } — recursive scan of the game’s library folder, bounded by SCAN_MAX_FILES (5,000) and a 5s wall-clock budget; truncated: true when either cap stopped the walk. Empty { files: [], truncated: false } for missing/escaped paths; 403/404 via ownership check; 500 on unexpected I/O errors
PATCH	/api/games/:gameId/files/category	JWT (explicit)	Body: { path: string, category: "main" | "dlc" | "update" | "extra" }	{ path, category } — stores a user-chosen category for a file inside the game’s folder (realpath must stay within the game folder and library root, else 404); sets game_files.category_overridden so later scans of /files report it instead of the folder/filename guess. 400 on invalid category; 403/404 via ownership check
DELETE	/api/games/:gameId/blacklist/:id	JWT (explicit)	—	204; 404 if entry not found
DELETE	/api/games/:id/downloads/:downloadId	JWT + sanitizeGameId, sanitizeDownloadId, validateRequest	—	{ success: true }; 404 if game/download not found

Downloads

Method	Path	Auth Required	Request Body	Response
GET	/api/downloads	JWT (global gate)	—	{ downloads: (Download & { downloaderId, downloaderName, trackedByQuestarr, downloaderCategory })[], errors: {...}[] }
GET	/api/downloads/summary	JWT (explicit)	—	Per-game download summary object
GET	/api/downloads/scan	JWT (explicit)	—	{ groups: { baseTitle, downloads[], libraryMatch: {game, confidence}|null }[] } — untracked downloads grouped/matched to library
POST	/api/downloads/claim	JWT (explicit)	{ downloaderId, downloadHash, downloadTitle, currentStatus, category, gameId? or newGame? } via claimDownloadRequestSchema.safeParse	{ success: true, gameId }; 409 if already linked; 400/404 on invalid input
POST	/api/downloads	JWT + sensitiveEndpointLimiter, sanitizeDownloaderDownloadData, validateRequest	{ url (http/https/magnet), title (1–500), category?, downloadPath? (no ".."), priority? (0–10), gameId? (uuid), downloadType?, password? (≤200 chars) }	Add-with-fallback result across enabled downloaders; 400 if none configured; 500 on total failure
POST	/api/downloads/bundle	JWT + sensitiveEndpointLimiter	{ downloads: { link, title, downloadType? }[] } — manual array check only	Streams a .zip of fetched torrent/nzb files

Downloaders

Method	Path	Auth Required	Request Body	Response
GET	/api/downloaders	JWT	—	Downloader[] (passwords masked as ********)
GET	/api/downloaders/enabled	JWT	—	Downloader[] (masked)
GET	/api/downloaders/storage	JWT	—	{ downloaderId, downloaderName, freeSpace, error? }[], cached 30s server-side
GET	/api/downloaders/:id	JWT	—	Downloader (masked); 404 if not found
POST	/api/downloaders	JWT + sensitiveEndpointLimiter, sanitizeDownloaderData, validateRequest	{ name (1–200), type (transmission|rtorrent|qbittorrent|sabnzbd|nzbget), url (full URL or bare hostname/IP), username?, password?, enabled?, downloadPath? (no ".."), label?, urlPath? } via insertDownloaderSchema; SSRF-checked via isSafeUrl	201 Downloader (masked); 400 invalid/unsafe URL
PATCH	/api/downloaders/:id	JWT + sensitiveEndpointLimiter, sanitizeDownloaderUpdateData, validateRequest	Partial of above plus priority?, category?; password equal to the redacted placeholder = keep unchanged	Updated Downloader (masked); 404 if not found
DELETE	/api/downloaders/:id	JWT + sensitiveEndpointLimiter	—	204; 404 if not found
POST	/api/downloaders/test	JWT	{ type, url, port?, useSsl?, urlPath?, username?, password?, downloadPath?, category?, label?, ... } — manual checks, SSRF-checked	Connection test result object
POST	/api/downloaders/:id/test	JWT	—	Connection test result for saved downloader; 404 if not found
POST	/api/downloaders/:id/downloads	JWT + sensitiveEndpointLimiter, sanitizeDownloaderDownloadData, validateRequest	{ url, title, category?, downloadPath?, priority?, downloadType?, password? (≤200 chars) }	Add-download result; 404 downloader not found; 400 if downloader disabled
GET	/api/downloaders/:id/downloads	JWT	—	Downloads array from that client; 404 if downloader not found
GET	/api/downloaders/:id/downloads/:downloadId	JWT	—	Single download status object; 404 if not found
GET	/api/downloaders/:id/downloads/:downloadId/details	JWT	—	Detailed info (files, trackers); 404 if not found
POST	/api/downloaders/:id/downloads/:downloadId/pause	JWT	—	Pause result object
POST	/api/downloaders/:id/downloads/:downloadId/resume	JWT	—	Resume result object
DELETE	/api/downloaders/:id/downloads/:downloadId	JWT	Query: deleteFiles?	Removal result object

Root Folders / Library Scan

Extra directories scanned (read-only discovery) for games already on disk outside the configured library root (e.g. an older library, a secondary drive). Separate from the library root used by the download-import pipeline — matched games get a libraryPath outside that root. Discovery itself never moves, renames, or deletes files there; the game-delete flow (DELETE /api/games/:id?deleteFiles=true) only touches files under a root folder when that folder’s allowDelete is explicitly turned on (off by default).

Method	Path	Auth Required	Request Body	Response
GET	/api/root-folders	JWT	—	RootFolder[]
POST	/api/root-folders	JWT + sensitiveEndpointLimiter, sanitizeRootFolderData, validateRequest	{ path (1–1000, no null bytes), name? (≤200), enabled?, allowDelete? } via insertRootFolderSchema; path probed on disk. allowDelete defaults to false	201 RootFolder; 400 if path inaccessible; 409 if path already registered
PATCH	/api/root-folders/:id	JWT + sensitiveEndpointLimiter, sanitizeRootFolderId, sanitizeRootFolderUpdateData, validateRequest	Partial: path?, name?, enabled?, allowDelete?	Updated RootFolder; 400 if :id isn’t a UUID; 404 if not found; 409 if new path already registered
DELETE	/api/root-folders/:id	JWT + sensitiveEndpointLimiter, sanitizeRootFolderId, validateRequest	—	204; 400 if :id isn’t a UUID; 404 if not found
POST	/api/root-folders/:id/health-check	JWT + sensitiveEndpointLimiter, sanitizeRootFolderId, validateRequest	—	Force-refreshed accessibility + disk stats for the folder; 400 if :id isn’t a UUID; 404 if not found
POST	/api/library/scan	JWT + sensitiveEndpointLimiter, sanitizeLibraryScanData, validateRequest	{ rootFolderId? } via sanitizeLibraryScanData — optional, 1–200 chars if given; omit to scan all enabled root folders	202 { accepted: true, rootFolderId }; scan runs asynchronously; 400 { error: "Validation failed", details } on invalid body
GET	/api/library/scan/status	JWT	—	ScanProgress[] — one entry per root folder scanned since server start
GET	/api/library/scan/unmatched	JWT	—	UnmatchedEntry[] — folders that didn’t confidently match an IGDB game
POST	/api/library/scan/unmatched/match	JWT + sensitiveEndpointLimiter, sanitizeUnmatchedMatchData, validateRequest	{ rootFolderId (1–200 chars), folderName (1–1000 chars), igdbId (positive integer) } via sanitizeUnmatchedMatchData	{ gameId, filesAdded }; 400 { error: "Validation failed", details } on invalid body; 500 with message on resolution failure

Indexers

Method	Path	Auth Required	Request Body	Response
GET	/api/indexers	JWT	—	Indexer[] (apiKey masked)
GET	/api/indexers/enabled	JWT	—	Indexer[] (masked)
GET	/api/indexers/search	JWT (registered after the global auth gate, so optionalAuthenticateToken never actually sees an unauthenticated request) + sanitizeIndexerSearchQuery, validateRequest	Query: query (1–200, required), category?/cat? (≤500), limit? (1–100), offset? (≥0), gameId?	{ items, total, offset, blacklistedCount?, errors? }
GET	/api/indexers/:id	JWT	—	Indexer (masked); 404 if not found
POST	/api/indexers	JWT + sensitiveEndpointLimiter, sanitizeIndexerData, validateRequest	{ name (1–200), url (http/https, SSRF-checked), apiKey? (≤500), protocol? (torznab|newznab), enabled? } via insertIndexerSchema	201 Indexer (masked); 400 invalid/unsafe URL
PATCH	/api/indexers/:id	JWT + sensitiveEndpointLimiter, sanitizeIndexerUpdateData, validateRequest	Partial: name?, url?, apiKey?, protocol?, enabled?, priority? (≥1), categories?, rssEnabled?, autoSearchEnabled?; apiKey placeholder = keep unchanged	Updated Indexer (masked); 404 if not found
DELETE	/api/indexers/:id	JWT + sensitiveEndpointLimiter	—	204; 404 if not found
POST	/api/indexers/test	JWT	{ name?, url (required, SSRF-checked), apiKey (required), enabled?, priority?, categories?, rssEnabled?, autoSearchEnabled? } — manual checks only	Torznab connection test result
POST	/api/indexers/:id/test	JWT	—	Connection test result for saved indexer; 404 if not found
GET	/api/indexers/:id/categories	JWT	—	Category list from indexer; 404 if not found
GET	/api/indexers/:id/search	JWT	Query: query (required), category?/cat?, limit? (default 50), offset? (default 0)	Search results from that single indexer; 400 if query missing, 404 if not found
POST	/api/indexers/prowlarr/sync	JWT + sensitiveEndpointLimiter	{ url: string, apiKey: string } — manual checks, SSRF-checked	{ success, message, results }
GET	/api/search	JWT (same global-gate note as above; alias of /api/indexers/search) + sanitizeIndexerSearchQuery, validateRequest	Same as /api/indexers/search	Same as /api/indexers/search

IGDB

Method	Path	Auth Required	Request Body	Response
GET	/api/igdb/search	JWT + igdbRateLimiter, sanitizeSearchQuery, validateRequest	Query: q (1–200, required), limit? (1–100)	Formatted IGDB game array
GET	/api/igdb/popular	JWT + igdbRateLimiter	Query: limit?	Formatted game array; Cache-Control: public, max-age=3600, stale-while-revalidate=600
GET	/api/igdb/recent	JWT + igdbRateLimiter	Query: limit?	Formatted game array; same cache header
GET	/api/igdb/upcoming	JWT + igdbRateLimiter	Query: limit?	Formatted game array; same cache header
GET	/api/igdb/genre/:genre	JWT + igdbRateLimiter	Path :genre (≤100 chars); query limit?, offset?	Formatted game array; same cache header
GET	/api/igdb/platform/:platform	JWT + igdbRateLimiter	Path :platform (≤100 chars); query limit?, offset?	Formatted game array; same cache header
GET	/api/igdb/genres	JWT + igdbRateLimiter	—	Genre list; Cache-Control: public, max-age=86400, stale-while-revalidate=3600
GET	/api/igdb/platforms	JWT + igdbRateLimiter	—	Platform list; same 24h cache header
GET	/api/igdb/game/:id	JWT + igdbRateLimiter, sanitizeIgdbId, validateRequest	Path :id (positive integer)	Formatted IGDB game; 404 if not found

Settings

Method	Path	Auth Required	Request Body	Response
GET	/api/settings/ssl	authenticateToken (pre-gate)	—	SSL config plus optional certInfo (subject, issuer, validity, selfSigned)
PATCH	/api/settings/ssl	authenticateToken + sensitiveEndpointLimiter (pre-gate)	{ enabled: boolean, port: number, certPath?, keyPath?, redirectHttp? } — manual checks; cert/key paths path-traversal checked against FILE_BROWSER_ROOT	{ success, message }; 400/403 on invalid config or disallowed path
POST	/api/settings/ssl/generate	authenticateToken + sensitiveEndpointLimiter (pre-gate)	—	{ success, message, certPath, keyPath } (self-signed cert)
POST	/api/settings/ssl/upload	authenticateToken + sensitiveEndpointLimiter (pre-gate)	Multipart form: cert file + key file (5 MB limit, memory storage); validated as PEM	{ success, message, certPath, keyPath }; 400 if missing/invalid PEM
GET	/api/system/filesystem	authenticateToken + sensitiveEndpointLimiter (pre-gate)	Query: path? (relative; absolute paths/NUL bytes rejected; confined to FILE_BROWSER_ROOT)	{ path, parent, files: {name, path, isDirectory, size}[] }; 403 on traversal, 404 if missing
GET	/api/config	sensitiveEndpointLimiter only, no JWT (pre-gate, public)	—	{ igdb: { configured, source }, xrel: { apiBase } }
GET	/api/settings/igdb	JWT + sensitiveEndpointLimiter	—	{ configured, source, clientId }
POST	/api/settings/igdb	JWT + sensitiveEndpointLimiter	{ clientId: string (required), clientSecret?: string } — manual checks; redacted-placeholder secret = keep existing	{ success: true }; 400 if client secret required but missing
GET	/api/settings/discord	JWT + sensitiveEndpointLimiter	—	{ configured: boolean, webhookUrl?: "********" }
POST	/api/settings/discord	JWT + sensitiveEndpointLimiter	{ webhookUrl?: string } — must be a discord.com/discordapp.com webhook URL; redacted placeholder = keep unchanged	{ success: true }; 400 on invalid webhook URL
GET	/api/settings	JWT	—	UserSettings (created with defaults if none exist)
PATCH	/api/settings	JWT	Validated via updateUserSettingsSchema (Zod)	Updated UserSettings; 400 { error, details } on Zod failure
PATCH	/api/settings/xrel	JWT	{ apiBase?: string (http/https, SSRF-checked, must match ALLOWED_XREL_DOMAINS), xrelSceneReleases?: boolean, xrelP2pReleases?: boolean } — manual checks	{ success, xrel: { apiBase }, settings? }; 400 on invalid/unsafe/unauthorized domain
GET	/api/settings/nexusmods	JWT + sensitiveEndpointLimiter	—	{ configured: boolean, source?: "env"|"database" }
POST	/api/settings/nexusmods	JWT + sensitiveEndpointLimiter	{ apiKey: string (required) }	{ success: true }; 400 if missing

RSS

Method	Path	Auth Required	Request Body	Response
GET	/api/rss/feeds	JWT	—	RssFeed[]
POST	/api/rss/feeds	JWT	Validated via insertRssFeedSchema (Zod); URL SSRF-checked	201 RssFeed; 400 on Zod/unsafe-URL failure (triggers async initial refresh)
PUT	/api/rss/feeds/:id	JWT	Partial insertRssFeedSchema	Updated RssFeed; 404 if not found; 400 if unsafe URL
DELETE	/api/rss/feeds/:id	JWT	—	204; 404 if not found
GET	/api/rss/items	JWT	Query: limit? (default 100)	RssFeedItem[]
POST	/api/rss/refresh	JWT	—	{ success: true } (triggers refresh of all feeds)

Notifications

Method	Path	Auth Required	Request Body	Response
GET	/api/notifications	JWT (explicit)	Query: limit? (default 50)	Notification[]
GET	/api/notifications/unread-count	JWT (explicit)	—	{ count: number }
POST	/api/notifications	JWT (explicit)	Validated via insertNotificationSchema (Zod)	201 Notification (also emitted over Socket.io); 400 on Zod failure
PUT	/api/notifications/:id/read	JWT (explicit)	—	Updated Notification; 404 if not found
PUT	/api/notifications/read-all	JWT (explicit)	—	{ success: true }
DELETE	/api/notifications	JWT (explicit)	—	204 (clears all read notifications)

Error Telemetry

Backs the consent flow opened from an “error-detected” notification’s link (error-report:<reportId>). Reports are built server-side from recent, PII-scrubbed server.log lines when an unhandled server error is detected (uncaught exception, unhandled rejection, or a 5xx response); see server/error-telemetry.ts. Pending reports are held in memory only (not persisted), scoped to the user they were created for, and expire after 24h.

Method	Path	Auth Required	Request Body	Response
GET	/api/telemetry/pending/:reportId	JWT (explicit)	—	{ lineCount, appVersion, platform, timestamp }; 404 if expired/unknown/not owned by the caller
POST	/api/telemetry/pending/:reportId/send	JWT (explicit)	—	{ code, issueNumber } (same shape as the manual “Send Logs” flow); 422 if unavailable (unknown/expired/not owned) or delivery fails

reportId must be a UUID (validated via express-validator). For GET, a report owned by another user is indistinguishable from an unknown/expired one — both return 404 — so a caller can’t probe for the existence of another user’s report. POST folds the same “not available” cases (unknown, expired, or not owned) into the 422 it already uses for delivery failures, since sendPendingReport doesn’t distinguish them from the caller’s perspective.

Whether an error triggers a notification at all is controlled by the errorDetected notification preference; whether it’s reported automatically (skipping the consent step above) is controlled by the per-user telemetryEnabled setting (Settings > System > Telemetry, off by default).

xREL

Method	Path	Auth Required	Request Body	Response
GET	/api/xrel/latest	JWT	Query: page? (default 1)	{ ...xrelResult, list: [...releases annotated with libraryStatus, gameId, isWanted, matchCandidate?] }
GET	/api/xrel/search	JWT	Query: q (required), scene? (default true unless “false”/“0”), p2p?, limit? (1–100, default 25)	{ results: [...] }; 400 if q missing

PATCH /api/settings/xrel (xREL API base URL and scene/P2P release preferences) is documented under Settings.

NexusMods

Method	Path	Auth Required	Request Body	Response
GET	/api/nexusmods/game-domain	JWT	Query: title (required)	{ configured: boolean, domain: string|null }; 400 if title missing
GET	/api/nexusmods/trending-mods	JWT	Query: domain (required), limit? (1–20, default 10)	Trending mods array; 400 if domain missing

NexusMods API-key configuration (GET/POST /api/settings/nexusmods) is documented under Settings.

Stats

Method	Path	Auth Required	Request Body	Response
POST	/api/stats/discord-share	JWT	{ image: string (data URI, png/jpeg/gif/webp base64), message?: string } — manual checks; webhook URL must match Discord’s domain pattern	{ success: true }; 400 on missing/invalid config or image; 502 if Discord request fails

Health / Ready / Config

Method	Path	Auth Required	Request Body	Response
GET	/api/health	None (public, pre-gate)	—	{ status: "ok" } (liveness probe only, no dependency checks)
GET	/api/ready	JWT (registered after the global auth gate, so a token is required despite being a readiness probe)	—	{ status: "ok" } (200) if DB + IGDB checks succeed, else { status: "error" } (503)
GET	/api/config	sensitiveEndpointLimiter only, no JWT (public, pre-gate)	—	{ igdb: { configured, source }, xrel: { apiBase } }

Dashboard Status

Method	Path	Auth Required	Request Body	Response
GET	/api/status	JWT	—	{ totalGames, pendingWishlist, activeDownloads, recentImports: { count, items: [{ gameId, title, completedAt }] } } — lightweight stats for external dashboard widgets (Homepage, Homarr, Organizr, etc.), excludes hidden games; response sent with Cache-Control: no-store. pendingWishlist counts games with status wanted; activeDownloads counts downloads with status downloading/paused; recentImports is scoped to downloads completed in the last 7 days — count is the total in that window, items are the same window’s 5 most recent (never older imports, even when fewer than 5 exist).

HowLongToBeat

Method	Path	Auth Required	Request Body	Response
GET	/api/hltb/lookup	JWT (explicit)	Query: title (required)	{ data: HltbResult | null }; 400 if title missing

Blacklist

Method	Path	Auth Required	Request Body	Response
GET	/api/blacklist	JWT (explicit)	—	All blacklist entries across the user’s games (ReleaseBlacklist[])

Per-game blacklist management (POST/GET/DELETE /api/games/:gameId/blacklist*) is documented under Games.

Steam

server/steam-routes.ts — 2 routes, mounted directly on the app (no prefix router), both behind the global auth gate plus explicit authenticateToken.

Method	Path	Auth Required	Request Body	Response
PATCH	/api/user/steam-id	JWT	{ steamId: string } — must be a 17-digit SteamID64 starting with 7656 (steamService.validateSteamId)	{ success: true, steamId }; 400 if missing/invalid format
POST	/api/steam/wishlist/sync	JWT	—	{ success, addedCount, games } (via syncUserSteamWishlist); 400 if Steam ID not linked or sync fails

PCGamingWiki

server/pcgamingwiki-router.ts — 1 route.

Method	Path	Auth Required	Request Body	Response
GET	/api/external/pcgamingwiki	JWT	Query: steamAppId (required, positive integer)	{ url: string | null }; 400 if steamAppId missing/invalid; result cached 24h (5min on lookup failure)

Integration API (external clients)

server/routes/integration.ts — 4 routes, mounted at /api/integration.

This is the one part of the API that accepts a long-lived integration API key in addition to a JWT, for machine clients that cannot run the interactive login flow — the Playnite extension, scripts, other self-hosted tools. The key is presented as X-Api-Key: <key> or Authorization: Bearer <key> (keys are recognised by their qsr_ prefix, so a Bearer header is unambiguous between a key and a JWT).

Authentication is handled by authenticateApiKeyOrToken in server/auth.ts, selected by requireAuthenticationForApi for paths under /integration only. Everywhere else on /api — key management included — stays JWT-only, so a leaked key cannot escalate into minting or revoking other keys.

Method	Path	Auth Required	Request Body	Response
GET	/api/integration/ping	JWT or API key	—	{ service: "questarr", version, apiVersion, authenticatedAs: { id, username }, usingApiKey }
GET	/api/integration/library	JWT or API key	Query: status (optional, comma-separated), includeHidden (optional, "true"/"false")	{ games: IntegrationGame[], count }; 400 on invalid query
POST	/api/integration/library/sync	JWT or API key	{ games: Array<{ title, externalId?, installed?, steamAppId? }> (1–5000), markInstalledAsOwned?: boolean } — Zod-validated	{ received, matched, unmatched, promotedToOwned }; 400 on invalid payload
POST	/api/integration/games/request	JWT or API key	{ title: string, status?: "wanted" | "owned" } — Zod-validated	201 { game }; 404 if IGDB has no match or the match is content-filtered; 409 if already in library

IntegrationGame is a deliberately narrow projection of a library game — id, title, igdbId, steamAppId, status, releaseStatus, releaseDate, coverUrl, platforms, genres, libraryPath, addedAt. Internal fields (userId, notes, search-result bookkeeping) are never exposed.

apiVersion (INTEGRATION_API_VERSION) describes the integration contract itself and is bumped only when a change would break an already-released client, so an extension can fail loudly on a mismatch instead of misbehaving mid-sync.

Sync matching: an incoming entry is matched against the caller’s library by Steam App ID first, then by normalized title (normalizeTitle from shared/title-utils.ts). Unmatched entries are reported back rather than added — a sync never creates library entries on its own. markInstalledAsOwned promotes a matched game from wanted to owned only when the client reports it installed, and is off by default.

Requesting a game: a requested game is added with status wanted, which is what hands it to the existing auto-search pipeline (checkAutoSearch in server/cron.ts) — that is how a request from the couch turns into a download.

API Keys (management)

server/routes/api-keys.ts — 3 routes, mounted at /api/api-keys, JWT only.

Keys are stored as a SHA-256 hash plus a short display prefix; the raw key is returned exactly once, in the 201 response that creates it, and is not recoverable afterwards. A user may hold at most 25 keys.

Method	Path	Auth Required	Request Body	Response
GET	/api/api-keys	JWT	—	Array<{ id, userId, name, prefix, createdAt, lastUsedAt }> — never includes the hash
POST	/api/api-keys	JWT + sensitiveEndpointLimiter	{ name: string } (1–100 chars)	201 { id, userId, name, prefix, createdAt, lastUsedAt, key } — key is shown only here; 409 once 25 keys exist
DELETE	/api/api-keys/:id	JWT + sensitiveEndpointLimiter	—	204; 404 if the key does not exist or belongs to another user

Error Format

Across handlers, error responses follow one of these consistent shapes:

• Validation failures (express-validator chains): the shared validateRequest middleware (server/middleware.ts) runs after any sanitize* validator array. On failure it returns HTTP 400 with:
  {
    "error": "Validation failed",
    "details": [/* express-validator error objects: { type, msg, path, location, value } */]
  }
  
• Validation failures (Zod schemas): handlers that call someSchema.parse(req.body) catch z.ZodError directly and return HTTP 400 with:
  {
    "error": "Invalid <thing> data",
    "details": [/* ZodError.errors array */]
  }
  
  (message text varies per handler, e.g. “Invalid game data”, “Invalid status data”, “Invalid settings data”)
• Ad hoc business-logic errors: most handlers return a plain { "error": "<message>" } object directly for 400/401/403/404/409/502 cases (sometimes with an extra field attached, e.g. { error, game } on a duplicate-game 409), without going through shared middleware.
• Uncaught/rethrown errors (global handler): routes that call next(error) fall through to errorHandler (server/middleware.ts), which returns:
  {
    "error": "<message, or 'Internal Server Error' in production for 5xx>",
    "details": "<only if err.details was set>"
  }
  
  Status comes from err.status/err.statusCode, defaulting to 500. In production, 5xx messages are sanitized to "Internal Server Error" to avoid leaking internals; 4xx messages pass through as-is. All errors are logged via Pino with method/path context — error level for 5xx, warn otherwise.
• No-content success: several DELETE endpoints return 204 No Content with an empty body rather than a JSON payload (e.g. DELETE /api/games/:id, DELETE /api/indexers/:id, DELETE /api/downloaders/:id, DELETE /api/rss/feeds/:id, DELETE /api/notifications).

Real-time interface (Socket.io)

Alongside the REST API, the server pushes real-time events over Socket.io (server/socket.ts). See docs/ARCHITECTURE.md §6 for the full actor/data-flow explanation. Summary:

Event	Emitted from	Payload	Consumed by
notification	cron.ts (game updates, download completion, auto-search results, xREL matches) and routes.ts	Notification object	client/src/components/NotificationCenter.tsx
downloadUpdate	cron.ts::checkDownloadStatus	gameId: string	client/src/components/GameDetailsModal.tsx

Both events are broadcast to every connected socket (io.emit) — there are no per-user rooms yet.