Overview of the REST API 

For detailed documentation, please see our developer documentation.

Getting Started

In order to get started using our API, you need to have a valid Filtrbox account.  See http://www.filtrbox.com/signup.html for more information. You can use any supported representation for these calls, but we will be only showing JSON for examples after the first. 

If you haven't read them yet, reviewing Recommended Practices, Versioning, Available Representations, and the Developer Documentation will help get you up to speed quickly on the abilities and limitations of our API.  

This article will walk through some common usages of our API, what calls you would want to make and some examples.  For the examples, we're using curl, but you should be able to replicate these in the client or language of your choice easily.  Just don't forget the Accept or Content-Type header (accept tells us what you want the response as, content-type tells you what format the data you're passing to us is in).    

Retrieve All Folders in your account

Examples using json and xml, both versioned and none versioned.

curl -u youremail:yourpassword -H 'Accept:application/json' -X GET https://www.filtrbox.com/rest/folders

curl -u youremail:yourpassword -H 'Accept:application/xml' -X GET https://www.filtrbox.com/rest/folders

curl -u youremail:yourpassword -H 'Accept:application/fbox-v1+xml' -X GET https://www.filtrbox.com/rest/folders
curl -u youremail:yourpassword -H 'Accept:application/fbox-v1+json' -X GET https://www.filtrbox.com/rest/folders

Retrieve All Filtrs within a folder

curl -u youremail:yourpassword -H 'Accept:application/json' -X GET https://www.filtrbox.com/rest/folders/<FOLDERID>/filtrs 

Retrieve Articles from a Filtr

curl -u youremail:yourpassword -H 'Accept:application/json' -X GET https://www.filtrbox.com/rest/filtrs/<FILTRID>/articles

Restricting Results

Same call but restricting start date to August 1, 2009 (ISO8601 format) and FiltrRank greater than 7: 

curl -u youremail:yourpassword -H 'Accept:application/json' -X GET 'https://www.filtrbox.com/rest/filtrs/<FILTRID>/articles?startdate=Sat%2C01+Aug+2009+24%3A00%3A00+MST&threshold=7'

Paging Results

Note that you get counts for total pages, total results on the current page, and total articles that meet your restriction requirements in each page result.  

curl -u youremail:yourpassword -H 'Accept:application/json' -X GET 'https://www.filtrbox.com/rest/filtrs/<FILTRID>/articles?pagenumber=7'

Add a Folder

A couple of things to notice here.  First is that we are setting the Content-Type instead of Accept header.  This simply instructs the API that we are going to be passing json data to it.  The next is that we are using the versioned representation this time.  You could just as easily use application/json if you didn't want to lock to our V1 version.  

curl -u youremail:yourpassword -i -H 'Content-Type:application/fbox-v1+json' -X POST https://www.filtrbox.com/rest/folders -d '{"name":"REST FOLDER"}' 

After executing this statement, you will see in the response headers the location of the new folder:

Location: https://www.filtrbox.com/rest/folders/<NEW FOLDER ID>

Add a Filtr to a Folder

Creating a Filtr is almost exactly the same as creating a folder.  There are many more options available when creating a Filtr but at the very minimum, a name is required.  The name will also act as the primary keyword.  

curl -u youremail:yourpassword -i -H 'Content-Type:application/fbox-v1+json' -X POST https://www.filtrbox.com/rest/folders/<FOLDERID>/filtrs -d '{"name":"REST FILTR"}'