fever

Miniflux Fever API

This document describes the Fever-compatible API implemented by the internal/fever package in this repository.

Endpoint

Path: BASE_URL/fever/
Methods: not restricted by the router; read requests are typically sent as GET, write requests should be sent as POST
Response format: JSON only
Reported API version: 3

Authentication

Fever authentication is enabled per user from the Miniflux integrations page.

Fever Username and Fever Password are configured in Miniflux
Miniflux stores the Fever token as the MD5 hash of username:password
Clients authenticate by sending that token as the api_key parameter
Token lookup is case-insensitive

Example:

api_key = md5("fever_username:fever_password")

Example shell command:

printf '%s' 'fever_username:fever_password' | md5sum

Authentication failure does not return HTTP 401. The middleware returns HTTP 200 with:

{
  "api_version": 3,
  "auth": 0
}

On successful authentication, every response includes:

api_version: always 3
auth: always 1
last_refreshed_on_time: current server Unix timestamp at response time

Dispatch Rules

The handler selects the first matching operation in this order:

groups
feeds
favicons
unread_item_ids
saved_item_ids
items
mark=item
mark=feed
mark=group

If no selector is provided, the server returns the base authenticated response only.

For read operations, the selector must be present in the query string. For write operations, mark, as, id, and before are read from request form values, so they may come from the query string or a form body.

Read Operations

`?groups`

Returns:

groups: list of categories
feeds_groups: mapping of category IDs to feed IDs

Response shape:

{
  "api_version": 3,
  "auth": 1,
  "last_refreshed_on_time": 1710000000,
  "groups": [
    {
      "id": 1,
      "title": "All"
    }
  ],
  "feeds_groups": [
    {
      "group_id": 1,
      "feed_ids": "10,11"
    }
  ]
}

Notes:

groups are Miniflux categories
feeds_groups.feed_ids is a comma-separated string
categories with no feeds are returned in groups but have no feeds_groups entry

`?feeds`

Returns:

feeds: list of feeds
feeds_groups: mapping of category IDs to feed IDs

Feed fields:

id
favicon_id
title
url
site_url
is_spark
last_updated_on_time

Notes:

favicon_id is 0 when the feed has no icon
is_spark is always 0 in this implementation
last_updated_on_time is the feed check time as a Unix timestamp

`?favicons`

Returns:

favicons: list of favicon objects

Favicon fields:

id
data

Notes:

data is a data URL such as image/png;base64,...

`?unread_item_ids`

Returns:

unread_item_ids: comma-separated list of unread entry IDs

Response shape:

{
  "api_version": 3,
  "auth": 1,
  "last_refreshed_on_time": 1710000000,
  "unread_item_ids": "100,101,102"
}

`?saved_item_ids`

Returns:

saved_item_ids: comma-separated list of starred entry IDs

`?items`

Returns:

items: list of entries
total_items: total number of non-removed entries for the user

Item fields:

id
feed_id
title
author
html
url
is_saved
is_read
created_on_time

The implementation always excludes entries whose status is removed.

Pagination and filtering

The handler applies a fixed limit of 50 items.

Supported parameters:

since_id: returns entries with id > since_id when greater than 0, and the oldest entries otherwise, ordered by id ASC
max_id: returns entries with id < max_id when greater than 0, and the most recent entries otherwise (including 0), ordered by id DESC
with_ids: comma-separated list of entry IDs to fetch, ordered by id ASC

Selector precedence inside ?items is:

since_id
max_id
with_ids
no item filter

Notes:

with_ids does not enforce the 50-ID maximum mentioned in older Fever documentation, but the 50-row limit still applies: a longer list returns its 50 lowest IDs
invalid with_ids members are parsed as 0 and do not match normal entries
when items is requested without since_id, max_id, or with_ids, the 50 oldest entries are returned, ordered by id ASC
html is returned after Miniflux content rewriting and may include media-proxy-rewritten URLs

Example:

{
  "api_version": 3,
  "auth": 1,
  "last_refreshed_on_time": 1710000000,
  "total_items": 245,
  "items": [
    {
      "id": 100,
      "feed_id": 10,
      "title": "Example entry",
      "author": "Author",
      "html": "<p>Content</p>",
      "url": "https://example.org/post",
      "is_saved": 0,
      "is_read": 1,
      "created_on_time": 1709990000
    }
  ]
}

Write Operations

Normal successful write operations return the base authenticated response:

