From 6c5eec7b4d8d36fb8121507c207076806f39440c Mon Sep 17 00:00:00 2001 From: fox Date: Sun, 15 Oct 2017 08:55:16 +0000 Subject: Update page 'ApiReference' --- ApiReference.md | 892 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 450 insertions(+), 442 deletions(-) diff --git a/ApiReference.md b/ApiReference.md index 11124cd..7e784f9 100644 --- a/ApiReference.md +++ b/ApiReference.md @@ -1,442 +1,450 @@ -JSON API Reference -================== - -Supported since version:1.4.0. - -The API is pluggable, plugins can use host -add\_api\_method() to add custom API calls (see -classes/pluginhost.php for details). - -Summary -------- - -The 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. - -```bash -curl -d '{"sid":"your-session-id","op":"getVersion"}' http://example.dom/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. - -Testing API calls (using curl) ------------------------------- - -```bash -curl -d '{"op":"login","user":"you","password":"xxx"}' http://example.dom/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 -------------- - -### 1.5.0 and above - -All API methods return JSON data like this: - -```json -{"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. - -```json -{"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. - -```json -{"version":"1.4.0"} -``` - -### login - -Parameters: - -- user (string) -- password (string) - -Returns client session ID. - -```json -{"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. - -### 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. - -```json -{"status":false} -``` - -### getUnread - -Returns an integer value of currently unread articles. - -```json -{"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) - only output articles for this feed -- 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: - -```json -{"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: - -```json -{"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) - -### 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. - -```json -{"status":"OK"} -``` - -### getPref - -Returns preference value of specified key. - -- pref\_name (string) - preference key to return value of - -```json -{"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 - -Returns status-message if the operation has been completed. - -```json -{"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: - -```json -{"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) - -### 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. +JSON API Reference +================== + +Supported since version:1.4.0. + +The API is pluggable, plugins can use host +add\_api\_method() to add custom API calls (see +classes/pluginhost.php for details). + +Summary +------- + +The 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. + +```bash +curl -d '{"sid":"your-session-id","op":"getVersion"}' http://example.dom/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. + +Boolean values +--------- + +For boolean parameters the expected syntax is: + +- string literal "true" meaning true +- anything else meaning false + +Testing API calls (using curl) +------------------------------ + +```bash +curl -d '{"op":"login","user":"you","password":"xxx"}' http://example.dom/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 +------------- + +### 1.5.0 and above + +All API methods return JSON data like this: + +```json +{"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. + +```json +{"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. + +```json +{"version":"1.4.0"} +``` + +### login + +Parameters: + +- user (string) +- password (string) + +Returns client session ID. + +```json +{"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. + +### 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. + +```json +{"status":false} +``` + +### getUnread + +Returns an integer value of currently unread articles. + +```json +{"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) - only output articles for this feed +- 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: + +```json +{"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: + +```json +{"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) + +### 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. + +```json +{"status":"OK"} +``` + +### getPref + +Returns preference value of specified key. + +- pref\_name (string) - preference key to return value of + +```json +{"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 + +Returns status-message if the operation has been completed. + +```json +{"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: + +```json +{"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) + +### 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. -- cgit v1.2.3