Urls | API v1 Documentation

API URL

The base url to request the api is:
https://www.scoop.it

GET /api/1/profile

Access a user's profile.

Parameters

id
long optional - the id of the user to lookup - defaults to the current user
shortName
string optional - the shortName of the user to lookup - defaults to the current user
curated
int optional - default to 0, number of curated posts to retrieve for each topic present in user data
curable
int optional - default to 0, number of curable posts to retrieve for each topic the current user is the curator (so it should not be specified if the "id" parameter is specified)
ncomments
int optional - default to 0, the maximum number of comments to retrieve for each curated post found in each topic present in user data
getCuratedTopics
bool optional - default to true. returns or not list of curated topics
getFollowedTopics
bool optional - default to true. returns or not list of followed topics
getTags
bool optional - default to true. returns or not list of tags for each returned topic
getCreator
bool optional - default to true. returns or not creator of each returned topic
getStats
bool optional - default to true. returns or not stats for each returned topic

Returns

{ "user" : < user > - the user "stats" : < "v" : int - number of views on the user's content "vp" : int - number of views progression on the user's content "uv" : int - DEPRECATED - number of unique visitors on the user's content "uvp" : int - DEPRECATED - number of unique visitors progression on the user's content > }

GET /api/1/topic

Access topic data.

Parameters

id
long required, unless 'urlName' is provided - the id of the topic to lookup
urlName
string required, unless 'id' is provided - the urlName of the topic to lookup
curated
int optional, default to 30 - number of curated posts to retrieve for this topic
page
int optional, default to 0
curable
int optional, default to 0 - for this topic, this parameter is ignored if the current user is not the curator of this topic
order
string mandatory if "since" parameter is not specified - sort order of the curated posts, can be "tag" (see below), "curationDate", "user" (same order as seen in the scoop.it website)
tag
string mandatory if "order"=="tag"
since
timestamp - only retrieve curated post newer than this timestamp
ncomments
int optional, default to 100 - each curated post found in this topic
Curated and curable parameters are exclusive: you cannot set both. Since parameter is based on publication date for curable posts and on curation date for curated posts.

Returns

{ "topic" : < topic > - the topic }

POST /api/1/topic

Perform actions on a topic. Use the "action" request parameter to perform one of the action below:

Actions

edit
edit a topic
reorder
reorder curated posts
follow
follow this topic
unfollow
unfollow this topic
markread
mark this topic as read (reset the "unreadPostCount" field)

Edit Action

Parameters

action
string "edit"
id
long mandatory - the topic id
name
string optional
description
string optional
lang
string optional, the new language of the topic (the iso 639 code) - (simplified/traditionnal), specify the full Locale (eg: zh_CN or zh_TW)

Returns

{ "topic" : < topic > - the topic }

Reorder Action

Parameters

action
string "reorder"
id
long mandatory - the topic id
postId
long[]- multiple request parameter of posts belonging to this topic in the new order it must appear in the website (aka the "user" order)
start
int optional, default to 0

Returns

{ }

Follow, Unfollow and Markread Actions

Parameters

action
string "follow", "unfollow" or "markread"
id
long - the topic id

Returns

{ }

GET /api/1/post

Access a post data.

Parameters

id
long - id of the post
ncomments
int optional, default to 100 - this post

Returns

{ "post": < post > - the post. }

POST /api/1/post

Perform an action on a post or create a post. Use the "action" request parameter to perform one of the action below:

Actions

prepare
prepare a new post (retrieve data from an url)
create
create a new post
comment
comment a post
thank
thank a post
accept
accept a post (aka curate the post, aka publish the post)
forward
forward a post to another topic (do a suggestion to another user)
refuse
refuse a post
delete
delete a post
edit
edit a post
pin
pin a post to its topic
rescoop
re-scoop a post from a topic to another one
share
share a post (on twitter, facebook...)

Prepare Action

Parameters

action
string "prepare"
url
string - the url of the post
{ "post": < post >* - the prepared post: it contains only a limited amount of data }
* only a limited subset of the data normally found in post is returned.

Create Action

Parameters

