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 a desktop or a mobile client on Android, iOS, etc...

Protocol

The API use the JSON-RPC 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 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.

Under the web user interface of Miniflux, go to the menu preferences, scroll down until you reach the API section.

You must have these information:

The API username is the same as your login username and the API token is generated automatically during the database creation.

Authentication

The API use the HTTP Basic Authentication scheme described in RFC2617.

Based on the above example, the username is "demo" and the password is the "API token" (swB3/nSo1CB1X2F).

Examples

Example with cURL

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "feed.create", "params": {"url": "http://images.apple.com/main/rss/hotnews/hotnews.rss"}, "id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Success output:

{"jsonrpc":"2.0","id":1,"result":6}

The feed_id is 6.

Error output:

{"jsonrpc":"2.0","id":1,"result":false}

Example with PHP

I developed a very simple JSON-RPC client/server PHP library. Here is an example to fetch all bookmarks.

use JsonRPC\Client;

$client = new Client('https://miniflux.net/demo/jsonrpc.php');
$client->authentication('demo', 'swB3/nSo1CB1X2F');

$result = $client->execute('item.bookmark.list');
print_r($result);

Output:

Array
(
    [0] => Array
        (
            [id] => be1403d8
            [title] => Data Structures for PHP Devs: Heaps
            [updated] => 1374503433
            [url] => http://phpmaster.com/data-structures-3/
            [status] => read
            [site_url] => http://phpmaster.com
            [feed_title] => PHP Master
        )

    [1] => Array
        (
            [id] => 49c2f23c
            [title] => Has Mozilla Lost Its Values?
            [updated] => 1374171372
            [url] => https://www.iab.net/iablog/2013/07/has-mozilla-lost-its-values.html
            [status] => read
            [site_url] => https://lobste.rs/
            [feed_title] => lobste.rs
        )
)

Procedures

feed.list

Get the list of subscriptions.

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "feed.list", "id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result" : [
      { "download_content" : "0",
        "enabled" : "1",
        "etag" : null,
        "feed_url" : "http://www.lemonde.fr/rss/une.xml",
        "id" : "1",
        "last_checked" : null,
        "last_modified" : null,
        "parsing_error" : "0",
        "site_url" : "http://www.lemonde.fr/rss/une.xml",
        "title" : "Le Monde.fr - Actualité à la Une"
      },
      { "download_content" : "1",
        "enabled" : "1",
        "etag" : null,
        "feed_url" : "http://www.futura-sciences.com/rss/actualites.xml",
        "id" : "6",
        "last_checked" : null,
        "last_modified" : null,
        "parsing_error" : "0",
        "site_url" : "http://www.futura-sciences.com",
        "title" : "Les dernières actualités de Futura-Sciences"
      },
      { "download_content" : "0",
        "enabled" : "1",
        "etag" : null,
        "feed_url" : "http://www.mac4ever.com/rss/actu",
        "id" : "2",
        "last_checked" : null,
        "last_modified" : null,
        "parsing_error" : "0",
        "site_url" : "http://www.mac4ever.com/actu",
        "title" : "Mac4Ever.com - Actualité"
      },
      ...
    ]
}

feed.info

Fetch one subscription

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "feed.info", "params": {"feed_id": 1}, "id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result" : [
    {
      "download_content" : "0",
      "enabled" : "1",
      "etag" : null,
      "feed_url" : "http://www.lemonde.fr/rss/une.xml",
      "id" : "1",
      "last_checked" : null,
      "last_modified" : null,
      "parsing_error" : "0",
      "site_url" : "http://www.lemonde.fr/rss/une.xml",
      "title" : "Le Monde.fr - Actualité à la Une"
    }
  ]
}

feed.create

Add a new subscription (synchronous operation).

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "feed.create", "params": {"url": "http://images.apple.com/main/rss/hotnews/hotnews.rss"}, "id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{"jsonrpc":"2.0","id":1,"result":6}

feed.delete

Remove one subscription.

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "feed.delete", "params": {"feed_id": 5}, id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result": true
}

feed.delete_all

Remove all subscriptions.

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "feed.delete_all", "id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result" : true
}

feed.update

Refresh one subscription (synchronous operation).

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "feed.update", "params": {"feed_id": 1}, id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result" : true
}

item.feed.list

