开放的API接口

Table of Contents:

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 

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 

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)

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 

Request:

GET /v1/feeds/42/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.

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 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”: “

HTML contents

“,

“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”: “

HTML contents

“,

“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)

  • 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”: “

HTML contents

“,

“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)

  • 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”: “

HTML contents

“,

“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 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”

}

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.

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.

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.

Miniflux

本博客所有文章除特别声明外，均采用 CC BY-SA 4.0 协议 ，转载请注明出处！