RSSMonster API

RSSMonster exposes a JSON API for its web client and for custom integrations. The routes are not versioned: they are served below /api on the same host as RSSMonster.

https://your-rssmonster.example/api

Most routes require a JSON Web Token (JWT). The Fever and Google Reader compatibility APIs use their own authentication schemes; their credentials are not interchangeable with a JWT.

Authentication

Request a JWT

Obtain a token by sending the user’s RSSMonster credentials to POST /api/auth/login:

curl --request POST \
  --header 'Content-Type: application/json' \
  --data '{"username":"<username>","password":"<password>"}' \
  'https://your-rssmonster.example/api/auth/login'

A successful response has this shape:

{
  "message": "Connected!",
  "token": "<jwt>",
  "user": {
    "id": 1,
    "username": "example"
  },
  "expiresInSeconds": 86400,
  "agenticFeaturesEnabled": false
}

The user object can contain additional non-secret account fields. Store the value of token and send it in the bearer authorization header on subsequent requests:

curl --header 'Authorization: Bearer <jwt>' \
  'https://your-rssmonster.example/api/feeds'

Use POST /api/auth/validate with the same header to check whether a token is still valid. Its successful response includes the authenticated user, the decoded token data, and whether agentic features are enabled.

JWT lifetime is controlled by JWT_EXPIRES_IN and defaults to 86,400 seconds (24 hours). RSSMonster does not expose refresh-token, logout, or token-revocation endpoints. When a token expires, log in again; to log out a client should discard its token. Changing a password invalidates older sessions using the stored password-change version; changing JWT_SECRET invalidates all previously issued JWTs. See Configuration for the server settings.

Registration and development login

POST /api/auth/register creates an account from username, password, and password_repeat, plus email when email is enabled. Registration does not return a JWT, so the new user must log in afterwards. Read GET /api/auth/configuration for the email capability. With email enabled, login can return an email-verification requirement and a short-lived emailEnrollmentToken instead of a normal session. Use that bearer token only for /api/auth/email-enrollment and its resend endpoint. See Account and Email.

POST /api/auth/development-login can issue a normal JWT without a password, but only when all of the development-login settings are enabled. This is meant for local debugging or a deliberately configured personal installation, never for a publicly reachable production server. See First Login for setup and security details.

Authentication errors

Protected native routes require an Authorization: Bearer <jwt> header. A missing, malformed, expired, or invalid token currently returns HTTP 400 with:

{
  "message": "Your session is not valid!"
}

Clients should therefore treat this response as an authentication failure even though it is not returned as HTTP 401.

Public endpoints

These native routes do not require a JWT:

Method	Endpoint	Purpose
GET	/api/auth/configuration	Read public authentication capability flags
POST	/api/auth/verify-email/confirm	Confirm an email verification token
POST	/api/auth/password-reset/request	Request recovery for an email address without disclosing account existence
POST	/api/auth/password-reset/confirm	Reset a password with its recovery token
POST	/api/auth/register	Create a user account
POST	/api/auth/login	Exchange username and password for a JWT
POST	/api/auth/development-login	Log in as the configured development user when enabled
GET	/api/health	Return process uptime and verify database access plus required feed/article tables

The Google Reader compatibility check and login routes are also public, but they belong to that protocol’s authentication flow.

Native endpoint reference

All endpoints in this section require a JWT unless marked otherwise above. Exact request and response fields are the current application’s contract; use the route names below as the discovery map when building an integration.

Articles and reading state

Method	Endpoint	Purpose
GET	/api/articles	List and search articles
GET	/api/articles/briefing	Get structured briefing context and story overview
GET	/api/articles/:articleId	Get one article
GET	/api/articles/duplicates/:articleId	Get duplicate articles
GET	/api/articles/:articleId/recommendations	Get related recommendations
GET	/api/articles/:articleId/developing-story	Get continuing coverage for an article’s story
GET	/api/articles/:articleId/story-sources	Get the story’s source coverage
POST	/api/articles/details	Get details for a set of articles
POST	/api/articles/markasread	Mark articles as read
POST	/api/articles/markallasread	Mark the selected article set as read
POST	/api/articles/marktounread/:articleId	Mark an article unread
POST	/api/articles/markasseen/:articleId	Mark an article seen
POST	/api/articles/markclicked	Record article clicks in bulk
POST	/api/articles/markclicked/:articleId	Record an article click
POST	/api/articles/markasfavorite	Change favorite state in bulk
POST	/api/articles/markasfavorite/:articleId	Change an article’s favorite state
POST	/api/articles/marknotinterested/:articleId	Record negative interest feedback
POST	/api/articles/markmorelikethis/:articleId	Record positive interest feedback