Get all items for a specific feed.

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.feed.list", "params": {"feed_id": 1}, id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result" : [
    {
        "bookmark" : "0",
        "content" : "<p>La fermeture de quatre usines affecte 1 250 salariés, soit 30 % des effectifs de la marque en Espagne.</p>",
        "feed_id" : "1",
        "id" : "bcc94722",
        "site_url" : "http://www.lemonde.fr/rss/une.xml",
        "status" : "unread",
        "title" : "Des milliers de manifestants à Madrid contre la fermeture d'usines Coca-Cola",
        "updated" : "1392486765",
        "url" : "http://www.lemonde.fr/europe/article/2014/02/15/des-milliers-de-manifestants-a-madrid-contre-la-fermeture-d-usines-coca-cola_4367428_3214.html#xtor=RSS-3208"
    },
    {
        "bookmark" : "0",
        "content" : "<p>Le Français a passé samedi la barre des 6,16 mètres, dépassant ainsi le saut de l'Ukrainien à 6,15 mètres atteint en 1993.</p>",
        "feed_id" : "1",
        "id" : "c659783b",
        "site_url" : "http://www.lemonde.fr/rss/une.xml",
        "status" : "unread",
        "title" : "Saut à la perche : Lavillenie bat le record du monde de Bubka",
        "updated" : "1392486633",
        "url" : "http://www.lemonde.fr/sport/article/2014/02/15/saut-a-la-perche-lavillenie-bat-le-record-du-monde-de-bubka_4367434_3242.html#xtor=RSS-3208"
    },
    ...
  ]
}

item.feed.count

Count all items for a specific feed.

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.feed.count", "params": {"feed_id": 1}, "id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result" : 25
}

item.bookmark.list

Get all bookmarks.

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.bookmark.list", "id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result" : [
    {
        "bookmark" : "1",
        "content" : "La fermeture de quatre usines affecte 1 250 salariés, soit 30 % des effectifs de la marque en Espagne.",
        "feed_id" : "1",
        "feed_title" : "Le Monde.fr - Actualité à la Une",
        "id" : "bcc94722",
        "site_url" : "http://www.lemonde.fr/rss/une.xml",
        "status" : "unread",
        "title" : "Des milliers de manifestants à Madrid contre la fermeture d'usines Coca-Cola",
        "updated" : "1392486765",
        "url" : "http://www.lemonde.fr/europe/article/2014/02/15/des-milliers-de-manifestants-a-madrid-contre-la-fermeture-d-usines-coca-cola_4367428_3214.html#xtor=RSS-3208"
      },
      ...
  ]
}

item.bookmark.count

Count the number of bookmarks.

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.bookmark.count", "id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result" : 3
}

item.bookmark.create

Add a new bookmark.

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.bookmark.create", "params": {"item_id": "1fd17ad3"}, "id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result" : true
}

item.bookmark.delete

Remove a bookmark.

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.bookmark.delete", "params": {"item_id": "1fd17ad3"}, "id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result" : true
}

item.list_unread

Get all unread items.

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.list_unread", "id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result" : [
      {
        "bookmark" : "0",
        "content" : "La fermeture de quatre usines affecte 1 250 salariés, soit 30 % des effectifs de la marque en Espagne.",
        "feed_id" : "1",
        "feed_title" : "Le Monde.fr - Actualité à la Une",
        "id" : "bcc94722",
        "site_url" : "http://www.lemonde.fr/rss/une.xml",
        "status" : "unread",
        "title" : "Des milliers de manifestants à Madrid contre la fermeture d'usines Coca-Cola",
        "updated" : "1392486765",
        "url" : "http://www.lemonde.fr/europe/article/2014/02/15/des-milliers-de-manifestants-a-madrid-contre-la-fermeture-d-usines-coca-cola_4367428_3214.html#xtor=RSS-3208"
      },
      ...
  ]
}

item.count_unread

Count all unread items.

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.count_unread", "id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result" : 18
}

item.list_read

Get all read items.

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.list_read", "id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result" :
    {
        "bookmark" : "0",
        "content" : "La fermeture de quatre usines affecte 1 250 salariés, soit 30 % des effectifs de la marque en Espagne.",
        "feed_id" : "1",
        "feed_title" : "Le Monde.fr - Actualité à la Une",
        "id" : "bcc94722",
        "site_url" : "http://www.lemonde.fr/rss/une.xml",
        "status" : "read",
        "title" : "Des milliers de manifestants à Madrid contre la fermeture d'usines Coca-Cola",
        "updated" : "1392486765",
        "url" : "http://www.lemonde.fr/europe/article/2014/02/15/des-milliers-de-manifestants-a-madrid-contre-la-fermeture-d-usines-coca-cola_4367428_3214.html#xtor=RSS-3208"
      },
      ...
}

