API Reference

Table of Contents:

Authentication
Clients
- Golang Client
- Python Client
API Endpoints

Authentication ¶

The API supports two authentication mechanisms:

HTTP Basic authentication with the account username/password.
Per-application API keys (since version 2.0.21) -> preferred method.

To generate a new API token, got to “Settings > API Keys > Create a new API key”.

HTTP Basic Authentication Example

curl -u your-miniflux-username https://miniflux.example.org/v1/me

API Token Authentication Example

Miniflux uses the HTTP header X-Auth-Token for API token authentication.

curl -H "X-Auth-Token: your-token" https://miniflux.example.org/v1/me

Clients ¶

There are two official API clients, one written in Go and another one written in Python.

Golang Client ¶

Repository: https://github.com/miniflux/v2/tree/main/client
Reference: https://pkg.go.dev/miniflux.app/v2/client

Installation:

go get -u miniflux.app/client

Usage Example:

package main

import (
    "fmt"

    miniflux "miniflux.app/client"
)

func main() {
    // Authentication using username/password.
    client := miniflux.New("https://miniflux.example.org", "admin", "secret")

    // Authentication using API token.
    client := miniflux.New("https://miniflux.example.org", "My secret token")

    // Fetch all feeds.
    feeds, err := client.Feeds()
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(feeds)
}

Python Client ¶

Repository: https://github.com/miniflux/python-client
PyPi: https://pypi.org/project/miniflux/

Installation:

pip install miniflux

Usage example:

import miniflux

# Authentication using username/password
client = miniflux.Client("https://miniflux.example.org", "my_username", "my_secret_password")

# Authentication using an API token
client = miniflux.Client("https://miniflux.example.org", api_key="My Secret Token")

# Get all feeds
feeds = client.get_feeds()

# Refresh a feed
client.refresh_feed(123)

# Discover subscriptions from a website
subscriptions = client.discover("https://example.org")

# Create a new feed, with a personalized user agent and with the crawler enabled
feed_id = client.create_feed("http://example.org/feed.xml", 42, crawler=True, user_agent="GoogleBot")

# Fetch 10 starred entries
entries = client.get_entries(starred=True, limit=10)

# Fetch last 5 feed entries
feed_entries = client.get_feed_entries(123, direction='desc', order='published_at', limit=5)

# Update a feed category
client.update_feed(123, category_id=456)

API Endpoints ¶

Status Codes ¶

200: Everything is OK
201: Resource created/modified
204: Resource removed/modified
400: Bad request
401: Unauthorized (bad username/password)
403: Forbidden (access not allowed)
500: Internal server error

Error Response ¶

{
    "error_message": "Some error"
}

Discover Subscriptions ¶

Request:

POST /v1/discover
Content-Type: application/json

{
    "url": "http://example.org"
}

Response:

[
    {
        "url": "http://example.org/feed.atom",
        "title": "Atom Feed",
        "type": "atom"
    },
    {
        "url": "http://example.org/feed.rss",
        "title": "RSS Feed",
        "type": "rss"
    }
]

Optional fields:

username: Feed username (string)
password: Feed password (string)
user_agent: Custom user agent (string)
fetch_via_proxy (boolean)

Flush History ¶

Request:

PUT /v1/flush-history

Note that DELETE is also supported.

Returns a 202 Accepted status code for success.

This API endpoint is available since Miniflux v2.0.49.

Get Feeds ¶

Request:

GET /v1/feeds

Response:

[
    {
        "id": 42,
        "user_id": 123,
        "title": "Example Feed",
        "site_url": "http://example.org",
        "feed_url": "http://example.org/feed.atom",
        "checked_at": "2017-12-22T21:06:03.133839-05:00",
        "etag_header": "KyLxEflwnTGF5ecaiqZ2G0TxBCc",
        "last_modified_header": "Sat, 23 Dec 2017 01:04:21 GMT",
        "parsing_error_message": "",
        "parsing_error_count": 0,
        "scraper_rules": "",
        "rewrite_rules": "",
        "crawler": false,
        "blocklist_rules": "",
        "keeplist_rules": "",
        "user_agent": "",
        "username": "",
        "password": "",
        "disabled": false,
        "ignore_http_cache": false,
        "fetch_via_proxy": false,
        "category": {
            "id": 793,
            "user_id": 123,
            "title": "Some category"
        },
        "icon": {
            "feed_id": 42,
            "icon_id": 84
        }
    }
]