The article list accepts RSSMonster’s search language. See Search for all expressions, including expressions shared with Smart Folders.

Feeds and categories

Method	Endpoint	Purpose
GET, POST	/api/feeds	List or create feeds
GET, PUT, DELETE	/api/feeds/:feedId	Read, update, or delete a feed
POST	/api/feeds/test-scraper	Preview HTML + XPath extraction
POST	/api/feeds/validate	Validate a prospective feed
POST	/api/feeds/refresh	Start a feed refresh job
GET	/api/feeds/refresh/:jobId/events	Follow refresh progress using server-sent events
POST	/api/feeds/recalculate-trust	Recalculate feed trust scores
GET	/api/feeds/:feedId/observability	Get feed crawl and health diagnostics
GET	/api/feeds/:feedId/crawls/:crawlResultId	Get one crawl result
POST	/api/feeds/:feedId/retry	Retry a feed crawl
POST	/api/feeds/:feedId/rediscover-rss	Rediscover a site’s feed URL
POST	/api/feeds/mute/:feedId	Change a feed’s muted state
GET, POST	/api/categories	List or create categories
GET, PUT, DELETE	/api/categories/:categoryId	Read, update, or delete a category

Organization, discovery, and insights

Method	Endpoint	Purpose
GET	/api/tags	List the user’s most-used tags, optionally filtered by status
GET	/api/smartfolders	List Smart Folders
POST	/api/smartfolders	Replace the user’s complete Smart Folder list
GET	/api/smartfolders/counts	Get Smart Folder article counts
GET	/api/smartfolders/insights	Get Smart Folder insights
POST	/api/events/articles	Get articles associated with an event
GET	/api/briefing/preferences	Get briefing preferences
PUT	/api/briefing/preferences	Update briefing preferences

Generated feeds

Method	Endpoint	Purpose
GET, POST	/api/generated-feeds	List or create generated feeds
GET, PUT, DELETE	/api/generated-feeds/:id	Read, update, or delete a generated feed
POST	/api/generated-feeds/:id/regenerate-token	Rotate the public URL’s access token

GET /rss/generated/:token returns RSS without a login header; possession of the URL grants access. See Generated Feeds for expressions, limits, and revocation.

Account, email, and notifications

Method	Endpoint	Purpose
GET, PATCH	/api/auth/account	Read or update the user’s password, email, and digest preferences
POST	/api/auth/account/daily-briefing-test	Queue a test briefing for a verified address
GET, PATCH	/api/auth/email	Read or change the saved email address
POST	/api/auth/verify-email/request	Request verification for the saved email address
GET, PUT	/api/auth/email-enrollment	Inspect or update enrollment; requires an enrollment token, not a session JWT
POST	/api/auth/email-enrollment/resend	Resend verification using an enrollment token
GET	/api/push/configuration	Read Push availability and public VAPID key
GET	/api/push/subscription	Report whether the user has any stored Push subscription
POST	/api/push/subscription	Save endpoint, keys, and optional expirationTime from a browser subscription
DELETE	/api/push/subscription	Remove the user’s subscription identified by body field endpoint

Account updates use the full form contract; inspect client/src/api/auth.js and server/services/accountSettings.js before constructing a request. Verification, recovery, and enrollment tokens have separate purposes and cannot replace a normal API session. See Account and Email.

Subscription management and maintenance

Method	Endpoint	Purpose
POST	/api/manager/overview	Get the subscription-management overview
GET	/api/manager/overview-lite	Get a lightweight management overview
POST	/api/manager/overview-counts	Get management counts
POST	/api/manager/updateorder	Update feed or category ordering
POST	/api/manager/changecategory	Move subscriptions between categories
GET	/api/crawl	Trigger a crawl
POST	/api/cleanup	Run authenticated cleanup processing
GET	/api/opml/export	Export subscriptions as OPML
POST	/api/opml/preview	Start validation for a multipart opmlFile upload and return a preview job ID
GET	/api/opml/preview/:previewId/status	Poll user-scoped validation progress and return the completed JSON preview
POST	/api/opml/import	Import only subscriptions marked selectedForImport: true in a JSON preview returned by the preview endpoint

