Download Feeds

The Freebox downloader supports subscribing to RSS feeds, for automatic content download.

Download Feed object

Download Feeds have the following attributes:

DownloadFeed
id int Read-only

id

status enum Read-only

The feed can have the following status

Status Description
ready feed is up to date
fetching feed is updating
error there was an error trying to refresh this feed, see error
url string Read-only

Feed URL

title string Read-only

Feed title (extracted from the RSS)

desc string Read-only

Feed description (extracted from the RSS)

image_url string Read-only

Feed image URL (extracted from the RSS)

nb_read int Read-only

Number of read items in the feed

nb_unread int Read-only

Number of unread items in the feed

auto_download bool

If set to true, the downloader will automatically download new items

fetch_ts timestamp Read-only

Last time the feed was fetched

pub_ts timestamp Read-only

Last time the feed was published on remote server

error enum Read-only

Error code (same as used in Download or DownloadFile).

Download Feed Errors

When attempting to access the download feed API, you may encounter the following errors:

error_code Description
feed_not_found No feed was found with the given id
item_not_found No feed item was found with the given id
feed_is_recent You are trying to update a feed that is already up to date
internal_error Internal error

Download Feed API

Get the list of all download Feeds

GET /api/v4/downloads/feeds/

Returns the collection of all DownloadFeed feeds

Example request:

GET /api/v4/downloads/feeds/ HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "success": true,
  "result": [
      {
          "auto_download": false,
          "id": 1,
          "desc": "Custom RSS feed based off search filters.",
          "error": "none",
          "nb_read": 0,
          "title": "ezRSS - Search Results",
          "image_url": "http://ezrss.it/images/ezrssit.png",
          "status": "ready",
          "url": "http://www.ezrss.it/search/index.php?show_name=Ubuntu&mode=rss",
          "nb_unread": 29,
          "fetch_ts": 1349885023,
          "pub_ts": 1350583600
      },
      {
          "auto_download": false,
          "id": 2,
          "desc": "Latest nzb for Debian",
          "error": "none",
          "nb_read": 0,
          "title": "Debian NZB RSS",
          "image_url": "",
          "status": "ready",
          "url": "http://www.nzb-rss.com/rss/Debian.rss",
          "nb_unread": 13,
          "fetch_ts": 1350469391,
          "pub_ts": 1350583600
      }
   ]
}

Get a download Feed

GET /api/v4/downloads/feeds/{id}

Gets the DownloadFeed with the given id

Example request:

GET /api/v4/downloads/feeds/2 HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "success": true,
  "result":
      {
          "auto_download": false,
          "id": 2,
          "desc": "Latest nzb for Debian",
          "error": "none",
          "nb_read": 0,
          "title": "Debian NZB RSS",
          "image_url": "",
          "status": "ready",
          "url": "http://www.nzb-rss.com/rss/Debian.rss",
          "nb_unread": 13,
          "fetch_ts": 1350469391,
          "pub_ts": 1350583600
      }
}

Add a Download Feed

POST /api/v4/downloads/feeds/

Creates a new DownloadFeed.

Example request:

POST /api/v4/downloads/feeds/ HTTP/1.1
Host: mafreebox.freebox.fr

{
   "url": "http://www.nzb-rss.com/rss/Debian-unstable.rss"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true,
    "result": {
        "auto_download": false,
        "error": "none",
        "desc": "",
        "status": "ready",
        "nb_read": 0,
        "title": "",
        "image_url": "",
        "feed_id": 6,
        "url": "http://www.nzb-rss.com/rss/Debian-unstable.rss",
        "nb_unread": 0,
        "fetch_ts": 0,
        "pub_ts": 1350583600
    }

}

Delete Download Feed

DELETE /api/v4/downloads/feeds/{id}

Deletes the DownloadFeed and all the associated items.

This will not alter the Download tasks.

Example request:

DELETE /api/v4/downloads/feeds/1 HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true
}

Update a Download Feed

PUT /api/v4/downloads/feeds/{id}

Updates the DownloadFeed task with the given id

