Json-RPC API ============ The Miniflux API is a way to interact programatically with your feeds, items, bookmarks and other data. Developers can use this API to make desktop or mobile clients. Protocol -------- The API use the [JSON-RPC](http://www.jsonrpc.org/) protocol because it's very simple. JSON-RPC is a remote procedure call protocol encoded in JSON. Almost the same thing as XML-RPC but with JSON. We use the [version 2](http://www.jsonrpc.org/specification) of the protocol. You must call the API with a **POST** HTTP request. Credentials ----------- The first step is to retrieve API credentials and the URL endpoint. They are available in **preferences > api**. You must have these information: - API endpoint: `https://your_domain.tld/jsonrpc.php` - API username: `username` - API token: `XXXXXX` (random token) The API username is the same as your login username and the API token is generated automatically. Authentication -------------- The API use the HTTP Basic Authentication scheme described in [RFC2617](http://www.ietf.org/rfc/rfc2617.txt). Examples -------- ### Example with cURL ```bash curl \ -u "username:password" \ -d '{"jsonrpc": "2.0", "method": "createFeed", "params": {"url": "http://images.apple.com/main/rss/hotnews/hotnews.rss"}, "id": 1}' \ https://localhost/jsonrpc.php ``` Success response: ```json { "jsonrpc": "2.0", "id": 1, "result": 6 } ``` The `feed_id` is 6. Error response: ```json { "jsonrpc": "2.0", "id": 1, "result": false } ``` Procedures ---------- ### getVersion - Purpose: **Get application version** - Parameters: none - Result on success: **version** Request example: ```json { "jsonrpc": "2.0", "method": "getVersion", "id": 304873928 } ``` Response example: ```json { "jsonrpc": "2.0", "result": "master", "id": 304873928 } ``` ### createUser - Purpose: **Create new user** (accessible only by administrators) - Parameters: - **username** (string) - **password** (string) - **is_admin** (boolean, optional) - Result on success: **user_id** - Result on failure: **false** Request example: ```json { "jsonrpc": "2.0", "method": "createUser", "id": 97055228, "params": { "username": "api_test", "password": "test123" } } ``` Response example: ```json { "jsonrpc": "2.0", "result": 2, "id": 97055228 } ``` ### removeUser - Purpose: **Remove a user** (accessible only by administrators) - Parameters: - **user_id** (integer) - Result on success: **true** - Result on failure: **false** Request example: ```json { "jsonrpc": "2.0", "method": "removeUser", "id": 2109613284, "params": [ 3 ] } ``` Response example: ```json { "jsonrpc": "2.0", "result": true, "id": 2109613284 } ``` ### getUserByUsername - Purpose: **Get user** (accessible only by administrators) - Parameters: - **username** (string) - Result on success: **user object** - Result on failure: **false|null** Request example: ```json { "jsonrpc": "2.0", "method": "getUserByUsername", "id": 1456121566, "params": [ "api_test" ] } ``` Response example: ```json { "jsonrpc": "2.0", "result": { "id": "2", "username": "api_test", "password": "$2y$10$FOzlRrLoHRI3Xj4YuV8z5O1jI4CKda61reX.g.Fm4ctYMijpOhTGu", "is_admin": "0", "last_login": null, "api_token": "398c293808aaed9cf2be45cf8e4fa303be5cdbbf6c4a55fece6b585c6a6c", "bookmarklet_token": "965e9049138e4e78c398dc369fc4ec529226055c6fd77a3d4119bc3a1b5e", "cronjob_token": "a4f6e1f5fd655c7365ebddcaf1dfd5782669186ed85a788d8e52b8230399", "feed_token": "62ed60fb75616d3f81a938206449a20fe30f0bf9db9bf0b93259821f5938", "fever_token": "59253f797b3b1885e31449fa97e9348c127e4e10e4eea959a2555c1b3a1e", "fever_api_key": "5e379736d05847f87c37a7d2f57ed234" }, "id": 1456121566 } ``` ### getFeeds - Purpose: **Get all subscriptions** - Parameters: none - Result on success: **list of feed objects** - Result on failure: **false** Request example: ```json { "jsonrpc": "2.0", "method": "getFeeds", "id": 1189414818 } ``` Response example: ```json { "jsonrpc": "2.0", "result": [ { "id": "1", "user_id": "1", "feed_url": "https:\/\/miniflux.net\/feed", "site_url": "https:\/\/miniflux.net\/", "title": "Miniflux", "last_checked": "1483053994", "last_modified": "Sun, 31 Jul 2016 16:54:32 GMT", "etag": "W\/\"bdc7a83fd61620b778da350991501757\"", "enabled": "1", "download_content": "0", "parsing_error": "0", "rtl": "0", "cloak_referrer": "0", "parsing_error_message": null, "expiration": "1483226794", "groups": [ { "id": "1", "title": "open source software" } ] } ], "id": 1189414818 } ``` ### getFeed - Purpose: **Get one subscription** - Parameters: - **feed_id** (integer) - Result on success: **feed object** - Result on failure: **null** Request example: ```json { "jsonrpc": "2.0", "method": "getFeed", "id": 912101777, "params": [ 1 ] } ``` Response example: ```json { "jsonrpc": "2.0", "result": { "id": "1", "user_id": "1", "feed_url": "https:\/\/miniflux.net\/feed", "site_url": "https:\/\/miniflux.net\/", "title": "Miniflux", "last_checked": "1483053994", "last_modified": "Sun, 31 Jul 2016 16:54:32 GMT", "etag": "W\/\"bdc7a83fd61620b778da350991501757\"", "enabled": "1", "download_content": "0", "parsing_error": "0", "rtl": "0", "cloak_referrer": "0", "parsing_error_message": null, "expiration": "1483226794", "groups": [ { "id": "1", "title": "open source software" } ] }, "id": 912101777 } ``` ### createFeed - Purpose: **Add new subscription** - Parameters: - **url** (string) - **download_content** (boolean, optional) - **rtl** (boolean, optional) - **group_name** (string, optional) - Result on success: **feed_id** - Result on failure: **false** Request example: ```json { "jsonrpc": "2.0", "method": "createFeed", "id": 315813488, "params": { "url": "https://miniflux.net/feed", "group_name": "open source software" } } ``` Response example: ```json { "jsonrpc": "2.0", "result": 1, "id": 315813488 } ``` ### removeFeed - Purpose: **Create new user** - Parameters: - **feed_id** (integer) - Result on success: **true** - Result on failure: **false** Request example: ```json { "jsonrpc": "2.0", "method": "removeFeed", "id": 1793804609, "params": [ 1 ] } ``` Response example: ```json { "jsonrpc": "2.0", "result": true, "id": 1793804609 } ``` ### refreshFeed - Purpose: **Refresh subscription** (synchronous call) - Parameters: - **feed_id** (integer) - Result on success: **true** - Result on failure: **false** Request example: ```json { "jsonrpc": "2.0", "method": "refreshFeed", "id": 181234449, "params": [ 1 ] } ``` Response example: ```json { "jsonrpc": "2.0", "result": true, "id": 181234449 } ``` ### getItems - Purpose: **Get list o items** - Parameters: - **since_id** (integer, optional) Returns only feeds from this item id - **item_ids** ([]integer, optional) Returns only items in this list - **limit** (integer, optional, default=50) Change number of items returned - Result on success: **list of item objects** - Result on failure: **false** Request example: ```json { "jsonrpc": "2.0", "method": "getItems", "id": 84429548, "params": { "since_id": 2 } } ``` Response example: ```json { "jsonrpc": "2.0", "result": [ { "id": "3", "checksum": "7f4b791f", "title": "Miniflux 1.1.8 released", "updated": "1442016000", "url": "https:\/\/miniflux.net\/news\/version-1.1.8", "enclosure_url": "", "enclosure_type": "", "bookmark": "0", "feed_id": "1", "status": "unread", "content": "