# 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`](ARCHITECTURE.md) (system actors and data flow) and [`docs/SECURITY_ASSESSMENT.md`](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 ` on subsequent requests. Verified by `authenticateToken`/`optionalAuthenticateToken` in `server/auth.ts`. The whole `/api` surface is default-deny: `requireAuthenticationForApi` (`server/routes.ts`) is mounted before any route and requires a valid JWT unless the request is in the `PUBLIC_API_ROUTES` allowlist or is the soft-auth `POST /api/auth/logout` (see the Authentication section below). The `/api/integration` subtree additionally accepts a long-lived integration API key (see the Integration API section), and keys with the `admin` scope can call a fixed allowlist of configuration routes; 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`). Every `/api` route requires a JWT unless it is listed in `PUBLIC_API_ROUTES` in `server/routes.ts`, is the soft-auth `POST /api/auth/logout` described below, or is one of the API-key exceptions at the end of this section. A route added without updating that list is protected by default, even when its handler does not call `authenticateToken` itself or a table row does not repeat it. The public routes are: - `GET /api/auth/status`, `POST /api/auth/setup`, `POST /api/auth/setup/test-igdb` and `POST /api/auth/login`: used before a token exists (setup wizard and login page). - `GET /api/health`: liveness probe. - `GET /api/ready`: readiness probe, with no sensitive data. `POST /api/auth/logout` is a "soft" route: it accepts a missing or expired token so a user with a stale cookie can still clear it, but a valid token is still read so CSRF protection applies. Everything else, including `/api/config`, `/api/system/filesystem`, `/api/settings/ssl` and every resource group below, requires a JWT. The only exceptions are the `/api/integration` routes, which also accept an integration API key, and the `admin`-scope allowlist of configuration routes (see [Configuration API for automation](#configuration-api-for-automation-admin-scope)). ## 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 | | GET | `/api/games/:id` | JWT + `sanitizeGameId`, `validateRequest` | — | Game object. 404 if the game does not exist or is in a hidden content category; 403 if it belongs to another user. Registered after `/api/games/discover`, so that literal path is never read as an id. | | 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 | ## Collections User-defined groups of games. A `manual` collection holds an explicit list of games; a `smart` collection stores `rules` and its games are computed from the user's library on every read. Hidden games and games excluded by the user's content-filter settings are never included. All routes require JWT and only see the requester's own collections (404 otherwise). | Method | Path | Request Body | Response | | ------ | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | GET | `/api/collections` | — | `Collection[]`, each with `gameCount` and `coverUrls` (up to 4) | | POST | `/api/collections` | `{ name (1–100), description? (≤500), type: "manual"\|"smart", rules? }`. `rules` (smart only, at least one non-empty criterion — empty lists alone are rejected —, unknown keys rejected, `releaseYearTo` must not be earlier than `releaseYearFrom`): `{ statuses?, platforms?, genres?, minRating? (0–10), minUserRating? (0–10), releaseYearFrom?, releaseYearTo?, titleContains? }` | 201 `Collection`; 400 `{ error, details }` (e.g. smart without rules). Rules are dropped for manual type | | GET | `/api/collections/:collectionId` | — | `Collection & { games: Game[] }`; 404 if not found | | PATCH | `/api/collections/:collectionId` | Any of `name`, `description`, `type`, `rules` | Updated `Collection`; 400 if the result would be a smart collection without rules; switching to manual clears rules | | DELETE | `/api/collections/:collectionId` | — | 204; 404 if not found. Games stay in the library | | POST | `/api/collections/:collectionId/games` | `{ gameId }` | 201 `{ collectionId, gameId }`; 400 on a smart collection; 404 if the game is not the user's; 409 if already added | | DELETE | `/api/collections/:collectionId/games/:gameId` | — | 204; 404 if the game is not in the collection | ## 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?, allowInsecureLan?, ... }` — 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). The UI is **Library → Library Import**. Adding/enabling a folder or changing an enabled folder's path starts an asynchronous scan. Enabling post-processing also scans enabled roots. Settings changes during an active scan queue a rescan. `ScanProgress` includes `startedAt`, optional `finishedAt`, status, candidate counts and match/review/error counts; updates also arrive as `library-scan-progress`. See [LIBRARY_IMPORT.md](LIBRARY_IMPORT.md) for the operator workflow. `POST /api/library/scan/unmatched/ignore` skips a Needs Review folder for good. Body: `{ rootFolderId, folderName }` (`folderName` is not trimmed and must match the scanned folder exactly). Returns `{ success: true }`, 400 for invalid input, 404 when the folder is no longer awaiting review. Later scans skip an ignored folder before listing its files, unless it is already linked to a game. `GET /api/library/scan/ignored` lists the ignored folders, and `DELETE /api/library/scan/ignored/:id` restores one (404 when unknown) and queues a rescan of its root folder so it returns to Needs Review. `POST /api/library/scan/unmatched/search` requires authentication, CSRF for cookie sessions, and the IGDB rate limiter. Body: `{ rootFolderId, folderName, query }` (trimmed strings, limits 200/1000/200 respectively). Returns an array of `{ igdbId, name, releaseYear }` candidates; searching does not import a game. Returns 400 for invalid input, 404 when the folder is no longer awaiting review, or 500 if IGDB search fails. Confirm a candidate using the match endpoint below. | 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 | ## Import Settings Mounted under `/api/imports` (JWT). See [LIBRARY_IMPORT.md](LIBRARY_IMPORT.md#naming-pattern) for naming tokens and rendering rules. | Method | Path | Auth Required | Request Body | Response | | ------ | ----------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | POST | `/api/imports/naming/preview` | JWT | `{ pattern: string (1–200) }` (strict, no other fields) | `{ samples: { title, leafName, fullPath }[] }` for up to 5 library games plus one sample release; nothing is renamed. 400 `{ error, errors: string[] }` if the pattern is invalid; 400 `{ error }` on bad body | | PATCH | `/api/imports/config` | JWT | Partial import config. `renamePattern?` (1–200) must pass naming validation: known tokens only, no `/` or `\`, no `..`, no control characters, balanced braces | Updated import config; 400 `{ error }` listing the validation messages on an invalid `renamePattern` or body | Example preview request: ```bash curl -X POST http://localhost:5000/api/imports/naming/preview \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"pattern":"{Title} ({Year})"}' ``` ## RomM Settings Mounted under `/api/settings/romm` (JWT). See [LIBRARY_IMPORT.md](LIBRARY_IMPORT.md#romm-integration) for what each setting does. | Method | Path | Auth Required | Request Body | Response | | ------ | ---------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/settings/romm` | JWT | — | `{ enabled, url, apiToken, platformFolders, syncEnabled, scanAfterImport, lastSync }`; `apiToken` is `"********"` when set | | POST | `/api/settings/romm` | JWT | Partial `{ enabled?, url? (http/https or empty), apiToken? (≤512), platformFolders?, syncEnabled?, scanAfterImport? }` (strict). A `"********"` token keeps the saved one; an empty token clears it | `{ success: true }`; 400 if a saved token exists and the URL changes without a new token | | POST | `/api/settings/romm/test` | JWT + `sensitiveEndpointLimiter` | `{ url?, apiToken? }` (strict). Never saved. An omitted, empty or `"********"` token tests with the saved token (sent only to the saved URL), so a blank token cannot be used to test without credentials | `{ success: true, platforms }`; 400 if the URL differs from the saved one without a token; 502 if RomM is unreachable | | POST | `/api/settings/romm/sync` | JWT + `sensitiveEndpointLimiter` | — | `{ success: true, summary }` (`totalRoms` fetched from RomM, matched, marked owned, already owned, not in library); 502 if the sync fails | | GET | `/api/settings/romm/folder-repair` | JWT | — | `{ proposals: [{ gameId, title, from, to, currentFolder, expectedFolder, destinationExists }] }`: games stored in a RomM platform folder none of their platforms belongs to; 409 if RomM platform folders are off | | POST | `/api/settings/romm/folder-repair` | JWT + `sensitiveEndpointLimiter` | `{ gameIds: string[] }` (1-500, strict). Paths are recomputed server-side; an existing destination is never overwritten | `{ results: [{ gameId, title, moved, to?, error? }] }`; a successful move updates the game path and files and asks RomM to rescan | ## 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?, allowInsecureLan? }` — 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 | | GET | `/api/indexers/prowlarr/settings` | JWT | — | Last successful sync values `{ url, apiKey: "********", allowInsecureLan, priority, categories }`, or `null` | | POST | `/api/indexers/prowlarr/sync` | JWT + `sensitiveEndpointLimiter` | `{ url: string, apiKey: string, allowInsecureLan?: boolean, priority?: 1–100, categories?: string[] }` — optional fields apply to every synced indexer; `apiKey: "********"` reuses the saved key for the saved URL only; values are remembered after a successful sync; 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`, plus `title?` (≤200): the title `query` is a simpler variant of, so later pages keep scoring against it | Same as `/api/indexers/search`, plus `queryUsed?` | ## 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` | — | SSL config plus optional `certInfo` (subject, issuer, validity, selfSigned) | | PATCH | `/api/settings/ssl` | `authenticateToken` + `sensitiveEndpointLimiter` | `{ 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` | — | `{ success, message, certPath, keyPath }` (self-signed cert) | | POST | `/api/settings/ssl/upload` | `authenticateToken` + `sensitiveEndpointLimiter` | 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` | 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` | JWT + `sensitiveEndpointLimiter` | — | `{ 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 | | GET | `/api/settings/steam` | JWT + `sensitiveEndpointLimiter` | — | `{ apiKeyConfigured: boolean, source: "env"\|"database"\|null }`; never the key | | POST | `/api/settings/steam` | JWT + `sensitiveEndpointLimiter` | `{ apiKey: string }`; an empty string removes the saved key (the `STEAM_API_KEY` environment variable applies again) | Same as GET; 400 if the key is not a string or not letters and digits (16-128) | ### Apprise settings These authenticated endpoints configure the shared Apprise service. Cookie sessions require the usual CSRF header on POST requests. | Method | Path | Request / response | | ------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/settings/apprise` | `{ configured, mode, apiUrl, key, urls, username, password }`; the password is masked as `********` when saved, including in CLI mode. | | POST | `/api/settings/apprise` | `{ mode: "api" or "cli", apiUrl?, key?, urls?, username?, password? }`; returns `{ success: true }`. API mode requires an API URL and a config key or notification URLs; CLI mode requires notification URLs. | | POST | `/api/settings/apprise/test` | Sends a test using saved settings; `{ success: true }`, or 502 with an error if delivery fails. | The optional API login is for Apprise API servers with `APPRISE_AUTH_REQUIRED=yes`. Usernames cannot contain a colon. The password is encrypted at rest; sending the masked placeholder keeps it, an empty string clears it, and omitting the field leaves it unchanged. HTTPS login requests reject plaintext or cross-origin redirects. An HTTP login sends credentials unencrypted and the UI warns about it; use HTTPS unless the connection is on a trusted network. ## RSS Enabled feeds refresh 10 seconds after startup and every hour. Manual full refreshes share a queued/running scheduled refresh; single-feed refreshes after creation run in the same serialized queue. Disabled feeds are skipped by full refreshes. The browser polls items every five minutes. | 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 `PATCH /api/settings` accepts `notificationPreferences` as a JSON-encoded string. Within `gameUpdates`, `includeShelved` and `includeCompleted` independently control update and pack/add-on notifications for those statuses, for both In-App and Apprise. Missing values mean `true` for compatibility with older preferences. Availability searches and badges still update when notifications are muted. | 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:`). 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](#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](#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 | ## Play time All routes need a JWT; game routes also check that the game belongs to the caller (404 otherwise). Details in [Play time](PLAY_TIME.md). | Method | Path | Request Body | Response | | ------ | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/games/:id/play-sessions` | — | Sessions of the game, newest first | | POST | `/api/games/:id/play-sessions` | `{ durationMinutes: 1–1440, startedAt?: ISO date }` — a session entered by hand | 201 with the session; it ends at `startedAt + duration` (default: ends now). 400 if it would end in the future | | POST | `/api/games/:id/play-sessions/start` | — | 201 with the running session. 409 `{ error, session }` when a timer is already running | | PATCH | `/api/games/:id/play-sessions/:sessionId` | `{ startedAt?: ISO date, endedAt?: ISO date, durationMinutes?: 1–1440 }` — at least one; `endedAt` and `durationMinutes` are exclusive | 200 with the session. A new start alone keeps the length; a duration counts from the start. Same limits as adding one (1 min–24 h, not in the future); 400 otherwise. 409 for a running timer or a `steam`, `playnite` or `playnite_import` session; 404 if not found | | POST | `/api/games/:id/play-sessions/merge` | `{ sessionIds: [uuid, …] }` — 2 to 20 sessions of the game | 201 with the merged session, from the earliest start to the latest end. The sessions must overlap or be at most 30 minutes apart, the result at most 24 h (400 otherwise); it keeps their source when they share one, else `manual`. 409 for a running timer or an imported session, 404 for an unknown id | | POST | `/api/games/:id/play-sessions/:sessionId/split` | `{ splitAt: ISO date }` | 201 with the two new sessions (same source), cut at `splitAt`; each lasts at least a minute (400 otherwise). 409 for a running timer or an imported session; 404 if not found | | DELETE | `/api/games/:id/play-sessions/:sessionId` | — | 204; 404 if not found | | GET | `/api/play-sessions/active` | — | `{ session }` — the running timer, or `null` | | POST | `/api/play-sessions/:sessionId/stop` | — | `{ session, capped }`; `capped` is true when the timer was cut off at 24 hours. 404 if that session is not the running one | | GET | `/api/stats/play-time?timeZone=&tz=&from=&to=` | — | Totals, longest session, streaks, top games/genres/platforms, last 12 weeks and months, `sessionStats` (average, median, length bands) and `heatmap` (per day, weekday, hour). `from`/`to` are inclusive local days that narrow everything except the weekly/monthly charts, streaks and goals. `timeZone` is an IANA name (e.g. `Europe/Paris`, DST-aware, wins when valid); `tz` is `Date#getTimezoneOffset()` (fallback, default 0) | | GET | `/api/stats/play-time/export?format=csv\|json&from=&to=&timeZone=` | — | Finished sessions of the range as a download: CSV (`game,source,started_at,ended_at,minutes`, spreadsheet formulas neutralised) or JSON `{ sessions: [...] }`. Same time zone and range parameters as the statistics | | GET | `/api/stats/backlog?timeZone=&tz=` | — | Backlog burn-down: `{ current, perWeek, perMonth, projection }` | ## Health / Ready / Config | Method | Path | Auth Required | Request Body | Response | | ------ | ------------- | -------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/health` | None (public, listed in `PUBLIC_API_ROUTES`) | — | `{ status: "ok" }` (liveness probe only, no dependency checks) | | GET | `/api/ready` | None (public, listed in `PUBLIC_API_ROUTES`) | — | `{ status, checks: { database, igdb } }` — each check is `"ok"` or `"error"`. 200 with `status: "ok"` when both pass, else 503 with `status: "error"`; read `checks` to tell a local database failure (roll back) from an IGDB outage (wait) | | GET | `/api/config` | JWT + `sensitiveEndpointLimiter` | — | `{ 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](#games). ## Activity and System Tasks Mounted under `/api/activity` and `/api/system` (JWT). Activity only sees the requester's own downloads and games. | Method | Path | Request | Response | | ------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/activity/history` | Query: `eventType?` (`grabbed`, `completed`, `imported`, `failed`, `needs_review`, `removed`, `blocklisted`), `search?` (≤200), `limit?` (1–200, default 50), `offset?` (≥0) | `{ events, total }`, newest first; 400 on invalid query | | DELETE | `/api/activity/blocklist` | — | `{ removed }`: unblocks every release of the user's games | | GET | `/api/system/tasks` | — | `{ tasks }`: each task has `name`, `title`, `description`, `intervalMs`, `running`, `lastStartedAt`, `lastFinishedAt`, `lastDurationMs`, `lastResult` (`success`\|`error`), `lastError`, `lastTrigger` (`schedule`\|`manual`\|`startup`), `nextRunAt` | | POST | `/api/system/tasks/:name/run` | — | 202 `{ task }` and the job runs in the background (progress over Socket.io: `task:started`, `task:finished`); 404 unknown task; 409 if already running | ## Release Scoring Authenticated endpoints behind the **Settings → Discovery & Downloads → Release Scoring** card. Each user has one release profile and any number of custom formats; both are created with defaults (and the old preferred release groups converted) the first time they are read. | Method | Path | Request body | Response | | ------ | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | GET | `/api/release-scoring` | — | `{ profile, formats, builtInRules: [{ id, label, points, locked, rejects }] }` | | PUT | `/api/release-profile` | `{ minScore, protocolPreference: "torrent" or "usenet" or "either", requiredTerms[], ignoredTerms[], minSeeders, maxSizeBytes (or null), builtInOverrides: { : { points?, enabled? } }, formatScores: { : number } }` | The saved profile; 400 for an invalid body or an unknown built-in rule id | | POST | `/api/custom-formats` | `{ name (1–100 chars), specs[] (1–20), score (−10000 to 10000), hardReject?, enabled? }` | 201 with the format; 400 when a spec is invalid (for example a regex RE2 cannot compile) | | PATCH | `/api/custom-formats/:id` | Any of the fields above; fields that are not sent keep their value | The updated format; 404 if it does not exist | | DELETE | `/api/custom-formats/:id` | — | 204, and any per-profile score for that format is removed; 404 if it does not exist | | POST | `/api/custom-formats/install-defaults` | — | 201 `{ added: [...] }`: the recommended formats that were not there yet (matched by name) | A spec is `{ field: "title" or "group" or "uploader" or "category" or "protocol" or "indexer", mode: "contains" or "exact" or "regex", value (1–200 chars), negate?, required? }`. Specs on the same field are alternatives unless marked `required`; every field used must be satisfied. Regexes run on RE2 (no lookarounds) and are case-insensitive. Required and ignored terms are case-insensitive words, or a regex written `/pattern/`. Locked built-in rules (a title that is a sequel of, or not, the wanted game, and an executable or disguised file) always apply and always reject, so `enabled: false` is ignored for them; the others can be re-weighted or disabled in `builtInOverrides`. Search results from `GET /api/search` carry an `evaluation` (score, score lines, rejections, matched formats and, when xREL is enabled, an `xrel` verdict of `verified`, `nuked`, `not_found` or `unavailable`, the last meaning the lookup failed or timed out, so it does not show the release is absent). Rejected releases stay in the manual results so the UI can say why. Manual results also carry a `trust` verdict, `{ level: "trusted" or "unverified" or "risky", reasons: [{ code, tone, label, detail? }] }`, derived from the rejections, the xREL result and size, the preferred release group and the blacklist rather than from the score. The `sortBy` auto-download rule also accepts `score`. When the full query returns nothing on the first page, `GET /api/search` retries, only when no indexer errored, with up to three of its simpler variants, tried from the least to the most lossy (without a possessive publisher prefix, without edition words, without punctuation, without the subtitle; variants that do not apply to the title are skipped) and answers with the first variant that finds releases in `queryUsed`; the results are then scored against the game's title without its possessive prefix and edition words (the subtitle is kept, so a release of another game of the series is not taken for the wanted one). The field is absent when the query itself found them. The optional `title` parameter lets a later page of such a search (`offset` > 0, sent with the variant as `query`) keep scoring against the original title. ## 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 | ### Steam play time `server/steam-playtime-routes.ts` — turns the Steam play-time sync on or off and runs it. See [Play time](PLAY_TIME.md#steam-play-time). All routes require a JWT; responses are not cached. | Method | Path | Body | Response | | ------ | ------------------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/steam/playtime` | — | `{ available, enabled, lastSyncAt, lastSessionsAdded, lastMinutesAdded, lastError }`; `available` is false without `STEAM_API_KEY` or a saved Steam ID | | PUT | `/api/steam/playtime` | `{ enabled: boolean }` | The same status. Turning the sync on starts from fresh baselines; 400 on another body | | POST | `/api/steam/playtime/sync` | — | `{ result: { sessionsAdded, minutesAdded, baselined }, status }`; 400 if the sync is off or Steam is not set up; 409 if a sync is running; 502 `{ error, status }` on a Steam failure, 500 with a fixed message for any other failure | | GET | `/api/steam/playtime/import/preview` | — | `{ candidates: [{ gameId, title, steamMinutes, recordedMinutes, importMinutes, lastPlayedAt }], skipped }`; writes nothing; 400 if Steam is not set up; 502 on a Steam failure | | POST | `/api/steam/playtime/import` | `{ gameIds?: string[] }` | `{ sessionsAdded, minutesAdded }`. Imports one `steam_import` session per listed game (all when omitted); minutes are recomputed server side; 409 while a sync or import runs; 400 on another body | ### Owned Steam library `server/steam-library-routes.ts` — preview and import endpoints. These endpoints require the normal authenticated session/token. Cookie mutations require the usual CSRF header. Responses use `Cache-Control: no-store`. - `GET /api/steam/library`: read the linked account's public Steam library. Returns `{ games: [{ steamAppId, title, alreadyTracked }] }`; preview does not write to the library. Missing server Steam key or linked ID returns 400; Steam failure/private library returns 502 with an actionable generic error. - `POST /api/steam/library/import`: synchronous compatibility endpoint, body `{ appIds: [400, 620] }`, 1–50 positive integer IDs. Ownership is checked again with Steam before any write. Returns `{ results: [{ steamAppId, title, outcome }] }`, where outcome is `added`, `duplicate`, `not_found` (unmapped or content-filtered), or `failed`. New games are Owned/source `steam`; existing game states remain unchanged, with missing Steam App IDs linked on exact IGDB matches. Invalid/stale selections return 400, a concurrent import by the same account returns 409, and an upstream batch failure returns 502. Partial row failures return 200 with per-row outcomes so callers can retry explicitly. - `POST /api/steam/library/import/jobs`: body `{ appIds: [...] }`, 1–20,000 positive integer IDs. Returns `202 { job }` after durably queuing the selection. Duplicate IDs are collapsed. The worker rechecks ownership before game writes; invalid/stale ownership is reported as a failed job. A concurrent import start returns 409. A new start replaces the account's previous terminal job. - `GET /api/steam/library/import/jobs/current`: returns `{ job: null }` or the account's latest job view. Available even if Steam configuration is removed. View fields: `id`, `state` (`queued`, `running`, `completed`, `failed`), `total`, `processed`, `added`, `duplicates`, `skipped`, `failed`, `canRetry`, `completedAppIds`, `recentResults` (last ten), and optional `message`. It does not return the saved Steam ID or pending selection. The browser polls every two seconds while active. A completed job may still contain skipped/failed rows. - `POST /api/steam/library/import/jobs/retry`: no body required. Queues failed and unprocessed IDs from the latest job; returns `202 { job }`, 400 if nothing remains, or 409 if another import is running. The new job carries the earlier outcomes, so `total` and the counters continue; successful earlier writes are preserved. Retry revalidates current Steam ownership. See [Steam library import](STEAM_LIBRARY.md) for prerequisites and limits. ## 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` — 5 routes, mounted at `/api/integration`, plus the SeerrNG provider routes under `/api/integration/seerrng/v1` (`server/routes/seerrng.ts`, documented in [SEERRNG.md](SEERRNG.md)). 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](https://github.com/Doezer/Questarr/blob/main/extensions/playnite-questarr/README.md), scripts, other self-hosted tools. The key is presented as `X-Api-Key: ` or `Authorization: Bearer ` (keys are recognised by their `qsr_` prefix, so a Bearer header is unambiguous between a key and a JWT). Each key carries one **scope** and an optional **expiry** (see [API Keys (management)](#api-keys-management)). A route declares the scopes that may call it with `requireScope(...)`; `all` satisfies every route, and a JWT session is never restricted by scope. A key outside a route's scope gets 403 `{ error, code: "API_KEY_SCOPE_DENIED" }`; an expired key gets 401 `{ error: "API key expired", code: "API_KEY_EXPIRED" }`. Requests are limited to 300/min per key (`integrationRateLimiter`). | Route | `library:write` | `read` | `requests` | `admin` | `all` | | ----------------------------------------------------------------------------------------------------------------------------------------- | :-------------: | :----: | :--------: | :-----: | :---: | | `GET /ping` | ✓ | ✓ | ✓ | ✓ | ✓ | | `GET /library` | ✓ | ✓ | — | ✓ | ✓ | | `POST /library/sync`, `POST /games/request`, `POST /play-sessions`, `POST /play-status`, `POST /play-time-totals`, `POST /library/import` | ✓ | — | — | — | ✓ | | `/seerrng/v1/*` (see [SeerrNG provider](SEERRNG.md)) | — | — | ✓ | — | ✓ | Authentication is handled by `authenticateApiKeyOrToken` in `server/auth.ts`, selected by `requireAuthenticationForApi` for paths under `/integration` and for the `admin`-scope allowlist below. Every other protected route 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, scope, expiresAt }` (`scope`/`expiresAt` are `null` for a JWT session; `expiresAt` is `null` for a key that never expires) | | 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 | | POST | `/api/integration/play-sessions` | JWT or API key (`library:write`) | `{ gameId?, steamAppId?, title?, startedAt, endedAt }` — at least one of `gameId`, `steamAppId`, `title`; matched in that order, never creates a game. Max 24 h, not in the future (5 min slack), `endedAt` ≥ `startedAt` | 201 `{ session, duplicate: false }` (source `playnite`); 200 `{ session, duplicate: true }` when the game already has a `playnite` session starting at that instant (manual and timer sessions are not compared); 404 `{ code: "GAME_NOT_FOUND" }` if no library game matches; 400 on invalid data | | POST | `/api/integration/play-status` | JWT or API key (`library:write`) | `{ games: [{ title, status, gameId?, steamAppId?, externalId?, platform? }], promoteWanted?: false }` — `status` is a Playnite completion status (`Not Played`, `Plan to Play`, `Played` → owned; `Playing` → playing; `On Hold`, `Abandoned` → shelved; `Beaten`, `Completed` → completed). Games are matched by `gameId`, then `steamAppId`, then normalized title, and never created. At most 5000 entries | 200 `{ received, updated, unchanged, skipped, unmatched, results[] }`, one result per entry with `result` and, when skipped, `reason`: `manual_status` (the user's own playing/shelved/completed status always wins; a status written by an earlier sync can be replaced), `wanted` (unless `promoteWanted`), `downloading`, `unknown_status`. `platform` (`steam`, `gog`, `epic`, otherwise `playnite`) is stored as the game's `statusSyncSource`; any status the user sets afterwards clears it | | POST | `/api/integration/play-time-totals` | JWT or API key (`library:write`) | `{ games: [{ title, playtimeSeconds, gameId?, steamAppId?, externalId?, lastPlayedAt? }] }` — `playtimeSeconds` is the total a store library (GOG, through Playnite) holds for the game. Games are matched like a play session and never created. At most 5000 entries | 200 `{ received, imported, unchanged, skipped, unmatched, minutesAdded, results[] }`. The recorded play time of the game is subtracted from the total and the difference becomes one estimated session (source `playnite_import`, ending at `lastPlayedAt` or now); a gap under 10 minutes is ignored, so sending the same total again adds nothing. A game with the running timer is `skipped` (`timer_running`) | | POST | `/api/integration/library/import` | JWT or API key (`library:write`) | `{ games: [{ title, platform?, externalId?, steamAppId? }] }`, at most 25 entries (each new title is looked up on IGDB) — adds the games the library does not have yet as `owned`, with `platform` (`steam`, `gog`, `epic`, otherwise `api`) as the game's `source` | 200 `{ received, added, existing, notFound, results[] }`. A title IGDB matches to another game (a sequel, a different subtitle) is `not_found` and not added; edition suffixes such as "Game of the Year Edition" are accepted. Games already in the library, by Steam App ID or normalized title, are `existing` | | GET | `/api/playnite/sync` | JWT | — | When Playnite last sent statuses, a library import and play time totals (counters of that request, last failure), plus how many game statuses each store currently owns (`syncedStatuses`). Shown under **Settings → Connections → Steam Integration → Playnite sync**. | `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. ## Outbound webhooks `server/routes/webhooks.ts` — mounted at `/api/webhooks`, JWT or an `admin`-scope API key. Events, payload, signature and retry rules are in [Webhooks](WEBHOOKS.md). All responses are `Cache-Control: no-store`; a user may hold at most 20 webhooks. | Method | Path | Auth Required | Request Body | Response | | ------ | ------------------------------ | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | GET | `/api/webhooks` | JWT or admin key | — | `{ subscriptions: Array<{ id, userId, name, url, events, enabled, createdAt, updatedAt }>, events: string[] }` — never includes the secret | | POST | `/api/webhooks` | JWT or admin key + `sensitiveEndpointLimiter` | `{ name (1–100), url (http/https, no credentials, SSRF-checked), events: string[] (≥1 of the event types), enabled?, secret? (16–200 chars; generated when omitted) }` | 201 subscription + `secret` (shown only here); 400 invalid or unsafe URL; 409 at 20 webhooks | | PATCH | `/api/webhooks/:id` | JWT or admin key + `sensitiveEndpointLimiter` | Partial: `name?, url?, events?, enabled?, secret?, rotateSecret?` — `rotateSecret: true` generates a new secret | Updated subscription (+ `secret` only when `rotateSecret` was sent); 404 if not found or not yours | | DELETE | `/api/webhooks/:id` | JWT or admin key + `sensitiveEndpointLimiter` | — | 204; the delivery log goes with it | | POST | `/api/webhooks/:id/test` | JWT or admin key + `sensitiveEndpointLimiter` | — | `{ success: true, statusCode, durationMs }`, or 502 `{ success: false, error, statusCode }`. One attempt, no retry; recorded in the log | | GET | `/api/webhooks/:id/deliveries` | JWT or admin key | — | Last 50 attempts, newest first: `Array<{ id, subscriptionId, eventId, eventType, attempt, statusCode, error, durationMs, createdAt }>` | ## 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. `last_used_at` is written at most once per minute per key. | Method | Path | Auth Required | Request Body | Response | | ------ | ------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/api-keys` | JWT | — | `Array<{ id, userId, name, prefix, createdAt, lastUsedAt, scope, expiresAt }>` — never includes the hash | | POST | `/api/api-keys` | JWT + `sensitiveEndpointLimiter` | `{ name: string (1–100 chars), scope?: "all" \| "library:write" \| "read" \| "requests" \| "admin" (default "all"), expiresInDays?: 1–365 \| null (default: never) }` | 201 `{ id, userId, name, prefix, createdAt, lastUsedAt, scope, expiresAt, 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: ```json { "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: ```json { "error": "Invalid 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": "" }` 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: ```json { "error": "", "details": "" } ``` 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](ARCHITECTURE.md#6-out-of-band-channel-socketio) 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/GameDetails.tsx` | Every authenticated socket joins a per-user room, `user:`, during the handshake. Delivery depends on whether the event has an owner: - `notification` events that carry a `userId` go only to that user's sockets (`io.to("user:")`). Other accounts on the same instance don't receive them. - Ownerless notifications and app-wide events (`downloadUpdate`, `importTaskUpdate`, `gameUpdated`, `library-scan-progress`, `logLine`) are broadcast to every authenticated socket (`io.emit`). Clients don't need to join rooms themselves. Connect with the auth cookie (or a bearer token in `auth.token`) and the server assigns the room: ```ts import { io } from "socket.io-client"; const socket = io({ withCredentials: true }); socket.on("notification", (n) => console.log("for me:", n)); socket.on("downloadUpdate", (gameId) => console.log("download changed:", gameId)); ``` ### Configuration API for automation (`admin` scope) A key with the `admin` scope can also call a fixed allowlist of configuration routes, so deployment tooling can set Questarr up without an interactive login. `all` does **not** imply `admin`, and an `admin` key is refused on the integration routes it was not granted. Any other key gets 403 `API_KEY_SCOPE_DENIED` here. The integration routes above are the only other place a key is accepted; every other protected route stays JWT-only — `/api/api-keys` in particular, so a key can never mint or revoke another key. Send the key in `X-Api-Key` or `Authorization: Bearer`. Treat an `admin` key like an administrator login: it can change download clients, indexers, notification delivery, settings and import paths. | Area | Routes | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Downloaders | `GET`/`POST /api/downloaders`, `PATCH`/`DELETE /api/downloaders/:id`, `POST /api/downloaders/:id/test` | | Indexers | `GET /api/indexers`, `POST /api/indexers/:id/test`, `GET /api/indexers/prowlarr/settings`, `POST /api/indexers/prowlarr/sync` | | Webhooks | `GET`/`POST /api/webhooks`, `PATCH`/`DELETE /api/webhooks/:id`, `POST /api/webhooks/:id/test`, `GET /api/webhooks/:id/deliveries` | | Settings | `GET`/`PATCH /api/settings`, `GET`/`POST /api/settings/apprise`, `POST /api/settings/apprise/test` | | Imports | `GET`/`PATCH /api/imports/config`, `GET`/`POST /api/imports/mappings/paths`, `PATCH`/`DELETE /api/imports/mappings/paths/:id`, `GET /api/imports/hardlink/check` | The allowlist lives in `server/admin-api-routes.ts`.