Fork me on GitHub

The ReadSocial API is documented below. View a demo of the ReadSocial API Web Client using As We May Think, by Vannevar Bush. You can download the Open Source Javascript Web Client from Github. There is also an Open Source iOS Library available there. The API is free to try - no membership account necessary. Just try the FREE test widget for anyone to use on their web content. Just paste this snippet into any page of content you want to activate:

(All data from the test widget will be tied to the ReadSocial App account, not your own.)

Getting Started

Use the test snippet above to quickly try it out on your content. If you have any questions, or are just confused, click on any paragraph in this page to attach questions or comments (feature not currenly available in IE).

To quickly get started using your own account with the API, go to your Settings page, and click on "Get Code." The code there will reference your own network, and any activity generated from pages using that code may be managed from your Dashboard. Just paste it into any page of content you want to activate.

Customizing the Source

To customize the open source Web Client, download the source from Github and install it on your site. Use the code from your settings page as a starting point, except when you call the main readsocial() function (see example above), you'll want to adjust the base configuration property to point to your own server, not the api.readsocial.net server. This will allow you to use your customized version of the code. Leave the api_base property set as it is.

Authentication and Security

Authentication is managed via one of two routes: OAuth Sessions via Twitter, Google or Facebook, or HTTP Basic Authorization provided by the requesting application. With Basic Auth, otherwise referred to as single sign on or app-based auth, it's up to the calling application to provide user details along with data objects written to the API.

Currently the API key and secret are only required for single sign-on calls (app-based authentication), and then only for actions which write data or create objects. All POSTed data should be JSON. The Content-Type and Accept headers must be set to "application/json" on all requests.

The SSL layer is available for all requests.

Using Single Sign On

To use Single Sign On, you must first install the open source web client codebase on your server.

You will configure your base config parameter as the scheme:host:port of the domain that will serve JS library files and other customized assets. the api_base config parameter should remain set to point the ReadSocial API server. Most data will still be served from that domain, with the exception of authenticated data. See below.

Single Sign On: Configuration of Servers

Authenticated requests and session info will be transferred from your own servers, with help from a proxy which forwards data and requests from/to the ReadSocial API servers.

We can help with this part of the integration. It requires a few simple server-side components which are likely to be very system/framework dependent. We don't provide libraries for this, but most modern languages and web protocol libraries make it fairly easy to implements these components.

Configuration Specifics


For single sign on, you need a GET URI /readsocial/authstatus that returns JSONP in the format:

      "user": {
            "uname":"Aaron Miller",

The JSONP method call must be identical to the method named above. The data represents the session of the requesting user (on your own system). The parameter net_id is your ReadSocial network. It corresponds with the key and secret you will use for transmission of authenticated data to/from our servers on the back end.


You will additionally need a GET URI /readsocial/login that takes the user to your own login page. This will only be accessible when the /readsocial/authstatus returns a session with its authed property set to false. You can store the URI that refers to your login URL and redirect back to it after login/signup is complete, or you can simply have your /readsocial/login action grab the callback parameter from the request itself, and redirect to that.


You also need a GET URI /readsocial/logout that de-authorizes your user's session and redirects back to the referring url.


Additionally, you will need a POST URI /readsocial/proxy. Each request to this will receive the data transport for posted comments or responses from the client, respectively. You are responsible for passing these transports along to the appropriate ReadSocial API endpoints on the back end, using your key and secret to authenticate the requests. Each data transport will contain an _endpoint property for your convenience which instructs which target the data is meant for.

Your proxy endpoint at /readsocial/proxy will simply read the _endpoint property of the data and pass the rest of the data along to that endpoint on the api.readsocial.net domain.

Once you've set up these endpoints, the client library will handle the rest, switching its operation to SSO instead of Oauth.


The UI library may be included in Epub files and has been successfully tested in iBooks. Other Epub reading systems that support scripting may also be compatible.

The markup you use in an Epub is as simple as this:

This has not been a scientist's war; it has been a war in which all
have had a part.  The scientists, burying their old professional
competition in the demand of a common cause, have shared greatly and
learned much.  It has been exhilarating to work in effective
partnership.  Now, for many, this appears to be approaching an end.
What are the scientists to do next?
<a class="readsocial-epublink">#future-of-science</a>
<a class="readsocial-epublink">#competition</a>

When the single-file version of the Javascript library is added to the Epub file, the anchor elements in the paragraph will be activated as ReadSocial hashgroup buttons in compatible reading systems.

The steps to activating ReadSocial in Epub content are:

  1. Add the all-in-one library file to the Epub. You will need to add it to the manifest as well as reference it in your content files.
  2. Add the hashgroup links to your content files, placing them inside the paragraphs you want to activate.
  3. Add a configuration block and a call to the readsocial bootstrap function in each content file you want activated (customize the container and partner_id properties to suit your own content, but make sure the use_iframe property is set to false):
  4. readsocial({
    	base: 'https://api.readsocial.net',
    	api_base: 'https://api.readsocial.net',
    	partner_id: 8,
    	container: '#contentdoc',
    	use_iframe: false

Tumblr Blogs

Currently the UI library will work with Tumblr blogs with minor modifications. We are working on support for other platforms too.

For more details on Tumblr integration and customization, we've compiled a few tips from real-world scenarios.

Note that some blog platforms do not create posts with p tags. Remember, your content must have paragraphs enclosed with p tags in order for the UI library to work properly. The back end API itself does not rely on p tags, but the UI client library does.

WordPress Blogs

If you're interested in using ReadSocial on a WordPress install, let us know. We have a plugin in development and would like to hear from interested parties.


Every paragraph on this page is enabled with ReadSocial (group name #readsocial-api-questions). Please feel free to attach questions of clarifications, and we will do our best to respond. If you have general questions not related to usage of the API, or anything else you want to know, be sure to check out our FAQ.

    Sexy API documentation from Swagger.