Home

Using the Scribd Platform API

Contents

1. Overview
2. User Authentication
3. Client Libraries
4. Usage Limits
5. Request Signing (optional)

For details see the → Platform API Reference

1. Overview

The Scribd API is a REST-like API with methods for uploading, converting, viewing, deleting, and searching documents.

All API requests are made by sending a request to the following address:

http://api.scribd.com/api

An example API request might look like:

http://api.scribd.com/api?method=docs.getList&api_key=758buxouy289mh4mhh1uf

All API requests must include the following 2 parameters: api_key and method.

Most requests can be simple HTTP GETs. This has the nice effect that you can test your API calls by just typing your request URL into your browser's address bar. However, the docs.upload method must be an HTTP Multi-Part POST because it sends a file. To embed documents, look at the Javascript API.

There are client libraries for the API in a number of languages. Also don't miss the tutorials.

2. User Authentication

Scribd's API has a very simple system for authenticating user accounts (note this is distinct from API accounts, which are authenticated simply by passing an api_key parameter). There are three choices for handling user authentication:

1. No user authentication

All API calls must be authenticated by passing your api_key, but they do not require additional user authentication. If you just pass the api_key, the API call will be made as if you, the Scribd user with the API account, executed them. This would be the natural authentication method for a book publishing company, for example, who would want all its books associated with its own account.

2. API sessions

API sessions are necessary for an application that is meant to be used by existing Scribd users, to act on their behalf. To use API sessions, have your application sign in as an existing Scribd user using the user.login method. Pass this method a username and password of a Scribd user, and it will return a session key. You can then use that session key with any document method to act as the user associated with the session. We suggest that you save previous session keys used by your application in a database to make it easy to switch between your application's users.

To use a session key, simply pass it as the value of the session_key parameter. For example:

http://api.scribd.com/api?method=docs.getList&api_key=758buxouy289mh4mhh1uf&session_key=sess-2ajcvmbqs5x1347h5yuu

3. The my_user_id parameter

This is intended to make it easy for web applications with their own user authentication systems to integrate with Scribd's user model. For example, if you have a website that allows job seekers to upload a resume, you could easily integrate your user model with ours, ensuring that each resume is attached to a sort of "phantom" Scribd user who represents the job seeker who uploaded it. Having this kind of user information will make searching and browsing with the API much easier for you and help keep things organized.

All you need to use this method is some unique identifier for each of your users like a username or user ID. Pass this unique identifier as the value of the parameter my_user_id to any document API method. The method will then be executed on behalf of a phantom Scribd user identified by the unique ID you gave us. For example:

http://api.scribd.com/api?method=docs.getList&api_key=758buxouy289mh4mhh1uf&my_user_id=fluffy19

3. Client Libraries

There are public client libraries for the Scribd API in Ruby, PHP, C#, and ActionScript. If you use one of these languages, using a client library will make the Scribd API much easier to use.

Ruby

Icon_package_getOfficial Ruby Client Library

Just run: sudo gem install rscribd

For more information, consult the RubyForge page.

Or try the Scribd_fu rails plugin, a Ruby on Rails plugin that streamlines interactions with the Scribd service.

Java

Icon_package_getOfficial Java Client Library
Download the jscribd source from GitHub.

PHP

Icon_package_getDownload PHP Client Library
Contributed by Robert Pottorff.

If you use PHP, you may well be interested in Rich Schu's PEAR PHP package.
PEAR package / GitHub source
You can install with: sudo pear install Services_Scribd-0.1.0

C# / .NET

Icon_package_getCodePlex page for the C# library
Contributed by Paul Duncan.

ActionScript 3.0

Icon_package_getGoogle Code page for the ActionScript library
Contributed by Mark Walters of DigitalFlipBook.com.

Python

Icon_package_getGoogle code version / Python package index
Contributed by Arkadiusz Wahlig.

Please contribute: We need more client libraries, so if you'd like to write your own, please

4. Usage Limits

The free version of the API has very generous upload usage limits. Most applications will never hit these usage limits. The free version provides:

  • Public documents: unlimited
  • Private documents: 50,000 documents per API account

There are no limits for applications that simply consume content by searching or browsing Scribd

Note that these limits refer to the total number of documents ever uploaded, so deleted documents continue to count against them.

For applications that need additional storage space, we provide paid accounts with a usage based pricing model similar to Amazon Web Services. Please contact for the latest pricing.

5. Request Signing (optional)

In Scribd's API, signing requests is an optional measure that offers increased security for your API account. Signing of requests protects against man-in-the-middle attacks, in which someone could intercept your communication with Scribd's servers, record your API key, and use that to access your API account themselves. If you are writing a desktop application (like a Windows app), signing is REQUIRED to maintain security. For most web applications it should not be necessary.

Scribd uses exactly the same signing method as the Flickr or Facebook API's, so if you have used those, you are already familiar with this process. To activate signing, go to your account options page and change the "Require API Signature" option.

At a technical level, signing an API request means appending a parameter api_sig. The value of api_sig is computed each time your application makes a request, using the values of the other parameters. Here is the algorithm you should use to compute the value of api_sig:

  1. Sort your argument list into alphabetical order based on the parameter name. (e.g. foo=1, bar=2, baz=3 sorts to bar=2, baz=3, foo=1)
  2. Concatenate your API secret key and argument name-value pairs (e.g. SECRETbar2baz3foo1)
  3. Calculate the md5() hash of this string
  4. Append this value to the argument list with the name api_sig, in hexidecimal string form (e.g. api_sig=1f3870be274f6c49b3e31a0c6728957f)

Obviously, you should not include the parameter api_sig, itself, in the first step when sorting your argument list - that would be circular. You should also not include the parameter file in the method docs.upload.