Introduction | API v1 Documentation

The Scoop.it API let the programmer access to the following functionalities of the Scoop.it platform:

• - read the profile of a User
• - read some data of a Topic
• - read some data of a Post
• - read notifications
• - perform actions on topics and posts

Scoop.it supports both OAuth 1.0 Protocol (RFC 5849) and OAuth 2.0 protocol to authenticate the application and the Scoop.it users logged in your application. You can generate the OAuth tokens for your application using the Application page.

HTTP requests may be sent anonymously to the backend or authenticated for a particular user (ie on behalf of a particular user). See OAuth documentation to have a complete description of how sending signed HTTP requests with OAuth. Our OAuth 1.0 implementation does not support PLAINTEXT signatures.

The clock of the machine your application is running on must be correct. Otherwise, the access of Scoop.it API will always be denied for this machine.

Request authentication is done though the Authorization HTTP header. It must be "Bearer <your_access_token>"

To make anonymous API request, you can get an access token using the client credentials grant type. To make authenticated request on the behalf of a Scoop.it user you will need to get an access token for that user. See the athorization code grant documentation.

Note that access tokens may expire and may need to be refreshed, see refresh token documentation.

When doing HTTP requests with OAuth, two authentication modes can be used:

- Anonymous Mode (the requests are only signed with the consumer token of your application)
- Authenticated Mode (the requests are signed by the consumer token of your application and a user access token: your application does requests on the behalf of a Scoop.it user)

A large part of data retrieval is available in anonymous mode. See the Urls documentation for a complete list of which calls allowed in Anonymous Mode.

Every modification to Scoop.it data (aka POST requests) must be done in Authenticated Mode.

API calls are REST HTTP requests sharing some basic properties.

Requests must be encoded in UTF-8. So the requests parameters in the query string or the post parameter must be UTF-8 encoded.

If the OAuth authentication is not successful, the Content Type of the response will always be application/x-www-form-urlencoded. This provides a basic way of detecting OAuth issues.

If the OAuth authentication is successful, the Content Type of the response will always be application/json, except if the HTTP status code is 502 (Proxy Error) or 503 (Service Unavailable). So except for the last two statuses, the response body will contain a JSON encoded object.

The response body is always encoded in UTF-8.

HTTP Status codes meaning:

200 (OK)	The operation was successful.
400 (Bad Request)	Something is wrong in the request sent to Scoop.it (eg: invalid data type, missing parameters...)
401 (Unauthorized)	The requested operation is not allowed in Anonymous Mode
403 (Forbidden)	The requested operation is forbidden for the current user.
404 (Not Found)	The requested resource is not found.
405 (Method Not Allowed)	The HTTP method is not allowed for this url.
503 (Service Unavailable)	Something wrong happened on our end, please try again later.

Your application should support gzip compression to reduce bandwidth consumption and thus speed up api calls. You can enable gzip compression by adding a HTTP request header "Accept-Encoding: gzip,deflate" to each request your application does to our servers.