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

link string Read-only¶: 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
}