action
string "create"
title
string - title of the post
url
string - the url of the post
content
string - the content of the post
insight
string optional
imageUrl
string - the picture url of the post
topicId
long - the destination topic id
tag
string[] optional - list of tags to apply to the post.
shareOn
json - if the current user is belong to topic's curatorsarray of objects representing sharers to publish the post on. eg:
[ { "sharerId": "twitter", "cnxId": 12, "text": "The Tweet #foo #bar http://sco.lt/..." }, { "sharerId": "facebook", "cnxId": 26, "text": "The Facebook Text" } ]
* if < sharer > represented by its sharerId and cnxId has the boolean mustSpecifyShareText set to true, a mandatory "text" field is required specifying the text to publish. The url of the post can be specified using the placeholder "http://sco.lt/..."

Returns

{ "post": < post > - the post. }

Comment Action

Parameters

action
string "comment"
id
long - post id
commentText
string - the comment

Returns

{ }

Thank Action

Parameters

action
string "thank"
id
long - post id

Returns

{ "thankCount": int - the number of thanks for this post "thanked": boolean - true if the action post has not yet been thanked by the current user }

Accept Action

Parameters

action
string "accept"
id
long - post id
title
string optional - new of the post
content
string optional - new content of the post
insight
string optional
imageUrl
string - picture url of the post
tag
string[] optional - list of tags to apply to the post.
shareOn
json optional - to publish the post on. eg:
[ { "sharerId": "twitter", "cnxId": 12, "text": "The Tweet #foo #bar http://sco.lt/..." }, { "sharerId": "facebook", "cnxId": 26, "text": "The Facebook Text" } ]
topicId
long optional - if specified, the post will be published to this topic
* if < sharer > represented by its sharerId and cnxId has the boolean mustSpecifyShareText set to true, a mandatory "text" field is required specifying the text to publish. The url of the post can be specified using the placeholder "http://sco.lt/..."

Returns

{ "post": < post > - the post, "curablePostCount": < long > - the number of curable post count of the post topic, }

Forward Action

Parameters

action
string "forward"
id
long - post id
title
string optional - new title of the post
content
string optional - new content of the post
insight
string optional - the insight of the curator
imageUrl
string - picture url of the post
shareOn
json optional - to publish the post on. eg:
[ { "sharerId": "twitter", "cnxId": 12, "text": "The Tweet #foo #bar http://sco.lt/..." }, { "sharerId": "facebook", "cnxId": 26, "text": "The Facebook Text" } ]
topicId
long optional - if specified
* if < sharer > represented by its sharerId and cnxId has the boolean mustSpecifyShareText set to true, a mandatory "text" field is required specifying the text to publish. The url of the post can be specified using the placeholder "http://sco.lt/..."

Returns

{ "post": < post > - the post. }

Refuse Action

Parameters

action
string "refuse"
id
long - post id
reason
string optional - for an user suggestion, the reason why this post has been refused: it will be included in the notification email.

Returns

{ "curablePostCount": < long > - the number of curable post count of the post topic, }

Delete Action

Parameters

action
string "delete"
id
long - post id

Returns

{ }

Edit Action

Parameters

action
string "edit"
id
long - post id
tag
string[] optional - list of tags to apply to the post. To remove all, specify only one empty "tag" parameter
title
string optional - new title of the post
content
string optional - new content of the post
insight
string optional - the insight of the curator
imageUrl
string - picture url of the post

Returns

{ "post": < post > - the post. }

Pin Action

Parameters

action
string "pin"
id
long - post id

Returns

{ }

Re-Scoop Action

Parameters

action
string "rescoop"
id
long - post id
destTopicId
long - id of the destination topic.
tag
string[] optional - list of tags to apply to the post. To remove all, specify only one empty "tag" parameter
title
string optional - new title of the post
content
string optional - new content of the post
insight
string optional - the insight of the curator
imageUrl
string - picture url of the post

Returns

{ "post": < post > - the post on the destination topic. }

Share Action

Parameters

id
long - post id
shareOn
json optional - to publish the post on. eg:
[ { "sharerId": "twitter", "cnxId": 12, "text": "The Tweet #foo #bar http://sco.lt/..." }, { "sharerId": "facebook", "cnxId": 26, "text": "The Facebook Text" } ]
* if < sharer > represented by its sharerId and cnxId has the boolean mustSpecifyShareText set to true, a mandatory "text" field is required specifying the text to publish. The url of the post can be specified using the placeholder "http://sco.lt/..."