Although /api/crawl changes server state, its current route uses GET. Maintenance routes can be expensive and should not be polled unnecessarily.

Settings, actions, and administration

Method	Endpoint	Purpose
GET, POST	/api/setting	Get or update user settings
GET	/api/setting/crawl-statistics	Get crawl statistics
GET	/api/setting/processing-jobs	Get the current user’s AI processing queue and worker health status
DELETE	/api/setting/processing-jobs	Delete the current user’s succeeded and dead processing-job history
GET	/api/setting/observability	Get grouped processing failures
GET	/api/setting/observability/groups/:fingerprint	Get occurrences of a failure group
GET	/api/setting/observability/failures/:failureId	Get one failure’s details
DELETE	/api/setting/observability	Clear the current user’s recorded processing failures
POST	/api/setting/islands/recalculate	Recalculate the current user’s interest islands
GET	/api/setting/islands	Get Interest Island insights
GET	/api/setting/events	Get Event insights
GET, POST	/api/setting/official-sources	Get or update official-source settings
PATCH	/api/setting/developing-events	Update developing-event settings
PATCH	/api/setting/theme	Update the theme
PATCH	/api/setting/startup-view	Update the startup view
PATCH	/api/setting/mark-as-read-on-scroll	Update scroll reading behavior
PATCH	/api/setting/prioritize-high-trust	Update high-trust prioritization
GET	/api/actions	List article-processing rules
POST	/api/actions	Replace the user’s complete rules list
GET	/api/users/email-configuration	Inspect email readiness; administrator only
POST	/api/users/email-configuration/test	Test SMTP connectivity without sending mail; administrator only
GET	/api/users	List users; administrator only
GET	/api/users/:userId	Get a user; administrator only
POST	/api/users/:userId	Update a user; administrator only
DELETE	/api/users/:userId	Delete another user; administrator only

RSSMonster is multi-user. Controllers scope feeds, articles, settings, and related results to the authenticated user. A valid JWT does not grant access to another user’s data; the user-management routes additionally require an administrator account.

Other API surfaces

RSSMonster also exposes protocol-specific and machine-oriented interfaces:

Endpoint	Authentication	Documentation
/api/fever	Fever api_key or legacy Fever login cookie	Fever API
/api/greader/*	GoogleLogin token; mutations also require an action token	Google Reader API
/api/agent	JWT bearer token	Accepts agent messages or input and returns an assistant response when the provider is configured
/mcp	JWT bearer token	Model Context Protocol transport for authenticated RSSMonster tools
/rss	JWT bearer token	Personal RSS output with feed, category, unread, starred, and limit filters

/api/agent requires the AI and assistant enable flags and a configured inference provider. MCP exposes authenticated tools independently of the built-in assistant provider. The /rss and /mcp routes are mounted outside /api, but use the same JWT bearer authentication. See Assistant and MCP.

Request conventions and limits

• Send JSON bodies with Content-Type: application/json, except for protocol endpoints and multipart OPML uploads.
• Cross-origin API requests may use GET, POST, PUT, PATCH, and DELETE with the Content-Type and Authorization headers.
• The default API limit is 600 requests per 15 minutes. Configure it with API_RATE_LIMIT_WINDOW_MS and API_RATE_LIMIT_MAX; the health endpoint and preflight requests are excluded. MCP has an additional, lower configurable limit.
• Article-list loading (GET /api/articles), detail loading (POST /api/articles/details), and read/seen updates (markasread, markallasread, markasseen/:articleId, marktounread/:articleId) share a separate allowance of 3,000 requests per client IP per API window, configured with ARTICLE_INTERACTION_RATE_LIMIT_MAX. These requests do not consume the general API allowance. Other article endpoints retain the general limit.
• A rate-limited request returns HTTP 429.
• JSON responses intentionally omit contentOriginal. Integrations should use the normalized article content fields returned by the relevant endpoint.
• Serve RSSMonster over HTTPS when credentials or tokens cross a network. A reverse proxy must preserve the Authorization header.

The web client uses these same routes, so its network requests and the corresponding files in server/routes/ are useful references for exact payload shapes not covered on this overview page.