Example request:

PUT /api/v4/downloads/feeds/2 HTTP/1.1
Host: mafreebox.freebox.fr
{
    "auto_download": true
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true,
    "result": {
        "auto_download": true,
        "error": "none",
        "desc": "Latest nzb for Debian",
        "title": "Debian NZB RSS",
        "status": "ready",
        "nb_read": 0,
        "image_url": "",
        "feed_id": 2,
        "url": "http://www.nzb-rss.com/rss/Debian.rss",
        "nb_unread": 13,
        "fetch_ts": 1350583674,
        "pub_ts": 1350583600
    }
}

Refresh a Download Feed

POST /api/v4/downloads/feeds/{id}/fetch

Remotely fetches the RSS feed and updates it.

Note that if the remote feed specifies a TTL, trying to update before the ttl will result in feed_is_recent error

Example request:

POST /api/v4/downloads/feeds/2/fetch HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true
}

Refresh all Download Feeds

POST /api/v4/downloads/feeds/fetch

Remotely fetches all the RSS feeds.

Example request:

POST /api/v4/downloads/feeds/fetch HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true
}

Download Feed Item object

Each RSS DownloadFeed contains feed items object

DownloadFeedItem
id int Read-only

id

feed_id int Read-only

id of the DownloadFeed

title string[ro]

item title

desc string[ro]

item description

author string Read-only

item author

URL of the RSS feed attachment

is_read bool

you can mark the item as read manually, or it is marked as read automatically when the item is downloaded

is_downloaded bool Read-only

mark downloaded items, automatically set to true when RSS item is downloaded

fetch_ts timestamp Read-only

timestamp of the item creation

pub_ts timestamp Read-only

item publish timestamp

enclosure_url string Read-only

enclosure URL (if specified in RSS feed)

enclosure_type string Read-only

enclosure mime type (if specified in RSS feed)

enclosure_length int Read-only

enclosure size in bytes (if specified in RSS feed)

Get the items of a given RSS feed

GET /api/v4/downloads/feeds/{feed_id}/items/

Returns the collection of all DownloadFeedItems for a given DownloadFeed

Example request:

GET /api/v4/downloads/feeds/2/items/ HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "success": true,
  "result": [
     {
       "pub_ts": 1350657300,
       "fetch_ts": 1350657317,
       "is_read": true,
       "title": "debian-6.0.4-amd64-CD-1.iso",
       "link": "http://bttracker.debian.org:6969/file/debian-6.0.4-amd64-CD-1.iso.torrent?info_hash=95ce23e889cc26901740f87ac25270da725bfd36",
       "id": 2845,
       "author": "debian",
       "feed_id": 2,
       "desc": ""
     },
     {
       "pub_ts": 1350657300,
       "fetch_ts": 1350657318,
       "is_read": false,
       "title": "debian-6.0.4-amd64-CD-2.iso",
       "link": "http://bttracker.debian.org:6969/file/debian-6.0.4-amd64-CD-2.iso.torrent?info_hash=34583a8e25ef1528a8bfce99d24f401acb24d982",
       "id": 2846,
       "author": "debian",
       "feed_id": 2,
       "desc": ""
     }
   ]
}

Update a feed item

PUT /api/v4/downloads/feeds/{feed_id}/items/{item_id}

Returns the collection of all DownloadFeedItems for a given DownloadFeed

Example request:

PUT /api/v4/downloads/feeds/2/items/2846 HTTP/1.1
Host: mafreebox.freebox.fr
{
    "is_read": true
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "success": true
}

Download a feed item

POST /api/v4/downloads/feeds/{feed_id}/items/{item_id}/download

This method will enqueue the RSS item to the download list

Example request:

POST /api/v4/downloads/feeds/2/items/2846/download HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "success": true
}

Mark all items as read

POST /api/v4/downloads/feeds/{feed_id}/items/mark_all_as_read

This method will mark each items as read

Example request:

POST /api/v4/downloads/feeds/2/items/mark_all_as_read HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "success": true
}