miniflux

Miniflux API Reference

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 informations by example:

The API username is the same as your login username and the API token is generated automatically during database setup. This token is randomly generated by /dev/urandom.

Authentication

The API use 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).

Example with curl

Here is an example how to add new feed with curl:

From the command line

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 in PHP

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

Fetch all bookmarks

<?php

require '../vendor/JsonRPC/Client.php';

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 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"
          },
          ...
        ]
    }