item.count_read

Count all read items.

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.count_read", "id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result" : 254
}

item.info

Fetch one item.

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.info", "params": {"item_id": "bcc94722"}, "id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result" : {
      "author" : "",
      "bookmark" : "1",
      "content" : "La fermeture de quatre usines affecte 1 250 salariés, soit 30 % des effectifs de la marque en Espagne.",
      "feed_id" : "1",
      "id" : "bcc94722",
      "status" : "unread",
      "title" : "Des milliers de manifestants à Madrid contre la fermeture d'usines Coca-Cola",
      "updated" : "1392486765",
      "url" : "http://www.lemonde.fr/europe/article/2014/02/15/des-milliers-de-manifestants-a-madrid-contre-la-fermeture-d-usines-coca-cola_4367428_3214.html#xtor=RSS-3208"
    }
}

item.delete

Remove one item.

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.delete", "params": {"item_id": "bcc94722"}, "id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result" : true
}

item.mark_as_read

Mark an item as read.

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.mark_as_read", "params": {"item_id": "1fd17ad3"}, "id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result" : true
}

item.mark_as_unread

Mark an item as unread.

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.mark_as_read", "params": {"item_id": "1fd17ad3"}, "id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result" : true
}

item.flush

Flush all read items.

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.flush", "id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result" : true
}

item.mark_all_as_read

Mark all unread items as read.

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.mark_all_as_read", "id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result" : true
}

item.set_list_status

Change the status of a list of item id.

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.set_list_status", "params": {"status": "unread", "items": ["1fd17ad3", "bcc94722"]}, "id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result" : true
}

item.get_all

Get all items (unread and read)

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.get_all", "id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result" : [
      {
        "bookmark" : "0",
        "content" : "<p>Le comportement de molécules biologiques importantes est probablement différent dans un milieu ...</p>",
        "feed_id" : "6",
        "feed_title" : "Les dernières actualités de Futura-Sciences",
        "id" : "947c27f1",
        "site_url" : "http://www.futura-sciences.com",
        "status" : "read",
        "title" : "Des bulles de graphène piègent des moélcules sous le microscope",
        "updated" : "1392467820",
        "url" : "http://www.futura-sciences.com/magazines/matiere/infos/actu/d/physique-bulles-graphene-piegent-moelcules-sous-microscope-52264/#xtor=RSS-8"
      },
      ...
    ]
}

item.get_all_status

Get all items status (unread and read)

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.get_all_status", "id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result" : {
      "02043706" : "unread",
      "03b2f912" : "read",
      "087619e5" : "unread",
      "0a05d7f2" : "read",
      "0ab36a48" : "read",
      "0d55fd54" : "read",
      "0f64bd6d" : "read",
      "0fff2adc" : "unread",
      "10fc26ac" : "unread",
      ....
    }
}

item.get_all_since

Get all items since a date (unread and read)

Request:

curl \
-u "demo:swB3/nSo1CB1X2F" \
-d '{"jsonrpc": "2.0", "method": "item.get_all_since", "params": {"timestamp": 1392467820}, "id": 1}' \
https://miniflux.net/demo/jsonrpc.php

Response:

{ "id" : 1,
  "jsonrpc" : "2.0",
  "result" : [
      {
        "bookmark" : "0",
        "content" : "<p>...</p>",
        "feed_id" : "6",
        "feed_title" : "Les dernières actualités de Futura-Sciences",
        "id" : "dccc2a20",
        "site_url" : "http://www.futura-sciences.com",
        "status" : "read",
        "title" : "Curiosity a franchi avec succès la dune de Dingo Gap",
        "updated" : "1392475200",
        "url" : "http://www.futura-sciences.com/magazines/espace/infos/actu/d/astronautique-curiosity-franchi-succes-dune-dingo-gap-52289/#xtor=RSS-8"
      },
      {
        "bookmark" : "0",
        "content" : "<p>...</p>",
        "feed_id" : "6",
        "feed_title" : "Les dernières actualités de Futura-Sciences",
        "id" : "947c27f1",
        "site_url" : "http://www.futura-sciences.com",
        "status" : "read",
        "title" : "Des bulles de graphène piègent des moélcules sous le microscope",
        "updated" : "1392467820",
        "url" : "http://www.futura-sciences.com/magazines/matiere/infos/actu/d/physique-bulles-graphene-piegent-moelcules-sous-microscope-52264/#xtor=RSS-8"
      },
      ...
    ]
}