1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
|
JSON API Reference
==================
Supported since version:1.4.0.
The API is pluggable, plugins can use host
<code>add\_api\_method()</code> to add custom API calls (see
<code>classes/pluginhost.php</code> 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 <code>"true"</code> 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:
<code>{"error":"NOT_LOGGED_IN"}</code>
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:
<code>error: "API_DISABLED"</code>
- If specified username and password are incorrect:
<code>error: "LOGIN_ERROR"</code>
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
<code>api\_level</code> integer, you can use that instead of calling
getApiLevel after login.
### logout
Closes your login session. Returns either status-message <code>{"status":"OK"}</code> or an error (e.g. <code>{"error":"NOT_LOGGED_IN"}</code>)
### 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 **<span class="10 api"></span>** (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:
<code>?article\_ids=X,Y&mode=0&field=2</code>
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:
<code>feed\_id = \-11 - label\_id</code>
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.
|