Notes:

icon is null when the feed doesn’t have any favicon.

Get Category Feeds ¶

Request:

GET /v1/categories/40/feeds

Response:

[
    {
        "id": 42,
        "user_id": 123,
        "title": "Example Feed",
        "site_url": "http://example.org",
        "feed_url": "http://example.org/feed.atom",
        "checked_at": "2017-12-22T21:06:03.133839-05:00",
        "etag_header": "KyLxEflwnTGF5ecaiqZ2G0TxBCc",
        "last_modified_header": "Sat, 23 Dec 2017 01:04:21 GMT",
        "parsing_error_message": "",
        "parsing_error_count": 0,
        "scraper_rules": "",
        "rewrite_rules": "",
        "crawler": false,
        "blocklist_rules": "",
        "keeplist_rules": "",
        "user_agent": "",
        "username": "",
        "password": "",
        "disabled": false,
        "ignore_http_cache": false,
        "fetch_via_proxy": false,
        "category": {
            "id": 40,
            "user_id": 123,
            "title": "Some category"
        },
        "icon": {
            "feed_id": 42,
            "icon_id": 84
        }
    }
]

This API endpoint is available since Miniflux v2.0.29.

Get Feed ¶

Request:

GET /v1/feeds/42

Response:

{
    "id": 42,
    "user_id": 123,
    "title": "Example Feed",
    "site_url": "http://example.org",
    "feed_url": "http://example.org/feed.atom",
    "checked_at": "2017-12-22T21:06:03.133839-05:00",
    "etag_header": "KyLxEflwnTGF5ecaiqZ2G0TxBCc",
    "last_modified_header": "Sat, 23 Dec 2017 01:04:21 GMT",
    "parsing_error_message": "",
    "parsing_error_count": 0,
    "scraper_rules": "",
    "rewrite_rules": "",
    "crawler": false,
    "blocklist_rules": "",
    "keeplist_rules": "",
    "user_agent": "",
    "username": "",
    "password": "",
    "disabled": false,
    "ignore_http_cache": false,
    "fetch_via_proxy": false,
    "category": {
        "id": 793,
        "user_id": 123,
        "title": "Some category"
    },
    "icon": {
        "feed_id": 42,
        "icon_id": 84
    }
}

Notes:

icon is null when the feed doesn’t have any favicon.

Get Feed Icon By Feed ID¶

Request:

GET /v1/feeds/{feedID}/icon

Response:

{
    "id": 262,
    "data": "image/png;base64,iVBORw0KGgoAAA....",
    "mime_type": "image/png"
}

If the feed doesn’t have any favicon, a 404 is returned.

Get Feed Icon By Icon ID¶

Request:

GET /v1/icons/{iconID}

Response:

{
    "id": 262,
    "data": "image/png;base64,iVBORw0KGgoAAA....",
    "mime_type": "image/png"
}

This API endpoint is available since Miniflux v2.0.49.

Create Feed ¶

Request:

POST /v1/feeds
Content-Type: application/json

{
    "feed_url": "http://example.org/feed.atom",
    "category_id": 22
}

Response:

{
    "feed_id": 262,
}

Required fields:

feed_url: Feed URL (string)
category_id: Category ID (int, optional since Miniflux >= 2.0.49)

Optional fields:

username: Feed username (string)
password: Feed password (string)
crawler: Enable/Disable scraper (boolean)
user_agent: Custom user agent for the feed (string)
scraper_rules: List of scraper rules (string) - Miniflux >= 2.0.19
rewrite_rules: List of rewrite rules (string) - Miniflux >= 2.0.19
blocklist_rules (string) - Miniflux >= 2.0.27
keeplist_rules (string) - Miniflux >= 2.0.27
disabled (boolean) - Miniflux >= 2.0.27
ignore_http_cache (boolean) - Miniflux >= 2.0.27
fetch_via_proxy (boolean) - Miniflux >= 2.0.27

