API Reference

API is pluggable, plugins can use host add_api_method() to add custom API calls (see classes/pluginhost.php for details).

API is stateful. You need to login and maintain a session ID to perform further operations. Session ID should be specified using JSON parameter sid. I.e.

curl -d '{"sid":"your-session-id","op":"getVersion"}' http://example.com/tt-rss/api/

All API calls output JSON-encoded data. API can be enabled or disabled per-user in the preferences. Client parameters should be passed encoded using JSON in HTTP POST data (supported since version:1.5.3). Older versions allowed passing parameters using HTTP GET and POST, but this is no longer supported.

Numeric values

Numbers can also be passed (and are sometimes returned) as quoted string literals, i.e. "0".

Some tt-rss versions have issues recognizing 0 as a valid number (unimplemented strict type checking causes 0 to be equivalent to false in getHeadlines, etc) so it might be a good idea to pass numerics as quoted strings for better backwards compatibility.

Boolean values

For boolean parameters the expected syntax is:

https://git.tt-rss.org/fox/tt-rss/src/master/classes/api.php#L11

• empty string, numeric zero, unquoted false literal (?), string literal "f" or "false": FALSE
• anything else: TRUE

Testing API calls (using curl)

curl -d '{"op":"login","user":"you","password":"xxx"}' http://example.com/tt-rss/api/

curl -d '{"sid":"...","op":"getHeadlines","feed_id":"0","is_cat":"1"}' http://example.com/tt-rss/api/

Most of the calls (except login, logout, isLoggedIn) require valid login session or will return this error object: {“error”:“NOT_LOGGED_IN”}

Output format

All API methods return JSON data like this:

{"seq":0,"status":0,"content":{"version":"1.4.3.1"}}

• seq (integer) is the sequence number supplied by client ("seq":131)
• status (integer) indicates whether request has been completed successfully, can be either 0 (API_STATUS_OK) or 1 (API_STATUS_ERR)
• content is the actual reply content, as documented below in method descriptions.

1.4.3 and below (obsolete)

Methods return the “content” object below, sequence numbers and statuses are not supported.

Methods

getApiLevel (since version:1.5.8, api level 1)

Return an abstracted integer API version level, increased with each API functionality change. This is the proper way to detect host API functionality, instead of using getVersion.

{"level":1}

Whether tt-rss returns error for this method (e.g. version:1.5.7 and below) client should assume API level 0.

getVersion

Returns tt-rss version. As of, version:1.5.8 it is not recommended to use this to detect API functionality, please use getApiLevel instead.

{"version":"1.4.0"}

login

Parameters:

• user (string)
• password (string)

Returns client session ID.

{"session_id":"xxx"}

It can also return several error objects:

• If API is disabled for this user: error: “API_DISABLED”
• If specified username and password are incorrect: error: “LOGIN_ERROR”

In case it isn’t immediately obvious, you have to login and get a session ID even if you are using single user mode. You can omit user and password parameters.

• On version:1.6.0 and above login also returns current API level as an api_level integer, you can use that instead of calling getApiLevel after login.
• Since API 17, also returns configuration object (see getConfig below).

logout

Closes your login session. Returns either status-message {“status”:“OK”} or an error (e.g. {“error”:“NOT_LOGGED_IN”})

isLoggedIn

Returns a status message with boolean value showing whether your client (e.g. specific session ID) is currently logged in.

{"status":false}

getUnread

Returns an integer value of currently unread articles.

{"unread":"992"}

getCounters

Returns JSON-encoded counter information. Requires version:1.5.0.

• output_mode (string, default: flc) - what kind of information to return (f - feeds, l - labels, c - categories, t - tags)

getFeeds

Returns JSON-encoded list of feeds. The list includes category id, title, feed url, etc.

Parameters:

• cat_id (integer) - return feeds under category cat_id
• unread_only (bool) - only return feeds which have unread articles
• limit (integer) - limit amount of feeds returned to this value
• offset (integer) - skip this amount of feeds first
• include_nested (bool) - include child categories (as Feed objects with is_cat set) requires version:1.6.0

Pagination:

Limit and offset are useful if you need feedlist pagination. If you use them, you shouldn’t filter by unread, handle filtering in your app instead.

Special category IDs are as follows:

• 0 Uncategorized
• -1 Special (e.g. Starred, Published, Archived, etc.)
• -2 Labels

Added in version:1.5.0:

• -3 All feeds, excluding virtual feeds (e.g. Labels and such)
• -4 All feeds, including virtual feeds

Known bug: Prior to version:1.5.0 passing null or 0 cat_id to this method returns full list of feeds instead of Uncategorized feeds only.

getCategories

Returns JSON-encoded list of categories with unread counts.

• unread_only (bool) - only return categories which have unread articles
• enable_nested (bool) - switch to nested mode, only returns topmost categories requires version:1.6.0
• include_empty (bool) - include empty categories requires version:1.7.6

Nested mode in this case means that a flat list of only topmost categories is returned and unread counters include counters for child categories.

This should be used as a starting point, to display a root list of all (for backwards compatibility) or topmost categories, use getFeeds to traverse deeper.

getHeadlines

Returns JSON-encoded list of headlines.

Parameters:

