├── README.md └── content ├── authentication.md ├── entries.md ├── extract-full-content.md ├── feeds.md ├── icons.md ├── imports.md ├── pages.md ├── recently-read-entries.md ├── saved-searches.md ├── starred-entries.md ├── subscriptions.md ├── supporting-twitter.md ├── taggings.md ├── tags.md ├── unread-entries.md └── updated-entries.md /README.md: -------------------------------------------------------------------------------- 1 | Feedbin API V2 2 | ============== 3 | 4 | This is the official documentation for the Feedbin REST-style API. 5 | 6 | API Objects 7 | ----------- 8 | 9 | - [Authentication](content/authentication.md) 10 | - [Subscriptions](content/subscriptions.md) 11 | - [Entries](content/entries.md) 12 | - [Unread Entries](content/unread-entries.md) 13 | - [Starred Entries](content/starred-entries.md) 14 | - [Taggings](content/taggings.md) 15 | - [Tags](content/tags.md) 16 | - [Saved Searches](content/saved-searches.md) 17 | - [Recently Read Entries](content/recently-read-entries.md) 18 | - [Updated Entries](content/updated-entries.md) 19 | - [Icons](content/icons.md) 20 | - [Imports](content/imports.md) 21 | - [Pages](content/pages.md) 22 | 23 | Tech Notes 24 | ---------- 25 | 26 | - [Extracting Full Content](content/extract-full-content.md) 27 | - [Supporting Twitter](content/supporting-twitter.md) 28 | 29 | Changes 30 | ------- 31 | - 2019-12-27: Added [Pages API](content/pages.md) 32 | - 2019-05-17: Added [Imports API](content/imports.md) 33 | - 2019-03-13: Added [Icons API](content/icons.md) 34 | - 2015-01-22: Added [Updated Entries API](content/updated-entries.md) 35 | - 2015-01-22: Added [Recently Read Entries API](content/recently-read-entries.md) 36 | - 2013-10-14: Added [Saved Search API](content/saved-searches.md) 37 | - 2013-05-20: Added `PATCH subscriptions.json` for editing feed titles to [Subscriptions](content/subscriptions.md#update-subscription) 38 | - 2013-05-20: Added `per_page` paramter to [Entries](content/entries.md) 39 | 40 | Making Requests 41 | --------------- 42 | 43 | The base URL for all requests is `https://api.feedbin.com/v2/` Only https is supported. 44 | 45 | The Feedbin API uses HTTP Basic authentication 46 | 47 | Using cURL you would make a request like: 48 | 49 | ```shell 50 | curl -u 'example@example.com:password' https://api.feedbin.com/v2/subscriptions.json 51 | ``` 52 | 53 | When creating or updating a record you must set `application/json; charset=utf-8` as the `Content-Type` header. 54 | 55 | ```shell 56 | curl -u 'example@example.com:password' \ 57 | -H "Content-Type: application/json; charset=utf-8" \ 58 | -X POST -d '{"feed_url":"http://daringfireball.net"}' \ 59 | https://api.feedbin.com/v2/subscriptions.json 60 | ``` 61 | 62 | Without this header you'll wind up with a `415 Unsupported Media Type` response. 63 | 64 | HTTP Caching, Use It 65 | -------------------- 66 | For extra speed, please use HTTP Caching. `GET` request set ETag and a Last-Modified headers. 67 | 68 | ```shell 69 | curl -v -u 'example@example.com:password' https://api.feedbin.com/v2/subscriptions/3.json 70 | < ETag: "c7d001e87bda1f0d3745b6bd2811b055" 71 | < Last-Modified: Sat, 02 Feb 2013 15:20:46 GMT 72 | ``` 73 | 74 | You can use these headers in subsequent requests like: 75 | 76 | ```shell 77 | curl -v -u 'example@example.com:password' --header 'If-Modified-Since:Sat, 02 Feb 2013 15:20:46 GMT' --header 'If-None-Match:"c7d001e87bda1f0d3745b6bd2811b055"' https://api.feedbin.com/v2/subscriptions/3.json 78 | < HTTP/1.1 304 Not Modified 79 | ``` 80 | 81 | Pagination 82 | ---------- 83 | Entries use pagination. Each page has a limit of 100 items. Paginated request will include a link header like: 84 | 85 | ``` 86 | Links: ; rel="next", ; rel="last" 87 | ``` 88 | 89 | The possible rel values are: 90 | 91 | - `first` The URL of the first page of results. 92 | - `prev` The URL of the previous page of results. 93 | - `next` The URL of the next page of results. 94 | - `last` The URL of the last page of results. 95 | 96 | On paginated resources there is a header in the response called: `X-Feedbin-Record-Count`. This header reports the total number of records for a resource. 97 | 98 | Dates 99 | ----- 100 | The Feedbin API uses the [ISO 8601](http://www.w3.org/TR/NOTE-datetime) date format. All responses will include dates formatted to this spec and all requests should stick to it as well. The dates are as high resolution as possible to allow for rapid state changes. When using the `since` parameter it is best to include the date exactly as it was returned by the server when the last request was made. Rounding down to the nearest second will most likely cause duplicates. 101 | 102 | The date should include complete date plus hours, minutes, seconds and timezone `YYYY-MM-DDThh:mm:ss.ssssssTZD` (eg `2013-02-19T07:33:38.449047-08:00` or in UTC `2013-02-19T15:33:38.449047Z`). All dates will be converted to UTC, so the timezone is very important. 103 | 104 | **Note** 105 | 106 | In Objective-C it's important to force a locale for the date because different regions can cause unexpected output. For example you can properly format a date for the Feedbin API like: 107 | 108 | ```objectivec 109 | NSDateFormatter *feedbinDateFormatter = [[NSDateFormatter alloc] init]; 110 | feedbinDateFormatter.timeZone = [NSTimeZone timeZoneWithAbbreviation:@"GMT"]; 111 | [feedbinDateFormatter setDateFormat:@"yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'"]; 112 | [feedbinDateFormatter setLocale:[[NSLocale alloc] initWithLocaleIdentifier:@"en_US"]]; 113 | ``` 114 | 115 | Thanks to [Stefan Pauwels](http://zoziapps.ch/) for sharing this tip. 116 | 117 | Domain 118 | ------ 119 | 120 | Until 2014-03-14 the API hostname was `api.feedbin.me`. `api.feedbin.me` will remain available but `api.feedbin.com` is recommended because it is the new primary domain. 121 | -------------------------------------------------------------------------------- /content/authentication.md: -------------------------------------------------------------------------------- 1 | Authentication 2 | ============== 3 | 4 | ### `GET /v2/authentication.json` 5 | 6 | Returns status code. You can check a users credentials with this endpoint. 7 | 8 | ```bash 9 | curl --request GET --user "example@example.com:password" https://api.feedbin.com/v2/authentication.json 10 | ``` 11 | 12 | You'll need to include the credentials using HTTP basic auth. You can set this through the `Authorization` header or using your favorite HTTP library's built in support for it. 13 | 14 | **Status Codes** 15 | 16 | - `200 OK` will be returned if credentials are valid 17 | - `401 Unauthorized` will be returned if credentials are invalid 18 | -------------------------------------------------------------------------------- /content/entries.md: -------------------------------------------------------------------------------- 1 | Entries 2 | ======= 3 | 4 | You can get all entries for a user sorted by `created_at` descending. The entry attributes vary from the original feed in several ways. Links and image sources are rewritten to always point to the fully qualified URL. This means sanitizing/escaping content is up to you. The `published` date is converted to UTC. 5 | 6 | ### `GET /v2/entries.json` 7 | 8 | Returns a paginated array of all entries for the user. 9 | 10 | ```bash 11 | curl --request GET --user "example@example.com:password" https://api.feedbin.com/v2/entries.json 12 | ``` 13 | 14 | ```json 15 | [ 16 | { 17 | "id": 2077, 18 | "feed_id": 135, 19 | "title": "Objective-C Runtime Releases", 20 | "url": "http:\/\/mjtsai.com\/blog\/2013\/02\/02\/objective-c-runtime-releases\/", 21 | "extracted_content_url": "https://extract.feedbin.com/parser/feedbin/9197b49979d10d5012130f8b456bd5bd040d3206?base64_url=aHR0cDovL3d3dy5jcmFpZ2tlcnN0aWVucy5jb20vMjAxNy8wMy8xMi9nZXR0aW5nLXN0YXJ0ZWQtd2l0aC1qc29uYi1pbi1wb3N0Z3Jlcy8=", 22 | "author": "Michael Tsai", 23 | "content": "

Bavarious<\/a> created a GitHub repository<\/a> that shows the differences between versions of Apple\u2019s Objective-C runtime<\/a> that shipped with different versions of Mac OS X.<\/p>", 24 | "summary": "Bavarious created a GitHub repository that shows the differences between versions of Apple\u2019s Objective-C runtime that shipped with different versions of Mac OS X.", 25 | "published": "2013-02-03T01:00:19.000000Z", 26 | "created_at": "2013-02-04T01:00:19.127893Z" 27 | } 28 | ] 29 | ``` 30 | 31 | Note that `title`, `author`, and `content` can be null. For example, using this feed: 32 | 33 | ```xml 34 | 35 | 36 | urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6 37 | 38 | urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 39 | 40 | 41 | ``` 42 | 43 | ```json 44 | [{ 45 | "id": 1570169709, 46 | "feed_id": 1356310, 47 | "title": null, 48 | "author": null, 49 | "summary": "", 50 | "content": null, 51 | "url": "http://s3.amazonaws.com", 52 | "extracted_content_url": "https://extract.feedbin.com/parser/feedbin/9197b49979d10d5012130f8b456bd5bd040d3206?base64_url=aHR0cDovL3d3dy5jcmFpZ2tlcnN0aWVucy5jb20vMjAxNy8wMy8xMi9nZXR0aW5nLXN0YXJ0ZWQtd2l0aC1qc29uYi1pbi1wb3N0Z3Jlcy8=", 53 | "published": "2017-10-28T14:54:19.885152Z", 54 | "created_at":"2017-10-28T14:54:19.885105Z" 55 | }] 56 | ``` 57 | 58 | | Parameter | Required | Example | 59 | | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | 60 | | `page: number` | false | `GET /v2/entries.json?page=2` will get page two of the available entries | 61 | | `since: date` | false | `GET /v2/entries.json?since=2013-02-02T14:07:33.000000Z` will get all entries created after the iso 8601 timestamp. | 62 | | `ids: number(s)` | false | `GET /v2/entries.json?ids=1,2,3` will get the entries with the ids 1, 2 and 3. A maximum of 100 entries can be requested. | 63 | | `read: boolean` | false | `GET /v2/entries.json?read=false` will get all unread entries. | 64 | | `starred: boolean` | false | `GET /v2/entries.json?starred=true` will get all starred entries. | 65 | | `per_page: number` | false | `GET /v2/entries.json?per_page=50` will limit results to 50 per page. | 66 | | `mode: enum` | false | `GET /v2/entries.json?mode=extended` the only mode available is `extended`. This includes more metadata for the entry | 67 | | `include_original: boolean` | false | `GET /v2/entries.json?include_original=true` include original entry data if the entry has been updated. | 68 | | `include_enclosure: boolean` | false | `GET /v2/entries.json?include_enclosure=true` include podcast/RSS enclosure data. | 69 | | `include_content_diff: boolean` | false | `GET /v2/entries.json?include_content_diff=true` include a diff of changed content. Result is HTML marked up to show differences. [Sample styles](https://github.com/feedbin/feedbin/blob/2610ba5aed103789d2a61708ffcd10d0432b5161/app/assets/stylesheets/_site.scss#L3246-L3309). | 70 | 71 | #### About `extracted_content_url` 72 | 73 | The `extracted_content_url` is the link to another [Feedbin service](https://feedbin.com/blog/2019/03/11/the-future-of-full-content/) that attempts to extract the full content of the entry `url`. It is powered by [Mercury Parser](https://github.com/postlight/mercury-parser) and returns the same JSON object that Mercury uses. 74 | 75 | ```json 76 | { 77 | "title": "Thunder (mascot)", 78 | "content": "...

Thunder is the stage name for the...", 79 | "author": "Wikipedia Contributors", 80 | "date_published": "2016-09-16T20:56:00.000Z", 81 | "lead_image_url": null, 82 | "dek": null, 83 | "next_page_url": null, 84 | "url": "https://en.wikipedia.org/wiki/Thunder_(mascot)", 85 | "domain": "en.wikipedia.org", 86 | "excerpt": "Thunder Thunder is the stage name for the horse who is the official live animal mascot for the Denver Broncos", 87 | "word_count": 4677, 88 | "direction": "ltr", 89 | "total_pages": 1, 90 | "rendered_pages": 1 91 | } 92 | ``` 93 | 94 | #### About `extended` Mode 95 | 96 | The `extended` mode includes a lot of additional meta-data for entries including the usual `id`, `feed_id`, `title`, `author`, `summary`, `content`, `url`, `published`, `created_at`. As well as these additions: 97 | 98 | - `original`: The JSON for the full original entry, if this entry has been updated 99 | - `images`: The image that Feedbin has extracted to be associated with the entry. 100 | - `enclosure`: Podcast related metadata 101 | - `twitter_id`: If the entry is a tweet, this is the id of the tweet on twitter. You can use this with the Twitter API to load tweets in your app. 102 | - `twitter_thread_ids`: If the entry has a related Twitter thread, this array of ids can be used with the Twitter API to load to load the full thread. The ids are sorted in ascending chronological order. 103 | - `extracted_articles`: If the entry is a tweet that links to articles, Feedbin attempts to extract the article content and provides it via the API. 104 | - `json_feed`: If the entry is from a JSON Feed, this contains the additional metadata that [JSON Feed offers](https://jsonfeed.org/version/1). 105 | 106 | 107 | Extended mode was created to make sure the original data would stay the same. The `extended` mode has a different policy where new data may be added over time. The only thing to keep in mind here is that there may be additional keys in the future and that your JSON parser should be flexible enough to deal with that. Keys will not be removed and their purpose will not change. 108 | 109 | An example with all of the keys populated would look like: 110 | 111 | ```json 112 | { 113 | "id": 1682191545, 114 | "feed_id": 1379740, 115 | "title": "Peter Kafka @pkafka", 116 | "author": "Peter Kafka", 117 | "summary": "In 2009, the big magazine publishers built their own digital service so they wouldn't be cut out by Apple or Google. Now they're selling to Apple.", 118 | "content": "

Content
", 119 | "url": "https://twitter.com/fromedome/status/973315765393920000", 120 | "extracted_content_url": "https://extract.feedbin.com/parser/feedbin/9197b49979d10d5012130f8b456bd5bd040d3206?base64_url=aHR0cDovL3d3dy5jcmFpZ2tlcnN0aWVucy5jb20vMjAxNy8wMy8xMi9nZXR0aW5nLXN0YXJ0ZWQtd2l0aC1qc29uYi1pbi1wb3N0Z3Jlcy8=", 121 | "published": "2018-03-12T21:52:16.000000Z", 122 | "created_at": "2018-03-12T22:55:53.437304Z", 123 | "original": { 124 | "author": "Brent Simmons", 125 | "content": "
Content
", 126 | "title": "Catching Up on The Omni Show", 127 | "url": "https://www.omnigroup.com/blog/entry/catching-up-on-the-omni-show", 128 | "entry_id": "https://www.omnigroup.com/blog/entry/catching-up-on-the-omni-show", 129 | "published": "2018-03-12T21:24:00.000Z", 130 | "data": {} 131 | }, 132 | "twitter_id": 973315765393920000, 133 | "twitter_thread_ids": [973315765393920000, 973315765393920001], 134 | "images": { 135 | "original_url": "http://www.macdrifter.com/uploads/2018/03/ScreenShot20180312_044129.jpg", 136 | "size_1": { 137 | "cdn_url": "https://images.feedbinusercontent.com/85996e1/85996e10ef95a3b96a914e67dfc08d5d3362c6e0.jpg", 138 | "width": 542, 139 | "height": 304 140 | } 141 | }, 142 | "enclosure": { 143 | "enclosure_url": "http://traffic.libsyn.com/atpfm/atp264.mp3", 144 | "enclosure_type": "audio/mpeg", 145 | "enclosure_length": "54103635", 146 | "itunes_duration": "01:51:35", 147 | "itunes_image": "http://static1.squarespace.com/static/513abd71e4b0fe58c655c105/t/52c45a37e4b0a77a5034aa84/1388599866232/1500w/Artwork.jpg" 148 | }, 149 | "extracted_articles": [ 150 | { 151 | "url": "https://www.recode.net/2018/3/12/17109592/apple-buys-texture-magazine-next-issue-media-eddy-cue-sxsw?utm_campaign=recode.net&utm_content=chorus&utm_medium=social&utm_source=twitter", 152 | "title": "Apple is buying Texture, the digital magazine distributor", 153 | "host": "www.recode.net", 154 | "author": "Peter Kafka", 155 | "content": "
Content
" 156 | } 157 | ] 158 | } 159 | ``` 160 | 161 | ### `GET /v2/feeds/203/entries.json` 162 | 163 | Returns a paginated array of all entries in feed_id 203 164 | 165 | ```bash 166 | curl --request GET --user "example@example.com:password" https://api.feedbin.com/v2/feeds/203/entries.json 167 | ``` 168 | 169 | ```json 170 | [ 171 | { 172 | "id": 3648, 173 | "feed_id": 203, 174 | "title": "Cleveland Drinkup February 6", 175 | "url": "https:\/\/github.com\/blog\/1398-cleveland-drinkup-february-6", 176 | "extracted_content_url": "https://extract.feedbin.com/parser/feedbin/9197b49979d10d5012130f8b456bd5bd040d3206?base64_url=aHR0cDovL3d3dy5jcmFpZ2tlcnN0aWVucy5jb20vMjAxNy8wMy8xMi9nZXR0aW5nLXN0YXJ0ZWQtd2l0aC1qc29uYi1pbi1wb3N0Z3Jlcy8=", 177 | "author": "juliamae", 178 | "content": "

Cleveland \":metal:\"! Let's \":beers:\"\":cocktail:\"\":neckbeard:\"\":guitar:\"\":octocat:\" in one of Ohio's greatest cities, Cleveland!<\/p>\n\n

Join @asenchi<\/a> and me Wednesday at the Great Lakes Brewing Company Taproom<\/a>, drinks on GitHub.<\/p>\n\n

\"Great<\/p>\n\n

The Facts:<\/strong><\/p>\n\n