{
  "api_version": 3,
  "auth": 1,
  "last_refreshed_on_time": 1710000000
}

`mark=item`

Parameters:

mark=item
id=<entry_id>
as=read|unread|saved|unsaved

Behavior:

as=read: marks the entry as read
as=unread: marks the entry as unread
as=saved: toggles the starred flag
as=unsaved: toggles the starred flag

Important:

saved and unsaved both call the same toggle operation
sending as=saved twice will save, then unsave
sending as=unsaved twice will unsave, then save
if id <= 0, the handler returns without writing a response body
if the entry does not exist or is already removed, the server returns the base response without an error

`mark=feed`

Parameters:

mark=feed
as=read
id=<feed_id>
before=<unix_timestamp>

Behavior:

marks unread entries in the feed as read when published_at < before
the update runs asynchronously in a goroutine after the response is returned

Notes:

if id <= 0, the handler returns without writing a response body
if before is missing or invalid, it is treated as Unix time 0, which usually means nothing is marked as read

`mark=group`

Parameters:

mark=group
as=read
id=<group_id>
before=<unix_timestamp>

Behavior:

id=0: marks all unread entries as read, ignoring before
id>0: marks unread entries in the matching category as read when published_at < before
the update runs asynchronously in a goroutine after the response is returned

Notes:

group IDs map to Miniflux category IDs
if id < 0, the handler returns without writing a response body
if before is missing or invalid for id>0, it is treated as Unix time 0, which usually means nothing is marked as read

Error Handling

Authentication failures:

HTTP status: 200
body: {"api_version":3,"auth":0}

Internal errors:

HTTP status: 500
body:

{
  "error_message": "..."
}

Differences From Generic Fever Documentation

This implementation is Fever-compatible, but it does not match every detail of historical Fever API docs.

Responses are always JSON; api=xml is mentioned in code comments but is not implemented
api_version is 3
last_refreshed_on_time is set to the current response time, not the timestamp of the most recently refreshed feed
the Kindling and Sparks super groups are not returned
feeds[].is_spark is always 0
as=saved and as=unsaved toggle the saved flag instead of setting it absolutely

Examples

Fetch groups:

curl -s 'https://miniflux.example.com/fever/?api_key=TOKEN&groups'

Fetch most recent items:

curl -s 'https://miniflux.example.com/fever/?api_key=TOKEN&items&max_id=0'

Fetch items after a known ID:

curl -s 'https://miniflux.example.com/fever/?api_key=TOKEN&items&since_id=123'

Mark an item as read:

curl -s -X POST 'https://miniflux.example.com/fever/' \
  -d 'api_key=TOKEN' \
  -d 'mark=item' \
  -d 'as=read' \
  -d 'id=123'

Mark a feed as read before a timestamp:

curl -s -X POST 'https://miniflux.example.com/fever/' \
  -d 'api_key=TOKEN' \
  -d 'mark=feed' \
  -d 'as=read' \
  -d 'id=10' \
  -d 'before=1710000000'

Mark all items as read through the group endpoint:

curl -s -X POST 'https://miniflux.example.com/fever/' \
  -d 'api_key=TOKEN' \
  -d 'mark=group' \
  -d 'as=read' \
  -d 'id=0'

Name		Name	Last commit message	Last commit date
parent directory ..
README.md		README.md
handler.go		handler.go
middleware.go		middleware.go
response.go		response.go

Navigation Menu

Repository navigation

fever

fever

README.md

Miniflux Fever API

Endpoint

Authentication

Dispatch Rules

Read Operations

`?groups`

`?feeds`

`?favicons`

`?unread_item_ids`

`?saved_item_ids`

`?items`

Pagination and filtering

Write Operations

`mark=item`

`mark=feed`

`mark=group`

Error Handling

Differences From Generic Fever Documentation

Examples

FilesExpand file tree

fever

Directory actions

More options

Directory actions

More options

Latest commit

History

fever

Folders and files

parent directory

README.md

Miniflux Fever API

Endpoint

Authentication

Dispatch Rules

Read Operations

?groups

?feeds

?favicons

?unread_item_ids

?saved_item_ids

?items

Pagination and filtering

Write Operations

mark=item

mark=feed

mark=group

Error Handling

Differences From Generic Fever Documentation

Examples

`?groups`

`?feeds`

`?favicons`

`?unread_item_ids`

`?saved_item_ids`

`?items`

`mark=item`

`mark=feed`

`mark=group`