Update Feed ¶

Request:

PUT /v1/feeds/42
Content-Type: application/json

{
    "title": "New Feed Title",
    "category_id": 22
}

Response:

{
    "id": 42,
    "user_id": 123,
    "title": "New Feed Title",
    "site_url": "http://example.org",
    "feed_url": "http://example.org/feed.atom",
    "checked_at": "2017-12-22T21:06:03.133839-05:00",
    "etag_header": "KyLxEflwnTGF5ecaiqZ2G0TxBCc",
    "last_modified_header": "Sat, 23 Dec 2017 01:04:21 GMT",
    "parsing_error_message": "",
    "parsing_error_count": 0,
    "scraper_rules": "",
    "rewrite_rules": "",
    "crawler": false,
    "blocklist_rules": "",
    "keeplist_rules": "",
    "user_agent": "",
    "username": "",
    "password": "",
    "disabled": false,
    "ignore_http_cache": false,
    "fetch_via_proxy": false,
    "category": {
        "id": 22,
        "user_id": 123,
        "title": "Another category"
    },
    "icon": {
        "feed_id": 42,
        "icon_id": 84
    }
}

Available fields:

feed_url (string)
site_url (string)
title (string)
category_id (int)
scraper_rules (string)
rewrite_rules (string)
blocklist_rules (string)
keeplist_rules (string)
crawler (boolean)
user_agent: Custom user agent for the feed (string)
username (string)
password (string)
disabled (boolean)
ignore_http_cache (boolean)
fetch_via_proxy (boolean)

Refresh Feed ¶

Request:

PUT /v1/feeds/42/refresh

Returns 204 status code for success.
This API call is synchronous and can takes hundred of milliseconds.

Refresh all Feeds ¶

Request:

PUT /v1/feeds/refresh

Returns 204 status code for success.
Feeds are refreshed in a background process.
Available since Miniflux 2.0.21

Remove Feed ¶

Request:

DELETE /v1/feeds/42

Get Feed Entry ¶

Request:

GET /v1/feeds/42/entries/888

Response:

{
    "id": 888,
    "user_id": 123,
    "feed_id": 42,
    "title": "Entry Title",
    "url": "http://example.org/article.html",
    "comments_url": "",
    "author": "Foobar",
    "content": "<p>HTML contents</p>",
    "hash": "29f99e4074cdacca1766f47697d03c66070ef6a14770a1fd5a867483c207a1bb",
    "published_at": "2016-12-12T16:15:19Z",
    "created_at": "2016-12-27T16:15:19Z",
    "status": "unread",
    "share_code": "",
    "starred": false,
    "reading_time": 1,
    "enclosures": null,
    "feed": {
        "id": 42,
        "user_id": 123,
        "title": "New Feed Title",
        "site_url": "http://example.org",
        "feed_url": "http://example.org/feed.atom",
        "checked_at": "2017-12-22T21:06:03.133839-05:00",
        "etag_header": "KyLxEflwnTGF5ecaiqZ2G0TxBCc",
        "last_modified_header": "Sat, 23 Dec 2017 01:04:21 GMT",
        "parsing_error_message": "",
        "parsing_error_count": 0,
        "scraper_rules": "",
        "rewrite_rules": "",
        "crawler": false,
        "blocklist_rules": "",
        "keeplist_rules": "",
        "user_agent": "",
        "username": "",
        "password": "",
        "disabled": false,
        "ignore_http_cache": false,
        "fetch_via_proxy": false,
        "category": {
            "id": 22,
            "user_id": 123,
            "title": "Another category"
        },
        "icon": {
            "feed_id": 42,
            "icon_id": 84
        }
    }
}

Get Entry ¶

Request:

GET /v1/entries/888

Response:

