Urls | API v1 Documentation

- Urls
- Types

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
filterCuratedTopicsByCreationDateFrom: timestamp optional - default to 0 (unix epoch). Filter curated topics by creation date.
filterCuratedTopicsByCreationDateTo: timestamp optional - default to 2^63. Filter curated topics by creation date.

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
curablePage: int optional, default to 0 - for this topic, this parameter is ignored if the current user is not the curator of this topic - get a given page of curable posts
order: string mandatory if "since" parameter is not specified - sort order of the curated posts, can be "tag" (see below), "search" (filter result on query "q" mandatory - see below), "curationDate", "user" (same order as seen in the scoop.it website)
tag: string[] mandatory if "order"=="tag"
q: string mandatory if "order"=="search" - the query to use to search in the topic
since: timestamp - only retrieve curated post newer than this timestamp
to: timestamp optional - used with "since" parameter, retrieve curated posts posts older then this timestamp
ncomments: int optional, default to 100 - each curated post found in this topic
showScheduled: boolean optional, default to false - if true, the response will include the scheduled posts

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"
resolveUrl: boolean optional, default to false - title, content and imageUrl will be automatically resolved if not set
title: string - title of the post (automatically resolved if not set and resolveUrl parameter is true)
url: string - the url of the post
content: string - the content of the post (automatically resolved if not set and resolveUrl parameter is true)
insight: string optional
imageUrl: string - the picture url of the post (automatically resolved if not set and resolveUrl parameter is true)
publicationDate: long - the publication date of the original article (number of milliseconds since 1970-01-01 00:00:00 UTC)
topicId: long - the destination topic id
tag: string[] optional - list of tags to apply to the post.
shareOn: json optional - 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" } ]
directLink: boolean optional - if set to 'true', links in the sharing will be direct.
scheduleDate: long optional - the date the post should be published, along with the shares (number of milliseconds since 1970-01-01 00:00:00 UTC). You must have the right to schedule posts, see our pricing page for details.

* 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" } ]
directLink: boolean optional - if set to 'true', links in the sharing will be direct.
topicId: long optional - if specified, the post will be published to this topic
scheduleDate: long optional - the date the post should be published, along with the shares (number of milliseconds since 1970-01-01 00:00:00 UTC). You must have the right to schedule posts, see our pricing page for details.

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

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
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" } ]
directLink: boolean optional - if set to 'true', links in the sharing will be direct.
scheduleDate: long optional - the date the post should be published, along with the shares (number of milliseconds since 1970-01-01 00:00:00 UTC). You must have the right to schedule posts, see our pricing page for details.

Returns

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

Share Action

Parameters

id: long - post id
shareOn: json - 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" } ]
directLink: boolean optional - if set to 'true', links in the sharing will be direct.

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 posts. By default, the posts are retrieved from the followed topic of the authenticated user.

Parameters

sort: string optional - method used for sorting posts, can be "rss" (by default), post are ordered like in the RSS feed, or "timeline", posts are ordered like in the "My followed scoops" tab in a scoop.it user profile,
topicIds: long[] optional - a list of topic ids that will be used to create the compilation
topicGroupId: long optional - create the compilation from topics in this topic group
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"
includeEmptyTopics: bool optional, default to false - also returns topics having no posts. only for type="topic"

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 }

GET /api/1/sse

Get the configuration of the Smart Source Engine for a topic

Parameters

topic: long - the id of the topic

Returns

{ "active" : boolean - state of the SSE "keywords" : string[] - the list of configured keywords }

POST /api/1/sse

Edit the configuration of the Smart Source Engine for a topic

Parameters

topic: long - the id of the topic
active: boolean optional - if the parameter is set, it will change accordingly the state of the SSE
keyword: string[] optional - if the parameter is set, it will be the news set of keywords used by the SSE

Returns

{ "active" : boolean - state of the SSE "keyword" : string[] - the list of configured keywords }

GET /api/1/se

Get list and the configuration of all available suggestion engines associated to the connected user

Returns

{ "suggestion_engines" : suggestion_engine[] - the suggestion engine associated to the connected user }

POST /api/1/se

Update the configuration of a suggestion engine

Parameters

id: long - the id of the suggestion engine to update
sorter: string optional - the sorter to use: "relevance", "freshness" or "popularity"
maxSuggestionAge: int optional - the maximum number of days for the age of a suggestion. -1 for no maximum
keywords: string[] - the list of configured keywords
includedDomains: string[] optional - the list of url domains to include
excludedDomains: string[] optional - the list of url domains to exclude
containsAllKeyword: string[] optional - the list of keywords which all must match the suggestions
containsAnyKeyword: string[] optional - the list of keywords which any should match the suggestions
doesNotContainKeywords: string[] optional - the list of keywords which must not match the suggestions

Returns

{ "updated" : boolean - is true if the suggestion has been updated }

GET /api/1/se/{engine_id}/sources

List all user managed source of the given suggestion engine.

Returns

{ "sources" : source[] - an array of all user managed source for this suggestion engine }

DELETE /api/1/se/{engine_id}/sources/{source_id}

Delete a user managed source from a suggestion engine.

Returns

{ "success" : boolean }

POST /api/1/se/{engine_id}/sources/{source_id}

Update the name of a user managed source.

Parameters

name: string - the name to assign to the source, if no string or an empty string is given, the source will be renamed using its default name.

Returns

{ "success" : boolean }

PUT /api/1/se/{engine_id}/sources

Create a user managed source.

Parameters

name: string - optional - the name to assign to the source, if no string or an empty string is given, the source will be named using its default name.
type: string - the type of the source to create.
rssUrl: string - url of the rss feed (required if type==rss)
twitterUser: string - twitter user (required if type==twitter_follow_user)
twitterSearchQuery: string - search query (required if type==twitter_search)
twitterListName: string - list name (required if type==twitter_list)
twitterListOwner: string - list owner name (required if type==twitter_list)
webpageUrl: string - webpage url (required if type==webpage)
query: string - advanced search query (required if type==advanced_search)

Returns

{ "source : source - the created source }

GET /api/1/sugs

Get the list of suggestions associated with a suggestion engine

Parameters

id: long - the id of the suggestion engine
savedSearchId: string optional - the id of the saved search
count: int optional - number of suggestions to return (default 100, max 1000)

Returns

{ "sugs" : < sug[] > - the suggestions }

POST /api/1/sugs

Request for an update of a list of suggestions. It does the same as the GET operation but upon the provided sugIds, the method avoid transmitting the content of suggestions

Parameters

id: long - the id of the suggestion engine
sugId: string[] - the ids of the suggestions existing on the client side
savedSearchId: string optional - the id of the saved search

Returns

{ "sugs" : < sug[] > - the refreshed list of suggestions. If a suggestion is part of returned list and is part of the provided list of ids, only its id is present in the returned list. }

GET /api/1/recipients-list

List Recipients lists

Returns

{ "lists" : < recipients_list[] > - The recipients list that can be listed with your authentication credentials }

POST /api/1/recipients-list

Subscribe or unsubscribe recipients to a recipients list

Parameters

id: long - the id of recipients list
email: string - the email to subscribe/unsubscribe
action: string "subscribe" or "unsubscribe" - the action to perform

Returns

{}