API documentation

This is the public REST API every Starve user can use. All endpoints respond with a semantic HTTP status code and optionally carry a payload body.

Versioning

This API is being versioned via an Accept header:

Accept: application/vnd.starve.de+json; version=1

This header has to be part of every request made to the API.

Authentication

Just use HTTP basic auth with the email and password you use to sign into Starve:

curl -u email@host.com:password https://api.starve.de/hello

If you can't be authorized (for any endpoint), you'll receive 401 Unauthorized.

Subscriptions

To get all the feeds you subscribed to:

GET /subscriptions.json

Response

Returns an array of all subscriptions.

[
  {
    "created_at": "2014-04-16T23:30:26.000+02:00",
    "favicon": "https://starve-static.s3.amazonaws.com/assets/favicons/default/missing-1d2c306d00fcac5a96125a07835cd790.png",
    "feed_url": "http://edgerails.info/atom.xml",
    "title": "Edge Rails.info",
    "feed_id": 177,
    "folder_id": 18,
    "id": 467
  },
  ...
]

Subscribe to a feed

You can subscribe to a feed by submitting it's URL to the following endpoint.

POST /subscriptions.json?feed_url=https://firstlook.org/theintercept/feed/

Response

If no RSS feed could be found at the feed_url, you'll receive 403 Forbidden. If the feed is already among your subscriptions, you'll receive a 301 redirect with a Location header whose value is the API URL to the subscription. If the subscription was new and successful, you'll receive a 201 Created and a Location header whose value is the API URL to the new subscription.

Unsubscribe a feed

DELETE /subscriptions/:id.json

Response

This endpoint responds with 204 No Content upon successful unsubscription. If a subscription with :id does not exist, you'll receive a 404 Not Found.

Entries

Gets you all the entries -- optionally scoped by feed.

GET /entries.json
GET /entries/unread.json
GET /entries/favorites.json
GET /feeds/:feed_id/entries.json
GET /feeds/:feed_id/entries/unread.json
GET /feeds/:feed_id/entries/favorites.json

All of the above should be obvious. The last 3 examples show how to retrieve entries for a specific feed identified by a :feed_id.

Response

From either endpoint you'll receive 200 OK and an array of entries.

[
  {
    "created_at": "2014-04-16T23:32:21.000+02:00",
    "published_at": "2014-04-16T22:00:42.000+02:00",
    "id": 7628,
    "feed_id": 215,
    "title": "Simple Color Instantiation with NSString",
    "url": "http://iosdevelopertips.com/objective-c/simple-color-instantiation-nsstring.html",
    "author": "John Muchow",
    "excerpt": "<p>Category on NSString allowing simple color instantiation from its content &#x2013; Nicolas Goutaland read more on github.com</p>\n<p>iOS Developer Tips &amp; Tricks : <a href=\"http://iOSDeveloperTips.com\">iOSDeveloperTips.com</a></p>\n",
    "content": "<p>Category on NSString allowing simple color instantiation from its content &#x2013; Nicolas Goutaland read more on github.com</p>\n<p>iOS Developer Tips &amp; Tricks : <a href=\"http://iOSDeveloperTips.com\">iOSDeveloperTips.com</a></p>\n",
    "summary": null
  },
  ...
]

Read/unread entries

To mark an entry as read or unread use the following endpoints. The :id placeholder is to be substituted with the ID of an entry.

PATCH /entries/:id/mark_read.json
PATCH /entries/:id/mark_unread.json

Response: Both will just respond with 204 No Content.

Batch unread entries

To toggle read status on up to 1000 entries at once use the following endpoint.


To get all unread entries:

GET /entries/unread.json

Response: 200 OK with an array of entry IDs.

[123,345,567]

To mark them unread:

POST /entries/unread.json

{"entry_ids":[123,345,567]}

Response: 204 No Content


Or, to mark them read

DELETE /entries/unread.json

{"entry_ids":[123,345,567]}

Response: 204 No Content

Favoring/disfavoring entries

To add an entry to your favorites or remove it call the following entries with :id substituted with the ID of the entry.

PATCH /entries/:id/favor.json
PATCH /entries/:id/disfavor.json

Response: Both will report success with 204 No Content.

Batch favorite entries

To toggle favorite status on up to 1000 entries at once use the following endpoint.


To get all favorites:

GET /entries/favorites.json

Response: You'll receive an array of entry IDs.

[123,345,567]

To favor multiple entries:

POST /entries/favorites.json

{"entry_ids":[123,345,567]}

Response: 204 No Content


Or, to disfavor them:

DELETE /entries/favorites.json

{"entry_ids":[123,345,567]}

Response: 204 No Content

Folders

Subscriptions are organized in folders.

GET /folders.json

Response: You'll get an array of all your folders.

[
  {
    "unread_articles_count": 10,
    "created_at": "2014-04-16T23:30:28.000+02:00",
    "title": "politics",
    "id": 17
  },
  ...
]

A single folder

GET /folders/:id.json

Response: 200 OK with an object with folder properties.

{
  "unread_articles_count": 255,
  "created_at": "2014-04-16T23:30:27.000+02:00",
  "title": "objc",
  "id": 16
}

Create a folder

POST /folders.json?folder[title]=new%20folder

Response: Upon successful creation you'll recieve a Location redirect to the newly created folder's API URL.

Delete a folder

DELETE /folders/:id.json

Response: This endpoint responds with 204 No Content upon successful deletion. If a folder with :id does not exist, you'll receive a 404 Not Found.