{
    "id": 888,
    "user_id": 123,
    "feed_id": 42,
    "title": "Entry Title",
    "url": "http://example.org/article.html",
    "comments_url": "",
    "author": "Foobar",
    "content": "<p>HTML contents</p>",
    "hash": "29f99e4074cdacca1766f47697d03c66070ef6a14770a1fd5a867483c207a1bb",
    "published_at": "2016-12-12T16:15:19Z",
    "created_at": "2016-12-27T16:15:19Z",
    "status": "unread",
    "share_code": "",
    "starred": false,
    "reading_time": 1,
    "enclosures": null,
    "feed": {
        "id": 42,
        "user_id": 123,
        "title": "New Feed Title",
        "site_url": "http://example.org",
        "feed_url": "http://example.org/feed.atom",
        "checked_at": "2017-12-22T21:06:03.133839-05:00",
        "etag_header": "KyLxEflwnTGF5ecaiqZ2G0TxBCc",
        "last_modified_header": "Sat, 23 Dec 2017 01:04:21 GMT",
        "parsing_error_message": "",
        "parsing_error_count": 0,
        "scraper_rules": "",
        "rewrite_rules": "",
        "crawler": false,
        "blocklist_rules": "",
        "keeplist_rules": "",
        "user_agent": "",
        "username": "",
        "password": "",
        "disabled": false,
        "ignore_http_cache": false,
        "fetch_via_proxy": false,
        "category": {
            "id": 22,
            "user_id": 123,
            "title": "Another category"
        },
        "icon": {
            "feed_id": 42,
            "icon_id": 84
        }
    }
}

Update Entry ¶

Both fields title and content are optional.

Request:

PUT /v1/entries/{entryID}

{
    "title": "New title",
    "content": "Some text"
}

Response:

{
  "id": 1790,
  "user_id": 1,
  "feed_id": 21,
  "status": "unread",
  "hash": "22a6795131770d9577c91c7816e7c05f78586fc82e8ad0881bce69155f63edb6",
  "title": "New title",
  "url": "https://miniflux.app/releases/1.0.1.html",
  "comments_url": "",
  "published_at": "2013-03-20T00:00:00Z",
  "created_at": "2023-10-07T03:52:50.013556Z",
  "changed_at": "2023-10-07T03:52:50.013556Z",
  "content": "Some text",
  "author": "Frédéric Guillot",
  "share_code": "",
  "starred": false,
  "reading_time": 1,
  "enclosures": [],
  "feed": {
    "id": 21,
    "user_id": 1,
    "feed_url": "https://miniflux.app/feed.xml",
    "site_url": "https://miniflux.app",
    "title": "Miniflux",
    "checked_at": "2023-10-08T23:56:44.853427Z",
    "next_check_at": "0001-01-01T00:00:00Z",
    "etag_header": "",
    "last_modified_header": "",
    "parsing_error_message": "",
    "parsing_error_count": 0,
    "scraper_rules": "",
    "rewrite_rules": "",
    "crawler": false,
    "blocklist_rules": "",
    "keeplist_rules": "",
    "urlrewrite_rules": "",
    "user_agent": "",
    "cookie": "",
    "username": "",
    "password": "",
    "disabled": false,
    "no_media_player": false,
    "ignore_http_cache": false,
    "allow_self_signed_certificates": false,
    "fetch_via_proxy": false,
    "category": {
      "id": 2,
      "title": "000",
      "user_id": 1,
      "hide_globally": false
    },
    "icon": {
      "feed_id": 21,
      "icon_id": 11
    },
    "hide_globally": false,
    "apprise_service_urls": ""
  },
  "tags": []
}

Returns a 201 Created status code for success.

This API endpoint is available since Miniflux v2.0.49.

Save entry to third-party services ¶

Request:

POST /v1/entries/{entryID}/save

Response:

Returns a 202 Accepted status code for success.

Fetch original article ¶

Request:

GET /v1/entries/{entryID}/fetch-content

Response:

{"content": "html content"}

This API endpoint is available since Miniflux v2.0.36.