• feed_id (integer|string) - only output articles for this feed (supports string values to retrieve tag virtual feeds since API level 18, otherwise integer)
• limit (integer) - limits the amount of returned articles (see below)
• skip (integer) - skip this amount of feeds first
• filter (string) - currently unused (?)
• is_cat (bool) - requested feed_id is a category
• show_excerpt (bool) - include article excerpt in the output
• show_content (bool) - include full article text in the output
• view_mode (string = all_articles, unread, adaptive, marked, updated)
• include_attachments (bool) - include article attachments (e.g. enclosures) requires version:1.5.3
• since_id (integer) - only return articles with id greater than since_id requires version:1.5.6
• include_nested (boolean) - include articles from child categories requires version:1.6.0
• order_by (string) - override default sort order requires version:1.7.6
• sanitize (bool) - sanitize content or not requires version:1.8 (default: true)
• force_update (bool) - try to update feed before showing headlines requires version:1.14 (api 9) (default: false)
• has_sandbox (bool) - indicate support for sandboxing of iframe elements (default: false)
• include_header (bool) - adds status information when returning headlines, instead of array(articles) return value changes to array(header, array(articles)) (api 12)

Limit:

Before API level 6 maximum amount of returned headlines is capped at 60, API 6 and above sets it to 200.

This parameters might change in the future (supported since API level 2):

• search (string) - search query (e.g. a list of keywords)
• search_mode (string) - all_feeds, this_feed (default), this_cat (category containing requested feed)
• match_on (string) - ignored

Special feed IDs are as follows:

• -1 starred
• -2 published
• -3 fresh
• -4 all articles
• 0 - archived
• IDs < -10 labels

Sort order values:

• date_reverse - oldest first
• feed_dates - newest first, goes by feed date
• (nothing) - default

updateArticle

Update information on specified articles.

Parameters:

• article_ids (comma-separated list of integers) - article IDs to operate on
• mode (integer) - type of operation to perform (0 - set to false, 1 - set to true, 2 - toggle)
• field (integer) - field to operate on (0 - starred, 1 - published, 2 - unread, 3 - article note since api level 1)
• data (string) - optional data parameter when setting note field (since api level 1)

E.g. to set unread status of articles X and Y to false use the following:

?article_ids=X,Y&mode=0&field=2

Since version:1.5.0 returns a status message:

{"status":"OK","updated":1}

“Updated” is number of articles updated by the query.

getArticle

Requests JSON-encoded article object with specific ID.

• article_id (integer) - article ID to return as of 15.10.2010 git or version:1.5.0 supports comma-separated list of IDs

Since version:1.4.3 also returns article attachments.

getConfig

Returns tt-rss configuration parameters:

{"icons_dir":"icons","icons_url":"icons","daemon_is_running":true,"num_feeds":71}

• icons_dir - path to icons on the server filesystem
• icons_url - path to icons when requesting them over http
• daemon_is_running - whether update daemon is running
• num_feeds - amount of subscribed feeds (this can be used to refresh feedlist when this amount changes)
• custom_sort_types - map of plugin-provided article sort types (API 17+)

updateFeed

Tries to update specified feed. This operation is not performed in the background, so it might take considerable time and, potentially, be aborted by the HTTP server.

• feed_id (integer) - ID of feed to update

Returns status-message if the operation has been completed.

{"status":"OK"}

getPref

Returns preference value of specified key.

• pref_name (string) - preference key to return value of

{"value":true}

catchupFeed

Required version: version:1.4.3

Tries to catchup (e.g. mark as read) specified feed.

Parameters:

• feed_id (integer) - ID of feed to update
• is_cat (boolean) - true if the specified feed_id is a category
• mode (string) - optional: one of all, 1day, 1week, 2week. defaults to all. since api level 15.

Returns status-message if the operation has been completed.

{"status":"OK"}

getCounters

Required version: version:1.5.0

Returns a list of unread article counts for specified feed groups.

Parameters:

• output_mode (string) - Feed groups to return counters for

Output mode is a character string, comprising several letters (defaults to “flc”):

• f - actual feeds
• l - labels
• c - categories
• t - tags

Several global counters are returned as well, those can’t be disabled with output_mode.

getLabels (since API level 1)

Returns list of configured labels, as an array of label objects:

{"id":2,"caption":"Debian","fg_color":"#e14a00","bg_color":"#ffffff","checked":false},

Before version:1.7.5

Returned id is an internal database id of the label, you can convert it to the valid feed id like this:

feed_id = -11 - label_id

After:

No conversion is necessary.

Parameters:

• article_id (int) - set “checked” to true if specified article id has returned label.

setArticleLabel (since API level 1)

Assigns article_ids to specified label.

Parameters:

• article_ids - comma-separated list of article ids
• label_id (int) - label id, as returned in getLabels
• assign (boolean) - assign or remove label

Note: Up until version:1.15 setArticleLabel() clears the label cache for the specified articles. Make sure to regenerate it (e.g. by calling API method getLabels() for the respecting articles) when you’re using methods which don’t do that by themselves (e.g. getHeadlines()) otherwise getHeadlines() will not return labels for modified articles.

shareToPublished (since API level 4 - version:1.6.0)

Creates an article with specified data in the Published feed.

Parameters:

• title - Article title (string)
• url - Article URL (string)
• content - Article content (string)
• sanitize (bool) - allows inserting HTML if disabled requires API level 20 (default: true)

subscribeToFeed (API level 5 - version:1.7.6)

Subscribes to specified feed, returns a status code. See subscribe_to_feed() in functions.php for details.

Parameters:

• feed_url - Feed URL (string)
• category_id - Category id to place feed into (defaults to 0, Uncategorized) (int)
• login, password - Self explanatory (string)

unsubscribeFeed (API level 5 - version:1.7.6)

Unsubscribes specified feed.

Parameters:

• feed_id - Feed id to unsubscribe from

getFeedTree (API level 5 - version:1.7.6)

• include_empty (bool) - include empty categories

Returns full tree of categories and feeds.

Note: counters for most feeds are not returned with this call for performance reasons.