Returns the FreshRSS account the server is authenticated as. Useful as a connection and credential check before anything else.

Lists every subscribed feed with its category and unread count. The numeric feedId is what all other tools take as feed_id. Start here to find out what is subscribed before listing articles.

Returns how many unread articles are waiting, in total and per feed and category, sorted by count. Only entries with unread articles are listed.

Lists articles from a feed, category, label or built-in stream, newest first. Returns short plain-text excerpts by default; set include_content=true for the article text, or fetch single articles with get_articles. FreshRSS has no full-text search over its API, so there is no way to query by keyword — narrow the result with feed_id/category and since/until instead and filter the returned articles yourself.

Fetches the full text of specific articles by id, as plain text. At most 20 ids per call.

Lists only the ids of matching articles — the cheap way to collect a set for mark_articles. Same selectors and filters as list_articles.

Lists the categories (folders that hold feeds) and the user labels (tags that are attached to individual articles), each with its unread count. Both are addressed by name in the other tools.

Exports all subscriptions as an OPML document — the portable backup format for feed readers. For a readable overview of the subscriptions use list_feeds instead.

Subscribes to a feed. The URL may point at the feed itself or at a website — FreshRSS discovers the feed and then downloads it, so this call can take a while. A category that does not exist yet is created.

Renames a feed and/or moves it to another category. A category that does not exist yet is created. Fields that are not given stay unchanged.

Deletes a feed together with all of its stored articles, read state and stars. Two-step: the first call returns a confirmation token, the second call with that token performs the deletion. This cannot be undone — re-subscribing starts from whatever the feed currently offers.

Sets the read state, the star and user labels of specific articles. Starring and labelling are reversible by calling this tool again with the opposite value. Marking as read is not, so read=true asks a person first; where the client cannot show a dialog, call once to receive a token and again with it. At most 100 articles per call; every given change is applied to all of them.

FreshRSS answers OK whether or not it recognised the ids, so the result of this tool cannot tell you the change landed. Use the ids exactly as list_article_ids returned them — not the long tag:google.com,... form — and confirm with get_unread_counts if it matters: the count is the only thing that moves.

Marks every article of a feed, category, label or built-in stream as read. Two-step: the first call returns a confirmation token, the second call with that token performs the change. Which articles were unread before cannot be recovered afterwards.

Renames a category (folder) or a user label. FreshRSS resolves the name against its categories first and falls back to labels, so one tool covers both. Feeds and articles keep their assignment.

Deletes a category (its feeds move to the default category, no articles are lost) or a user label (it is detached from every article). FreshRSS matches categories first, so a category and a label of the same name cannot be told apart here. Two-step: the first call returns a confirmation token, the second call with that token performs the deletion.

Subscribes to every feed in an OPML document, creating the categories it names, and then refreshes all feeds — which can take minutes on a large file. There is no bulk undo; every feed would have to be removed individually. Two-step: the first call returns a confirmation token, the second call with that token performs the import.