Get Category Entries ¶

Request:

GET /v1/categories/22/entries?limit=1&order=id&direction=asc

Available filters:

status: Entry status (read, unread or removed), this option can be repeated to filter by multiple statuses (version >= 2.0.24)
offset
limit
order: “id”, “status”, “published_at”, “category_title”, “category_id”
direction: “asc” or “desc”
before (unix timestamp, available since Miniflux 2.0.9)
after (unix timestamp, available since Miniflux 2.0.9)
published_before (unix timestamp, available since Miniflux 2.0.49)
published_after (unix timestamp, available since Miniflux 2.0.49)
changed_before (unix timestamp, available since Miniflux 2.0.49)
changed_after (unix timestamp, available since Miniflux 2.0.49)
before_entry_id (int64, available since Miniflux 2.0.9)
after_entry_id (int64, available since Miniflux 2.0.9)
starred (boolean, available since Miniflux 2.0.9)
search: search query (text, available since Miniflux 2.0.10)
category_id: filter by category (int, available since Miniflux 2.0.19)

Response:

{
    "total": 10,
    "entries": [
        {
            "id": 888,
            "user_id": 123,
            "feed_id": 42,
            "title": "Entry Title",
            "url": "http://example.org/article.html",
            "comments_url": "",
            "author": "Foobar",
            "content": "<p>HTML contents</p>",
            "hash": "29f99e4074cdacca1766f47697d03c66070ef6a14770a1fd5a867483c207a1bb",
            "published_at": "2016-12-12T16:15:19Z",
            "created_at": "2016-12-27T16:15:19Z",
            "status": "unread",
            "share_code": "",
            "starred": false,
            "reading_time": 1,
            "enclosures": null,
            "feed": {
                "id": 42,
                "user_id": 123,
                "title": "New Feed Title",
                "site_url": "http://example.org",
                "feed_url": "http://example.org/feed.atom",
                "checked_at": "2017-12-22T21:06:03.133839-05:00",
                "etag_header": "KyLxEflwnTGF5ecaiqZ2G0TxBCc",
                "last_modified_header": "Sat, 23 Dec 2017 01:04:21 GMT",
                "parsing_error_message": "",
                "parsing_error_count": 0,
                "scraper_rules": "",
                "rewrite_rules": "",
                "crawler": false,
                "blocklist_rules": "",
                "keeplist_rules": "",
                "user_agent": "",
                "username": "",
                "password": "",
                "disabled": false,
                "ignore_http_cache": false,
                "fetch_via_proxy": false,
                "category": {
                    "id": 22,
                    "user_id": 123,
                    "title": "Another category"
                },
                "icon": {
                    "feed_id": 42,
                    "icon_id": 84
                }
            }
        }
    ]

Get Feed Entries ¶

Request:

GET /v1/feeds/42/entries?limit=1&order=id&direction=asc

Available filters:

status: Entry status (read, unread or removed), this option can be repeated to filter by multiple statuses (version >= 2.0.24)
offset
limit
order: “id”, “status”, “published_at”, “category_title”, “category_id”
direction: “asc” or “desc”
before (unix timestamp, available since Miniflux 2.0.9)
after (unix timestamp, available since Miniflux 2.0.9)
published_before (unix timestamp, available since Miniflux 2.0.49)
published_after (unix timestamp, available since Miniflux 2.0.49)
changed_before (unix timestamp, available since Miniflux 2.0.49)
changed_after (unix timestamp, available since Miniflux 2.0.49)
before_entry_id (int64, available since Miniflux 2.0.9)
after_entry_id (int64, available since Miniflux 2.0.9)
starred (boolean, available since Miniflux 2.0.9)
search: search query (text, available since Miniflux 2.0.10)
category_id: filter by category (int, available since Miniflux 2.0.19)

Response:

{
    "total": 10,
    "entries": [
        {
            "id": 888,
            "user_id": 123,
            "feed_id": 42,
            "title": "Entry Title",
            "url": "http://example.org/article.html",
            "comments_url": "",
            "author": "Foobar",
            "content": "<p>HTML contents</p>",
            "hash": "29f99e4074cdacca1766f47697d03c66070ef6a14770a1fd5a867483c207a1bb",
            "published_at": "2016-12-12T16:15:19Z",
            "created_at": "2016-12-27T16:15:19Z",
            "status": "unread",
            "share_code": "",
            "starred": false,
            "reading_time": 1,
            "enclosures": null,
            "feed": {
                "id": 42,
                "user_id": 123,
                "title": "New Feed Title",
                "site_url": "http://example.org",
                "feed_url": "http://example.org/feed.atom",
                "checked_at": "2017-12-22T21:06:03.133839-05:00",
                "etag_header": "KyLxEflwnTGF5ecaiqZ2G0TxBCc",
                "last_modified_header": "Sat, 23 Dec 2017 01:04:21 GMT",
                "parsing_error_message": "",
                "parsing_error_count": 0,
                "scraper_rules": "",
                "rewrite_rules": "",
                "crawler": false,
                "blocklist_rules": "",
                "keeplist_rules": "",
                "user_agent": "",
                "username": "",
                "password": "",
                "disabled": false,
                "ignore_http_cache": false,
                "fetch_via_proxy": false,
                "category": {
                    "id": 22,
                    "user_id": 123,
                    "title": "Another category"
                },
                "icon": {
                    "feed_id": 42,
                    "icon_id": 84
                }
            }
        }
    ]

Mark Feed Entries as Read ¶

Request:

PUT /v1/feeds/123/mark-all-as-read

Returns 204 Not Content status code for success.

This API endpoint is available since Miniflux v2.0.26.

Get Entries ¶

Request:

GET /v1/entries?status=unread&direction=desc

Available filters:

status: Entry status (read, unread or removed), this option can be repeated to filter by multiple statuses (version >= 2.0.24)
offset
limit
order: “id”, “status”, “published_at”, “category_title”, “category_id”
direction: “asc” or “desc”
before (unix timestamp, available since Miniflux 2.0.9)
after (unix timestamp, available since Miniflux 2.0.9)
published_before (unix timestamp, available since Miniflux 2.0.49)
published_after (unix timestamp, available since Miniflux 2.0.49)
changed_before (unix timestamp, available since Miniflux 2.0.49)
changed_after (unix timestamp, available since Miniflux 2.0.49)
before_entry_id (int64, available since Miniflux 2.0.9)
after_entry_id (int64, available since Miniflux 2.0.9)
starred (boolean, available since Miniflux 2.0.9)
search: search query (text, available since Miniflux 2.0.10)
category_id: filter by category (int, available since Miniflux 2.0.24)

Response:

{
    "total": 10,
    "entries": [
        {
            "id": 888,
            "user_id": 123,
            "feed_id": 42,
            "title": "Entry Title",
            "url": "http://example.org/article.html",
            "comments_url": "",
            "author": "Foobar",
            "content": "<p>HTML contents</p>",
            "hash": "29f99e4074cdacca1766f47697d03c66070ef6a14770a1fd5a867483c207a1bb",
            "published_at": "2016-12-12T16:15:19Z",
            "created_at": "2016-12-27T16:15:19Z",
            "status": "unread",
            "share_code": "",
            "starred": false,
            "reading_time": 1,
            "enclosures": null,
            "feed": {
                "id": 42,
                "user_id": 123,
                "title": "New Feed Title",
                "site_url": "http://example.org",
                "feed_url": "http://example.org/feed.atom",
                "checked_at": "2017-12-22T21:06:03.133839-05:00",
                "etag_header": "KyLxEflwnTGF5ecaiqZ2G0TxBCc",
                "last_modified_header": "Sat, 23 Dec 2017 01:04:21 GMT",
                "parsing_error_message": "",
                "parsing_error_count": 0,
                "scraper_rules": "",
                "rewrite_rules": "",
                "crawler": false,
                "blocklist_rules": "",
                "keeplist_rules": "",
                "user_agent": "",
                "username": "",
                "password": "",
                "disabled": false,
                "ignore_http_cache": false,
                "fetch_via_proxy": false,
                "category": {
                    "id": 22,
                    "user_id": 123,
                    "title": "Another category"
                },
                "icon": {
                    "feed_id": 42,
                    "icon_id": 84
                }
            }
        }
    ]

Update Entries ¶

Request:

PUT /v1/entries
Content-Type: application/json

{
    "entry_ids": [1234, 4567],
    "status": "read"
}

Returns 204 status code for success.

Toggle Entry Bookmark ¶

Request:

PUT /v1/entries/1234/bookmark

Returns 204 status code for success.

Get Enclosure ¶

Request:

GET /v1/enclosures/{enclosureID}

Response:

{
  "id": 278,
  "user_id": 1,
  "entry_id": 195,
  "url": "https://example.org/file",
  "mime_type": "application/octet-stream",
  "size": 0,
  "media_progression": 0
}

This API endpoint is available since Miniflux v2.2.0.

Update Enclosure ¶

Request:

PUT /v1/enclosures/{enclosureID}

{
    "media_progression": 42
}

Returns 204 status code for success.

This API endpoint is available since Miniflux v2.2.0.

Get Categories ¶

Request:

GET /v1/categories

Response:

[
    {"title": "All", "user_id": 267, "id": 792},
    {"title": "Engineering Blogs", "user_id": 267, "id": 793}
]

Create Category ¶

Request:

POST /v1/categories
Content-Type: application/json

{
    "title": "My category"
}

Response:

{
    "id": 802,
    "user_id": 267,
    "title": "My category"
}

Update Category ¶

Request:

PUT /v1/categories/802
Content-Type: application/json

{
    "title": "My new title"
}

Response:

{
    "id": 802,
    "user_id": 267,
    "title": "My new title"
}

Refresh Category Feeds¶

Request:

PUT /v1/categories/123/refresh

Returns 204 status code for success.
Category feeds are refreshed in a background process.

This API endpoint is available since Miniflux v2.0.42.

Delete Category ¶

Request:

DELETE /v1/categories/802

Returns a 204 status code when successful.

Mark Category Entries as Read ¶

Request:

PUT /v1/categories/123/mark-all-as-read

Returns 204 Not Content status code for success.

This API endpoint is available since Miniflux v2.0.26.

OPML Export ¶

Request:

GET /v1/export

The response is a XML document (OPML file).

This API call is available since Miniflux v2.0.1.

OPML Import ¶

Request:

POST /v1/import

XML data

The body is your OPML file (XML).
Returns 201 Created if imported successfully.

Response:

{
  "message": "Feeds imported successfully"
}

This API call is available since Miniflux v2.0.7.

Create User ¶

Request:

POST /v1/users
Content-Type: application/json

{
    "username": "bob",
    "password": "test123",
    "is_admin": false
}

Available Fields:

Field	Type
`username`	`string`
`password`	`string`
`google_id`	`string`
`openid_connect_id`	`string`
`is_admin`	`boolean`

Response:

{
    "id": 270,
    "username": "bob",
    "theme": "system_serif",
    "language": "en_US",
    "timezone": "UTC",
    "entry_sorting_direction": "desc",
    "stylesheet": "",
    "google_id": "",
    "openid_connect_id": "",
    "entries_per_page": 100,
    "keyboard_shortcuts": true,
    "show_reading_time": true,
    "entry_swipe": true,
    "last_login_at": null
}

You must be an administrator to create users.

Update User ¶

Request:

PUT /v1/users/270
Content-Type: application/json

{
    "username": "joe"
}

Available fields:

Field	Type	Example
`username`	`string`
`password`	`string`
`theme`	`string`	“dark_serif”
`language`	`string`	“fr_FR”
`timezone`	`string`	“Europe/Paris”
`entry_sorting_direction`	`string`	“desc” or “asc”
`stylesheet`	`string`
`google_id`	`string`
`openid_connect_id`	`string`
`entries_per_page`	`int`
`is_admin`	`boolean`
`keyboard_shortcuts`	`boolean`
`show_reading_time`	`boolean`
`entry_swipe`	`boolean`

Response:

{
    "id": 270,
    "username": "joe",
    "theme": "system_serif",
    "language": "en_US",
    "timezone": "America/Los_Angeles",
    "entry_sorting_direction": "desc",
    "stylesheet": "",
    "google_id": "",
    "openid_connect_id": "",
    "entries_per_page": 100,
    "keyboard_shortcuts": true,
    "show_reading_time": true,
    "entry_swipe": true,
    "last_login_at": "2021-01-05T06:46:06.461189Z"
}

You must be an administrator to update users.

Get Current User ¶

Request:

GET /v1/me

Response:

{
    "id": 1,
    "username": "admin",
    "is_admin": true,
    "theme": "dark_serif",
    "language": "en_US",
    "timezone": "America/Vancouver",
    "entry_sorting_direction": "desc",
    "stylesheet": "",
    "google_id": "",
    "openid_connect_id": "",
    "entries_per_page": 100,
    "keyboard_shortcuts": true,
    "show_reading_time": true,
    "entry_swipe": true,
    "last_login_at": "2021-01-05T04:51:45.118524Z"
}

This API endpoint is available since Miniflux v2.0.8.

Get User ¶

Request:

# Get user by user ID
GET /v1/users/270

# Get user by username
GET /v1/users/foobar

Response:

{
    "id": 270,
    "username": "test",
    "is_admin": false,
    "theme": "light_serif",
    "language": "en_US",
    "timezone": "America/Los_Angeles",
    "entry_sorting_direction": "desc",
    "stylesheet": "",
    "google_id": "",
    "openid_connect_id": "",
    "entries_per_page": 100,
    "keyboard_shortcuts": true,
    "show_reading_time": true,
    "entry_swipe": true,
    "last_login_at": "2021-01-04T20:57:34.447789-08:00"
}

You must be an administrator to fetch users.

Get Users ¶

Request:

GET /v1/users

Response:

[
    {
        "id": 270,
        "username": "test",
        "is_admin": false,
        "theme": "light_serif",
        "language": "en_US",
        "timezone": "America/Los_Angeles",
        "entry_sorting_direction": "desc",
        "stylesheet": "",
        "google_id": "",
        "openid_connect_id": "",
        "entries_per_page": 100,
        "keyboard_shortcuts": true,
        "show_reading_time": true,
        "entry_swipe": true,
        "last_login_at": "2021-01-04T20:57:34.447789-08:00"
    }
]

You must be an administrator to fetch users.

Delete User ¶

Request:

DELETE /v1/users/270

You must be an administrator to delete users.

Mark User Entries as Read ¶

Request:

PUT /v1/users/123/mark-all-as-read

Returns 204 Not Content status code for success.

This API endpoint is available since Miniflux v2.0.26.

Fetch Read/Unread Counters ¶

Request:

GET /v1/feeds/counters

Response Example:

{
  "reads": {
    "1": 12,
    "3": 1,
    "4": 1
  },
  "unreads": {
    "1": 7,
    "3": 99,
    "4": 14
  }
}

This endpoint is available since Miniflux 2.0.37.

Healthcheck ¶

The healthcheck endpoint is useful for monitoring and load-balancer configuration.

Request:

GET /healthcheck

Response:

OK

Returns a status code 200 when the service is up.

Application version ¶

The version endpoint returns Miniflux build version.

Request:

GET /version

Response:

2.0.22

This API endpoint is available since Miniflux v2.0.22 and it's deprecated since version 2.0.49.

Application version and build information ¶

The version endpoint returns Miniflux version and build information.

Request:

GET /v1/version

Response:

{
    "version":"2.0.49",
    "commit":"69779e795",
    "build_date":"2023-10-14T20:12:04-0700",
    "go_version":"go1.21.1",
    "compiler":"gc",
    "arch":"amd64",
    "os":"linux"
}

This API endpoint is available since Miniflux v2.0.49.