Returns

{ }

GET /api/1/test

Test authentication credentials.

Parameters

Returns

{ "connectedUser": < user > - the current connected user, or null in anonymous mode }

GET /api/1/notifications

Notifications for the current user

Parameters

since
timestamp - only new notification from this timestamp will be returned

Returns

{ "notifications": < notification[] > }

GET /api/1/compilation

Get a compilation of followed topics of the current user.

Parameters

sort
string optional - method used for sorting posts, can be "rss" (by default), post are ordered like in the RSS feed of the users followed topics, or "following", posts are ordered like in the Explore page,
since
timestamp - no posts older than this timestamp will be returned
count
int - maximum number of posts to return
page
int optional, default to 0 - page number of posts to retrieve
ncomments
int optional, default to 100 - the maximum number of comments to retrieve for each returned post
getTags
bool optional, default to true - returns or not list of tags for each returned post.
getTagsForTopic
bool optional, default to true - returns or not tags for topic of each returned post
getStatsForTopic
bool optional, default to true - returns or not stats for topic of each returned post

Returns

{ "posts": < post[] > }
Note that the topic field is expanded for all posts.

GET /api/1/search

Search for users, topics or posts.

Parameters

type
string - type of object searched: "user", "topic" or "post"
query
string - the search query
count
int optional, default to 50 - the number of item per page
page
int optional, default to 0 -the page number to return, the first page is 0
lang
string optional, default to "en" - the language of the content to search into
topicId
long optional - the id of the topic to search posts into
getTags
bool optional, default to true - returns or not list of tags for each returned topic / post. only for type="topic" or type="post"
getCreator
bool optional, default to true - returns or not creator of each returned topic. only for type="topic"
getStats
bool optional, default to true - returns or not stats for each returned topic. only for type="topic"
getTagsForTopic
bool optional, default to true - returns or not tags for topic of each returned post. only for type="post"
getStatsForTopic
bool optional, default to true - returns or not stats for topic of each returned post. only for type="post"

Returns

{ "totalFound": int - the total number of results found. "users": < user[] > - users found (if applicable) "topics": < topic[] > - topics found (if applicable) "posts": < post[] > - posts found (if applicable) }

GET /api/1/resolver

Resolve an object (topic or user) given its short name.

Parameters

type
string "User" or "Topic"
shortName
string - a short name

Returns

{ "type": string - the requested type value, "id": long - id of the found resource }

GET /api/1/interest

Access interest data

Parameters

id
long required, unless 'shortName' and 'lang' are provided - the id of the interest to lookup
shortName
string required, unless 'id' is provided - the shortName of the interest to lookup
lang
string required, unless 'id' is provided, default to 'en' - the language of the interest to lookup
getTopics
bool optional - default to false. returns or not the list of topics in the interest
getUsers
bool optional - default to false. returns or not the list of users in the interest
getPosts
bool optional - default to false. returns or not the list of posts in the interest
page
int optional, default to 0 - the number of the page to return (zero based), if getTopics or getUsers or getPosts is true
count
int optional, default to 50 - the number of items per page, if getTopics or getUsers or getPosts is true
curated
int optional - default to 0, number of curated posts to retrieve for each topic (used when getTopics is true)
ncomments
int optional - default to 0, the maximum number of comments to retrieve for each post (when getPosts is true) or curated post found in each topic (when getTopics is true)
getTags
bool optional - default to false. returns or not list of tags for each returned topic (when getTopics is true) or post (when getPosts is true)
getCreator
bool optional - default to false. returns or not creator of each returned topic (used when getTopics is true)
getStats
bool optional - default to false. returns or not stats for each returned topic (used when getTopics is true)
getTagsForTopic
bool optional, default to false - returns or not tags for topic of each returned post (when getPosts is true)
getStatsForTopic
bool optional, default to false - returns or not stats for topic of each returned post (when getPosts is true)

Returns

{ "interest" : < interest > - the interest }

GET /api/1/interest-list

Get the list of interests

Parameters

lang
string optional, default to 'en' - the language of interests to get

Returns

{ "interests" : < interest[] > - interests for the specified language }