Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
1166 lines (1118 sloc) 41.6 KB
- authentication:
- url: /api/login
method: POST
short_desc: "Login as an existing user."
long_desc:
- "Login as an existing user."
tips:
- >
If a user has no password set, you cannot just send any old password.
This is not <a href="http://www.instapaper.com/api/full">Instapaper</a>.
params:
- key: username
desc: "Username"
required: true
example: "samuelclay"
- key: password
desc: "Password"
optional: true
example: "new$blur"
- url: /api/logout
method: POST
short_desc: "Logout the currently logged in user."
long_desc:
- "Logout the currently logged in user."
- url: /api/signup
method: POST
short_desc: "Create a new user."
long_desc:
- "Create a new user."
params:
- key: username
desc: "Username"
required: true
example: "samuelclay"
- key: password
desc: "Password"
optional: true
example: "new$blur"
- key: email
desc: "Email address"
required: true
example: "samuel@newsblur.com"
- feeds:
- url: /rss_feeds/search_feed
method: GET
short_desc: "Information about a feed from its address."
long_desc:
- "Retrieve information about a feed from its website or RSS address."
params:
- key: address
desc: "Searches the RSS and website address and returns a feed."
required: true
example: 'techcrunch.com'
- key: offset
desc: "Try paging through feeds found by using the offset."
optional: true
example: 1
- url: /reader/feeds
method: GET
short_desc: "User's feeds, with unread counts, meta data, and optional favicons."
long_desc:
- "Retrieve a list of feeds to which a user is actively subscribed."
- "Includes the 3 unread counts (positive, neutral, negative), as well as optional favicons."
tips:
- "Use <code>/reader/refresh_feeds</code> to get updated unread counts."
- >
Turn off <code>include_favicons</code> if you can either cache favicons
or can wait to fetch them.
params:
- key: include_favicons
desc: >
Include favicons inline. Since they can be time consuming to download,
you can optionally turn them off. Use /api/v1/feeds/favicons/ to
retrieve the favicons in a separate request.
optional: true
default: "false"
example: "true/false"
- key: flat
desc: >
Returns a flat folder structure instead of nested folders. Useful
when displaying all folders in a single depth without recursive descent.
optional: true
default: "false"
example: "true/false"
- key: update_counts
desc: >
Forces recalculation of unread counts on all feeds. The preferred method is
to call this endpoint without updated counts, then call refresh_feeds to get
updated counts. That way you can quickly show the user's feeds, then update
the counts. Turning this option on will lead to a slower load-time.
optional: true
default: "false"
example: "true/false"
- url: /reader/favicons
method: GET
short_desc: "Favicons for each of a user's feeds."
long_desc:
- >
Retrieve a list of favicons for a list of feeds. Used when combined
with <code>/reader/feeds</code> and <code>include_favicons=false</code>,
so the feeds request contains far less data. Useful for mobile devices,
but requires a second request.
tips:
- >
To use inline data images, you can use this syntax:
<pre><code>&lt;img src="data:image/png;base64,[IMAGE_DATA_STRING]" /&gt;</code></pre>
params:
- key: feed_ids
desc: " Array of feed ids. Leave empty to retrieve all active (enabled) feeds."
optional: true
example: "feed_ids=12&feed_ids=24"
- url: /reader/page/:id
method: GET
short_desc: "Original page from a single feed."
long_desc:
- "Retrieve the original page from a single feed."
- url: /reader/refresh_feeds
method: GET
short_desc: "Get latest unread counts for active feeds."
long_desc:
- "Up-to-the-second unread counts for each active feed."
- "Poll for these counts no more than once a minute."
- url: /reader/feeds_trainer
method: GET
short_desc: "Get all popular and known intelligence classifiers."
long_desc:
- "Retrieves all popular and known intelligence classifiers."
- "Also includes user's own classifiers."
tips:
- "If you only want a user's classifiers, use <code>/classifiers/:id</code>."
- "Omit the feed_id to get all classifiers for all subscriptions."
params:
- key: feed_id
desc: >
Only use a single feed. Omit this to get the classifiers for all feeds at once.
optional: true
example: "42"
- url: /rss_feeds/statistics/:id
method: GET
short_desc: "Get statistics and history for a feed."
long_desc:
- "Statistics and history for a feed."
- >
Includes feed update frequencies, frequency distribution of intelligence
classifiers, average stories per month over the life of the feed, and
the last five feed and page fetches.
- url: /rss_feeds/feed_autocomplete
method: GET
short_desc: "Get a list of feeds that contain a phrase."
long_desc:
- "Get a list of feeds that contain a search phrase."
- "Searches by feed address, feed url, and feed title, in that order."
- "Will only show sites with 2+ subscribers."
params:
- key: term
desc: "Phrase to search for in feed address, url, and title."
optional: true
example: "tech"
- stories:
- url: /reader/feed/:id
method: GET
short_desc: "Stories from a single feed."
long_desc:
- "Retrieve stories from a single feed."
params:
- key: page
desc: "Page of stories, starting from 1."
optional: true
default: 1
example: 2
- key: order
desc: "Story order by oldest or newest first"
optional: true
default: newest
example: oldest
- key: read_filter
desc: "Show all stories or only unread stories"
optional: true
default: all
example: unread
- key: include_hidden
desc: >
Use this if you want to show hidden stories (provided you have a "Show Hidden
Stories" button). All native NewsBlur apps (web, ios, android) use this.
optional: true
default: "false"
example: "true"
- key: include_story_content
desc: >
If you're just checking for story ids and meta-data, you don't
need the story content, thus reducing bandwidth.
optional: true
default: "true"
example: "false"
tips:
- >
The story score (red, neutral, green) can be computed by following
the function <a href="https://github.com/samuelclay/NewsBlur/blob/master/media/js/newsblur/reader/reader_utils.js"> <code>compute_story_score</code> in reader_utils.js on GitHub</a>. Alternatively, you can use the <code>score</code> parameter.
- >
Counts are broken into three. Add them up for a total, but you shouldn't show or count the hidden stories:
<ul>
<li> <code>ps</code>: positive/focus count</li>
<li> <code>nt</code>: neutral/unread count</li>
<li> <code>ng</code>: negative/hidden count</li>
</ul>
- >
If you aren't including hidden stories and a user has many stories that are hidden (which happens quite often as they might thumbs down the publisher but thumbs up a title or tag), then make sure to keep paging if the <code>hidden_stories_count</code> is non-zero. Don't rely on the <code>stories</code> list being empty to assume that's when to stop paging.
- url: /reader/starred_stories
method: GET
short_desc: "User's starred stories."
long_desc:
- "Retrieve a user's starred stories."
params:
- key: page
desc: "Page of starred stories, starting from 1."
optional: true
default: 1
example: 2
- key: h
desc: "Pass up to 100 story_hashes. Use with starred_story_hashes."
optional: true
example: "h=a1b2c3&h=d4e5f6"
- url: /reader/starred_story_hashes
method: GET
short_desc: "Story hashes of starred stories."
long_desc:
- "Retrieve the story hashes of a user's starred stories."
params:
- key: include_timestamps
desc: "Including timestamps for starred_date"
optional: true
default: false
tips:
- "Use with /reader/starred_stories and pass up to 100 story_hashes as the <code>h</code> param."
- url: /reader/river_stories
method: GET
short_desc: "Stories from multiple feeds (River of News)."
long_desc:
- "Retrieve stories from a collection of feeds. This is known as the River of News."
- "Stories are ordered in reverse chronological order."
params:
- key: feeds
desc: "Feed ids to use in the river. Usually every feed in a folder with unread stories."
required: true
example: "feeds=12&feeds=24"
- key: page
desc: "Page of stories, starting from 1."
optional: true
default: 1
example: 2
- key: order
desc: "Story order by oldest or newest first"
optional: true
default: newest
example: oldest
- key: read_filter
desc: "Show all stories or only unread stories"
optional: true
default: unread
example: all
- key: include_hidden
desc: >
Use this if you want to show hidden stories (provided you have a "Show Hidden
Stories" button). All native NewsBlur apps (web, ios, android) use this.
optional: true
default: "false"
example: "true"
tips:
- >
Counts are broken into three. Add them up for a total, but you shouldn't show or count the hidden stories:
<ul>
<li> <code>ps</code>: positive/focus count</li>
<li> <code>nt</code>: neutral/unread count</li>
<li> <code>ng</code>: negative/hidden count</li>
</ul>
- >
If you aren't including hidden stories and a user has many stories that are hidden (which happens quite often as they might thumbs down the publisher but thumbs up a title or tag), then make sure to keep paging if the <code>hidden_stories_count</code> is non-zero. Don't rely on the <code>stories</code> list being empty to assume that's when to stop paging.
- url: /reader/river_stories
method: GET
short_desc: "Stories by story_hash."
long_desc:
- "Retrieve up to 100 stories when specifying by story_hash."
- "Used this in conjunction with <code>unread_story_hashes</code> to store stories for offline use."
params:
- key: h
desc: "Pass up to 100 story_hashes. Use with unread_story_hashes."
required: true
example: "h=468:a1b2c3&h=7531:d4e5f6"
- url: /reader/unread_story_hashes
method: GET
short_desc: "The story_hashes of all unread stories."
long_desc:
- "The story_hashes of all unread stories."
- "Useful for offline access of stories and quick unread syncing."
- "Use include_timestamps to fetch stories in date order."
params:
- key: feed_id
desc: "Feed ids to check. Omit to include every feed subscription."
optional: true
example: "feed_id=12&feed_id=24"
- key: include_timestamps
desc: "Including timestamps for story_date"
optional: true
default: false
- url: /reader/read_stories
method: GET
short_desc: "Feed of previously read stories."
long_desc:
- "Feed of previously read stories."
params:
- key: page
desc: "Page of stories, starting from 1."
optional: true
default: 1
example: 2
- key: order
desc: "Story order by oldest or newest first"
optional: true
default: newest
example: oldest
- url: /reader/mark_story_hashes_as_read
method: POST
short_desc: "Mark a story as read."
long_desc:
- "Mark stories as read using their unique story_hash."
- "Multiple story hashes can be sent at once."
- "Mix and match stories from different feeds and social subscriptions."
tips:
- "Throttle requests to mark as read. You don't need to send one request per story."
- "Queue up to 5 stories or once every 10 seconds before firing, whichever comes first."
- >
This endpoint is newer than all of the other mark as read endpoints, so use this one.
The other endpoints are maintained for old clients to use.
params:
- key: story_hash
desc: "List of story hashes to mark as read."
required: true
example: >
story_hash=123:a1d62b&story_hash=1456789:4e3c12
- url: /reader/mark_story_as_read
method: POST
short_desc: "Mark a story as read (deprecated)."
long_desc:
- "<b>Deprecated! Just send the <code>story_hash</code> to <code>mark_story_hashes_as_read</code>.</b>"
- "Mark stories as read (deprecated)."
- "Multiple story ids can be sent at once."
- "Each story must be from the same feed."
tips:
- "Throttle requests to mark as read. You don't need to send one request per story."
- "Queue up to 5 stories or once every 10 seconds before firing, whichever comes first."
params:
- key: story_id
desc: "List of story ids to mark as read."
required: true
example: >
story_id=http://blog.newsblur.com/post/1&story_id=http://blog.newsblur.com/post/2
- key: feed_id
desc: "Feed id that each story is from."
required: true
example: "42"
- url: /reader/mark_feed_stories_as_read
method: POST
short_desc: "Mark stories from multiple feeds as read (deprecated)."
long_desc:
- "<b>Deprecated! Just send the <code>story_hash</code> to <code>mark_story_hashes_as_read</code>.</b>"
- "Marks multiple stories as read."
- "Multiple story ids can be sent at once."
- "Multiple feeds can be sent."
tips:
- "Throttle requests to this endpoint. You don't need to send one request per story."
- "Queue up to 5 stories or once every 10 seconds before firing, whichever comes first."
params:
- key: feeds_stories
desc: "JSON serialized dictionary of feed_ids to an array of story_ids."
required: true
example: "{<br>12: ['story_id_1', 'story_id_2'],<br>24: ['story_id_3']<br>}"
- url: /reader/mark_social_stories_as_read
method: POST
short_desc: "Mark stories from a blurblog as read (deprecated)."
long_desc:
- "<b>Deprecated! Just send the <code>story_hash</code> to <code>mark_story_hashes_as_read</code>.</b>"
- "Marks multiple stories as read."
- "Multiple story ids can be sent at once."
- "Multiple feeds can be sent."
tips:
- "Throttle requests to this endpoint. You don't need to send one request per story."
- "Queue up to 5 stories or once every 10 seconds before firing, whichever comes first."
params:
- key: users_feeds_stories
desc: "JSON serialized dictionary of user_ids to feed_ids to an array of story_ids."
required: true
example: "{<br>user_id: <br>{feed_id: ['story_id_1', 'story_id_2'],<br>24: ['story_id_3']<br>}<br>}"
- url: /reader/mark_story_as_unread
method: POST
short_desc: "Mark a story as unread."
long_desc:
- "Mark a story as unread."
params:
- key: story_id
desc: "Story id to mark unread."
required: true
example: "http://www.ofbrooklyn.com/story-title"
- key: feed_id
desc: "Feed id that the story is from."
required: true
example: "42"
- url: /reader/mark_story_hash_as_unread
method: POST
short_desc: "Mark a story as unread."
long_desc:
- "Mark a single story as unread using its unique story_hash."
- "Premium users can mark up to 30 days as unread. Free users only have 15 days."
- >
If a story is too old to mark as read, look for (and display to the user) the
<code>message</code> parameter returned back to you.
tips:
- >
This endpoint is newer than all of the other mark as read endpoints, so use this one.
The other endpoints are maintained for old clients to use.
params:
- key: story_hash
desc: "A story hash to mark as unread."
required: true
example: >
story_hash=123:a1d62b
- url: /reader/mark_story_as_starred
method: POST
short_desc: "Mark a story as starred (saved)."
long_desc:
- "Mark a story as starred (saved)."
params:
- key: story_id
desc: "Story id to save."
required: true
example: "64"
- key: feed_id
desc: "Feed id that the story is from."
required: true
example: "42"
- url: /reader/mark_story_hash_as_starred
method: POST
short_desc: "Mark a story as starred (saved)."
long_desc:
- "Mark a story as starred (saved)."
params:
- key: story_hash
desc: "Story to save, specified by hash."
required: true
example: "64:a295ed"
- url: /reader/mark_story_as_unstarred
method: POST
short_desc: "Mark a story as unstarred (unsaved)."
long_desc:
- "Mark a story as unstarred (unsaved)."
params:
- key: story_id
desc: "Story id to unsave."
required: true
example: "64"
- key: feed_id
desc: "Feed id that the story is from."
required: true
example: "42"
- url: /reader/mark_story_hash_as_unstarred
method: POST
short_desc: "Mark a story as unstarred (unsaved)."
long_desc:
- "Mark a story as unstarred (unsaved)."
params:
- key: story_hash
desc: "Story to unsave, specified by hash."
required: true
example: "64:a295ed"
- url: /reader/mark_feed_as_read
method: POST
short_desc: "Mark a list of feeds as read."
long_desc:
- "Mark a list of feeds as read."
params:
- key: feed_id
desc: "List of feed ids to mark as read."
required: true
example: "feed_id=12&feed_id=24"
- key: cutoff_timestamp
desc: "Timestamp for older/newer cutoff."
optional: true
example: "1400777921"
- key: direction
desc: "Older or newer stories should be marked as read. Use with <code>cutoff_timestamp</code>"
optional: true
example: "older"
tips:
- "To mark a folder as read, send the ids of each feed inside the folder."
- url: /reader/mark_all_as_read
method: POST
short_desc: "Mark all stories from all feeds as read."
long_desc:
- "Mark all stories from all feeds as read."
tips:
- "Use <code>0</code> days back to mark everything as read."
params:
- key: days
desc: "Days back to mark as read."
optional: true
default: "0"
example: "7"
- social:
- url: /social/river_stories
method: GET
short_desc: "Stories from multiple users (River of News)."
long_desc:
- "Retrieve stories from a collection of social subscriptions. This is known as the River of News."
- "Stories are ordered in reverse chronological order by default."
- "Only unread stories are available."
params:
- key: social_user_ids
desc: "User ids to use in the river."
required: true
example: "feed_id=12&feed_id=24"
- key: page
desc: "Page of stories, starting from 1."
optional: true
default: 1
example: 2
- key: order
desc: "Story order by oldest or newest first"
optional: true
default: newest
example: oldest
- url: /social/share_story
method: POST
short_desc: "Share a story with optional comments."
long_desc:
- "Share a story with optional comments. The story is shared on the user's blurblog."
params:
- key: feed_id
desc: "Feed id that the story is from."
required: true
example: "42"
- key: story_id
desc: "Story id to share."
required: true
example: "http://blog.newsblur.com/post/1"
- key: comments
desc: "The meat of the share."
optional: true
example: "42"
- key: source_user_id
desc: >
If the story is being re-shared from another blurblog, note the
user_id of the original sharer.
optional: true
example: "128"
- key: post_to_services
desc: "List of services to cross-post to. Can be 'twitter' and/or 'facebook'."
optional: true
example: "post_to_services=twitter&post_to_service=facebook"
- key: format
desc: "Return JSON or a HTML template"
optional: true
default: "json"
example: "html"
- url: /social/unshare_story
method: POST
short_desc: "Remove a shared story from user's blurblog."
long_desc:
- >
Removes a shared story from a user's blurblog. Unshares the story and
removes the comments. Any replies will also be deleted. This may change.
params:
- key: feed_id
desc: "Feed id that the story is from."
required: true
example: "42"
- key: story_id
desc: "Story id to remove the existing share."
required: true
example: "http://blog.newsblur.com/post/1"
- key: format
desc: "Return JSON or a HTML template"
optional: true
default: "json"
example: "html"
- url: /social/load_user_friends
method: GET
short_desc: "Lists of user profiles: followers, followings, etc."
long_desc:
- This lists the user profiles of followers and followings of a user.
- Also returns information related to which sharing services a user is using.
- url: /social/profile
method: GET
short_desc: "Public profile of a user."
long_desc:
- "Public profile of a user. Includes common followers and common followings."
params:
- key: user_id
desc: "User id of user"
required: true
example: "42"
- url: /social/load_user_profile
method: GET
short_desc: "Private details of the current user's profile and connected services."
long_desc:
- "Private details of the current user's profile and connected services."
- url: /social/save_user_profile
method: POST
short_desc: "Saves a user's profile details."
long_desc:
- "Saves a user's profile details."
params:
- key: location
desc: "Hometown"
optional: true
example: "New York City"
- key: bio
desc: "160 character bio."
optional: true
example: "Developer. API Designer."
- key: website
desc: "Website address"
optional: true
example: "http://www.samuelclay.com"
- key: photo_service
desc: "Which photo service to use: twitter, facebook, gravatar."
optional: true
example: "twitter"
- url: /social/interactions
method: GET
short_desc: "Interactions between a user and other users."
long_desc:
- "Interactions between a user and other users."
params:
- key: user_id
desc: "ID of user. Defaults to current logged in user."
optional: true
example: "42"
- key: page
desc: "4 interactions per page."
optional: true
example: "2"
- key: format
desc: "JSON or HTML template"
optional: true
default: "json"
example: "html"
- url: /social/activities
method: GET
short_desc: "A user's activities."
long_desc:
- "A user's activities: follows, shared stories, and replies to comments."
- >
Also includes starred stories and new site subscriptions if fetching the
currently logged in user's activities.
params:
- key: user_id
desc: "ID of user. Defaults to current logged in user."
optional: true
example: "42"
- key: page
desc: "4 activities per page."
optional: true
example: "2"
- key: format
desc: "JSON or HTML template"
optional: true
default: "json"
example: "html"
- url: /social/follow
method: POST
short_desc: "Follow a user and subscribe to their blurblog."
long_desc:
- "Follow a user and subscribe to their blurblog."
params:
- key: user_id
desc: "ID of user to follow."
required: true
example: "42"
- url: /social/unfollow
method: POST
short_desc: "Unfollow a user and unsubscribe from their blurblog."
long_desc:
- "Unfollow a user and unsubscribe from their blurblog."
params:
- key: user_id
desc: "ID of user to unfollow."
required: true
example: "42"
- url: /social/feed_trainer
method: GET
short_desc: "Get the intelligence classifiers for a blurblog."
long_desc:
- "Get the intelligence classifiers for a blurblog."
params:
- key: user_id
desc: "ID of blurblog's user."
required: true
example: "42"
- url: /social/public_comments
method: GET
short_desc: "Get all public comments on a shared story."
long_desc:
- "Get all public comments on a shared story."
- >
If you want comments from friends, they are already attached to the
story from either <code>reader/feed/:id</code> or
<code>/social/stories/:user_id</code>.
params:
- key: story_id
desc: "ID of shared story."
required: true
example: "http://blog.newsblur.com/post/1"
- key: feed_id
desc: "ID of feed for the shared story."
required: true
example: "42"
- key: format
desc: "JSON or HTML template"
optional: true
default: "json"
example: "html"
- url: /social/save_comment_reply
method: POST
short_desc: "Saves a reply to a comment."
long_desc:
- "Saves a reply to a comment."
- "Comments can have a number of replies, but they are all one-level deep."
- >
Replying to a comment sends notifications to both original commenter and to
every other replier to the comment.
params:
- key: story_feed_id
desc: "ID of feed the story belongs to."
required: true
example: "42"
- key: story_id
desc: "ID of story being commented on."
required: true
example: "http://blog.newsblur.com/post/1"
- key: comment_user_id
desc: "ID of user who left the original comment that is now being replied to."
required: true
example: "64"
- key: reply_comments
desc: "The content of the reply."
required: true
example: "Brilliant analysis."
- key: reply_id
desc: >
If editing an existing reply, provide the original reply id so the correct
reply can be overwritten.
optional: true
example: "5000...0042"
- key: format
desc: "Return JSON or a HTML template"
optional: true
default: "json"
example: "html"
- url: /social/remove_comment_reply
method: POST
short_desc: "Deletes a reply."
long_desc:
- "Deletes a reply from a comment."
- "Also deletes the interactions and activities associated with the reply."
params:
- key: story_feed_id
desc: "ID of feed the story belongs to."
required: true
example: "42"
- key: story_id
desc: "ID of story being commented on."
required: true
example: "http://blog.newsblur.com/post/1"
- key: comment_user_id
desc: "ID of user who left the original comment that is now being replied to."
required: true
example: "64"
- key: reply_id
desc: The reply's id
optional: true
example: "5000...0042"
- key: format
desc: "Return JSON or a HTML template"
optional: true
default: "json"
example: "html"
- url: /social/like_comment
method: POST
short_desc: "Favorites a comment."
long_desc:
- "Favorites a comment."
- "Does not send an email to the recipient user, but they do see an interaction."
params:
- key: story_feed_id
desc: "ID of feed the story belongs to."
required: true
example: "42"
- key: story_id
desc: "ID of story being commented on."
required: true
example: "http://blog.newsblur.com/post/1"
- key: comment_user_id
desc: "ID of user who left the original comment that is now being replied to."
required: true
example: "64"
- key: format
desc: "Return JSON or a HTML template"
optional: true
default: "json"
example: "html"
- url: /social/remove_like_comment
method: POST
short_desc: "Un-favorites a comment."
long_desc:
- "Un-favorites a comment."
params:
- key: story_feed_id
desc: "ID of feed the story belongs to."
required: true
example: "42"
- key: story_id
desc: "ID of story being commented on."
required: true
example: "http://blog.newsblur.com/post/1"
- key: comment_user_id
desc: "ID of user who left the original comment that is now being replied to."
required: true
example: "64"
- key: format
desc: "Return JSON or a HTML template"
optional: true
default: "json"
example: "html"
- url: /social/find_friends
method: GET
short_desc: "Search for a user by username, email, or blurblog title."
long_desc:
- "Search for a user by username, email, or blurblog title."
params:
- key: query
desc: "Username, email, or part of a blurblog title."
required: true
example: "samuel"
- url: /social/rss/:user_id/:username
method: GET
short_desc: "RSS feed for a blurblog."
long_desc:
- "RSS feed for a blurblog."
tips:
- >
The <code>username</code> url parameter is optional. It's just recommended
if you have it.
- url: /social/stories/:user_id/:username
method: GET
short_desc: "Shared stories from a user's blurblog."
long_desc:
- "Shared stories from a user's blurblog."
- "Comments, replies, and profiles from followed users are automatically included."
params:
- key: order
desc: "Story order by oldest or newest first"
optional: true
default: newest
example: oldest
- key: read_filter
desc: "Show all stories or only unread stories"
optional: true
default: all
example: unread
tips:
- >
The <code>username</code> url parameter is optional. It's just recommended
if you have it.
- url: /social/page/:user_id/:username
method: GET
short_desc: "A user's shared stories blurblog in HTML."
long_desc:
- "A user's shared stories blurblog in HTML."
- "This may also live at a custom URL, which is specified in the user's full profile."
tips:
- >
The <code>username</code> url parameter is optional. It's just recommended
if you have it.
- url: /social/settings/:user_id/:username
method: GET
short_desc: "A user's full profile."
long_desc:
- "A user's full profile."
tips:
- >
The <code>username</code> url parameter is optional. It's just recommended
if you have it.
- url: /social/statistics/:user_id/:username
method: GET
short_desc: "Get statistics and history for a blurblog."
long_desc:
- "Get statistics and history for a blurblog."
tips:
- >
The <code>username</code> url parameter is optional. It's just recommended
if you have it.
- "feed management":
- url: /reader/add_url
method: POST
short_desc: "Add a feed by its URL (RSS feed or website)."
long_desc:
- "Add a feed by its URL. Can be either the RSS feed or the website itself."
params:
- key: url
desc: "URL of website or RSS feed."
required: true
example: "http://blog.newsblur.com"
- key: folder
desc: "Folder to place feed in. Omit to use top level."
optional: true
default: "[Top Level]"
example: "Blogs"
tips:
- >
If you want to just show the Add Site dialog on the site, you can use this URL:
<code>http://www.newsblur.com/?url=%u</code>
- url: /reader/add_folder
method: POST
short_desc: "Add a new folder."
long_desc:
- "Add a new folder."
params:
- key: folder
desc: "Folder name"
required: true
example: "Photo-blogs Extraordinaire"
- key: parent_folder
desc: "Existing folder to create new folder inside of. Omit for top level."
optional: true
default: "[Top Level]"
example: "All Blogs"
- url: /reader/move_feed_to_folder
method: POST
short_desc: "Move a feed into a different folder."
long_desc:
- "Move a feed into a different folder."
params:
- key: feed_id
desc: "Feed id."
required: true
example: 12
- key: in_folder
desc: >
Current folder the feed is in. Necessary to disambiguate if a feed is in
multiple folders.
required: true
example: "Blogs"
- key: to_folder
desc: "Folder the feed is going into."
required: true
example: "Tumblrs"
tips:
- "Leave folder names blank to specify Top Level."
- url: /reader/move_folder_to_folder
method: POST
short_desc: "Move a folder into a different folder."
long_desc:
- "Move a folder into a different folder."
params:
- key: folder_name
desc: "Name of folder being moved."
required: true
example: "Tumblrs"
- key: in_folder
desc: >
Current folder the folder is in. Necessary to disambiguate if a folder
name is in multiple folders. (Please don't let this happen.)
required: true
example: "Blogs"
- key: to_folder
desc: "New folder the existing folder is going into."
required: true
example: "Daily Blogs"
tips:
- "Leave folder names blank to specify Top Level."
- url: /reader/rename_feed
method: POST
short_desc: "Rename a feed title."
long_desc:
- "Rename a feed title. Only the current user will see the new title."
params:
- key: feed_title
desc: "New feed title."
required: true
example: "NYTimes"
- key: feed_id
desc: "Feed id of the feed to be renamed."
required: true
example: "42"
- url: /reader/delete_feed
method: POST
short_desc: "Unsubscribe from a feed."
long_desc:
- "Unsubscribe from a feed. Removes it from the folder."
- >
Set the <code>in_folder</code> parameter to remove a feed from the correct
folder, in case the user is subscribed to the feed in multiple folders.
params:
- key: feed_id
desc: "Feed id of feed to remove."
required: true
example: "42"
- key: in_folder
desc: "Name of folder the feed is in."
optional: true
example: "News"
- url: /reader/rename_folder
method: POST
short_desc: "Rename a folder."
long_desc:
- "Rename a folder."
params:
- key: folder_to_rename
desc: "Original folder name."
required: true
example: "Photoblogs"
- key: new_folder_name
desc: "New folder name."
required: true
example: "East Coast Photoblogs"
- key: in_folder
desc: "Name of parent folder, used to find the folder."
required: true
example: "Blogs"
- url: /reader/delete_folder
method: POST
short_desc: "Delete a folder and unsubscribe from all feeds inside."
long_desc:
- "Delete a folder and unsubscribe from all feeds inside."
params:
- key: folder_to_delete
desc: "Name of folder to delete."
required: true
example: "Photoblogs"
- key: in_folder
desc: "Name of parent folder, used to find the folder. Omit if folder is top level."
optional: true
example: "Blogs"
- key: feed_id
desc: "List of feed ids in the folder that's being deleted. These feeds also get removed."
optional: true
example: "feed_id=12&feed_id=24"
- url: /reader/save_feed_order
method: POST
short_desc: "Reorder feeds and move them around between folders."
long_desc:
- "Reorder feeds and move them around between folders."
- "The entire folder structure needs to be serialized."
params:
- key: folders
desc: "Object with folders and feed ids."
required: true
example: "[12, 24, 36, <br>{'Blogs': [56, 67, 78,<br />{'Photoblogs': [42]}]}]"
- "intelligence classifiers":
- url: /classifier/:id
method: GET
short_desc: "Get the intelligence classifiers for a user's site."
long_desc:
- "Get the intelligence classifiers for a user's site."
- >
Only includes the user's own classifiers. Use <code>/reader/feeds_trainer</code>
for popular classifiers.
tips:
- >
All of this data is attached to a feed when called with
<code>/reader/feed/:id</code>.
- >
After loading a feed, there is no need to explicitly call this endpoint,
unless the feed has not yet been fetched.
- url: /classifier/save
method: POST
short_desc: "Save intelligence classifiers for a feed."
long_desc:
- "Save intelligence classifiers (tags, titles, authors, and the feed) for a feed."
tips:
- "The endpoint is far different from all other endpoints. It takes a variety of param keys."
- "You can send a list for any of the keys. <code>like_tag[]=tech&like_tag[]=mobile</code>"
params:
- key: feed_id
desc: "ID of feed for the classifier."
required: true
example: "42"
- key: "like_[TYPE]"
desc: "Positive score for TYPE <- [tag, author, title, feed]"
optional: true
example: "like_author=<br />Samuel Clay"
- key: "dislike_[TYPE]"
desc: "Negative score for TYPE <- [tag, author, title, feed]"
optional: true
example: "dislike_title=<br />New York Yankees"
- key: "remove_like_[TYPE]"
desc: "Clear score for a classifier."
optional: true
example: "remove_like_author=<br />Samuel Clay"
- key: "remove_dislike_[TYPE]"
desc: "Functionally the same as <code>remove_like_[TYPE]</code>."
optional: true
example: "remove_dislike_title=<br />New York Yankees"
- "import/export":
- url: /import/opml_export
method: GET
short_desc: "Download backup of feeds as an OPML file."
long_desc:
- "Download a backup of feeds and folders as an OPML file."
- "Contains folders and feeds in XML; useful for importing in another RSS reader."
- url: /import/opml_upload
method: POST
short_desc: "Upload an OPML file."
long_desc:
- "Upload an OPML file."
params:
- key: file
desc: "The OPML file in XML format."
required: true