Introduction | API v1 Documentation

The API documented here is a work in progress. While we don't foresee any reasons to change url mapping or types or fields names, we may add some new fields, types or urls in the future.
If you have any comment or question,
please use the dedicated google group.

What this API can do?

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

Authentication

Scoop.it supports OAuth 1.0 Protocol (RFC 5849)
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 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.

Authentication Modes

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.

REST API

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.