The Leanpub API

Authentication

Getting your API key

You need to get an API key to start using the API. Go to your author dashboard, click on the "Account tab" and search for the API key section near the bottom (it will only be visible if you are signed up as an author).

Click on the button that says "Enable the Leanpub API" and copy the API key.

Using your API key

You need to send your API key on every API request you make. For GET requests, append it as a query string with a key of api_key:

GET https://leanpub.com/some/path?api_key=YOUR_API_KEY

For posts, you can also include the API key as part of the post data with a key of api_key. Here's an example in cURL:

curl -d "api_key=YOUR_API_KEY" https://leanpub.com/some/path

Your book's slug

You'll need to know your book's slug. It's the part of the URL for your book after https://leanpub.com/. E.g. if your book is found at https://leanpub.com/your_book, then your book's slug is your_book.

Previewing and Publishing

Previewing.

To start a preview of your book, you POST to https://leanpub.com/SLUG/preview.json passing api_key as part of the post data. Here's an example with cURL:

curl -d "api_key=YOUR_API_KEY" https://leanpub.com/SLUG/preview.json

To preview a subset of your book using Subset.txt, post to https://leanpub.com/SLUG/preview/subset.json, passing the api_key as usual.

curl -d "api_key=YOUR_API_KEY" https://leanpub.com/SLUG/preview/subset.json

Previewing a single file

Sometimes you just want to take a look at the file you are working on and don't want to mess around with Subset.txt or anything like that. You can do that with the Single File generation API.

To use it, make a post to https://leanpub.com/SLUG/preview/single.json with a Content-Type header of text/plain and the body of the post containing the Markdown you want to generate. We will place the resulting PDF in the previews folder of your Dropbox, with a name of SLUG-single-file.pdf.

Getting the newlines working when posting with CURL is a bit complicated, so we'll use a Ruby script as an example this time. To use it, set an environment variable called LEANPUB_API_KEY to your Leanpub API key:

export LEANPUB_API_KEY="yourapikey"

Then call the script like this:

./generate_single_file <book_slug> <path_to_file>

e.g.

./generate_single_file thes3cookbook /path/to/some/markdown.txt

here's the script:

#!/usr/bin/env ruby
require "httpclient"

slug = ARGV[0]
filename = ARGV[1]
api_key = ENV["LEANPUB_API_KEY"]

content = File.read(filename)
headers = { "Content-Type" => "text/plain"}

url = "https://leanpub.com/#{slug}/preview/single.json?api_key=#{api_key}"
HTTPClient.new.post(url, :body => content, :header => headers)

Publishing

To publish your book, you POST to https://leanpub.com/SLUG/publish.json with your api key as part of the post data. This will publish without emailing your readers. Here's an example with cURL:

curl -d "api_key=YOUR_API_KEY" https://leanpub.com/SLUG/publish.json

If you want to email readers and add some release notes, add keys for publish[email_readers] and publish[release_notes]. The release notes should be URL encoded.

curl -d "api_key=YOUR_API_KEY" -d "publish[email_readers]=true" -d "publish[release_notes]=please+let+me+know+what+you+think" https://leanpub.com/SLUG/publish.json

Getting the job status

Once you have started a preview or publish, you can get the status of the current job for your book by doing a GET on https://leanpub.com/SLUG/job_status.json with your api key as a query param:

curl "https://leanpub.com/SLUG/job_status?api_key=YOUR_API_KEY"

The result is a JSON response that looks like this:

{
  "num": 8,
  "job_type": "GenerateBookJob#preview",
  "total": 28,
  "message": "Downloading publisher logo...",
  "status": "working",
  "name": "Publish scotttest99",
  "time": 1376073552,
  "options": {
    "requested_by": "[email protected]",
    "release_notes": "this is a test\n\nwith two lines",
    "slug": "scotttest99",
    "action": "publish",
    "email_readers": true
  }
}

the num and total keys can be used to say things like "you are on step num of total".

You can poll this to see what's happening, but please don't poll more than every five seconds or so. You will get an empty JSON object when the job is complete.

Getting the Latest Version of your Book

You can get the latest version of your book using the preview_url and published_url returned by the book summary information API. These are also the URLs on the "Download Latest Preview" and "Download Latest Version" pages for your book (https://leanpub.com/YOUR_BOOK/preview/links and https://leanpub.com/YOUR_BOOK/publish/download_latest_version). These URLs never change, so you only need to get them once per book. They are also something you should keep secret: if someone has these URLs, they can get your book for free.

The only trick is that you're going to have to follow a redirect to Amazon S3. If you're using curl, that's as simple as adding the `-L` flag to your curl command:

  curl -L https://leanpub.com/s/some-long-uuid.pdf > yourbook.pdf
  curl -L https://leanpub.com/s/some-long-uuid.epub > yourbook.epub
  curl -L https://leanpub.com/s/some-long-uuid.mobi > yourbook.mobi

Getting Book Summary Information

You can get information about a book at

https://leanpub.com/SLUG.json

This does not require authentication. If you do provide an API key, and you are an author of the book, then we will also give you the total copies sold and revenue for the book, as well as the URLs for downloading the current preview and published version of your book in epub, pdf and mobi formats.

Here are two examples using curl with and without the API key:

curl https://leanpub.com/SLUG.json

curl https://leanpub.com/SLUG.json?api_key=YOUR_API_KEY

The result is a JSON response that looks like this:

{
  "slug": "thes3cookbook",
  "subtitle": "Get cooking with Amazon's Simple Storage Service",
  "title": "The S3 Cookbook",
  "about_the_book": "Amazon’s Simple Storage Service (S3) has been described as “Storage in the cloud”....",
  "author_string": "Scott Patten",
  "url": "http://leanpub.com/thes3cookbook",
  "title_page_url": "https://s3.amazonaws.com/titlepages.leanpub.com/thes3cookbook/original?1375318991",
  "minimum_price": "3.0",
  "suggested_price": "10.0",
  "page_count_published": 252,
  "total_copies_sold": 111382,
  "word_count_published": 43315
}

The page_count_published entry shows the number of pages in the currently published version, and will only be shown if the author has chosen to display the number of pages. Similarly, word_count_published shows the number of words in the currently published version and will only be shown if the author has chosen to display the number of words.

Here is what it will look like for an author who has authenticated:

  {
  "slug": "thes3cookbook",
  "subtitle": "Get cooking with Amazon's Simple Storage Service",
  "title": "The S3 Cookbook",
  "about_the_book": "Amazon’s Simple Storage Service (S3) has been described as “Storage in the cloud”....",
  "last_published_at": "2015-01-15T19:21:50Z",
  "meta_description": null,
  "page_count": 263,
  "page_count_published": 252,
  "total_copies_sold": 111382,
  "total_revenue": "1123334.14",
  "word_count": 43315,
  "word_count_published": 43315,
  "author_string": "Scott Patten",
  "url": "http://leanpub.com/thes3cookbook",
  "title_page_url": "https://s3.amazonaws.com/titlepages.leanpub.com/thes3cookbook/original?1435903728",
  "minimum_price": "3.0",
  "suggested_price": "10.0",
  "image": "https://s3.amazonaws.com/titlepages.leanpub.com/thes3cookbook/medium?1435903728",
  "possible_reader_count": 0,
  "pdf_preview_url": "http://leanpub.com/s/redacted-string.pdf",
  "epub_preview_url": "http://leanpub.com/s/redacted-string.epub",
  "mobi_preview_url": "http://leanpub.com/s/redacted-string.mobi",
  "pdf_published_url": "http://leanpub.com/s/another-redacted-string.pdf",
  "epub_published_url": "http://leanpub.com/s/another-redacted-string.epub",
  "mobi_published_url": "http://leanpub.com/s/another-redacted-string.mobi"
}

page_count_published is the page count of the latest published version. page_count is the page count of the latest previewed or published version. word_count_published and word_count are the same, but for word count (and yes, those revenue numbers are totally made up).

Getting sales data

Summary Sales Data

You can get a summary of your sales at

https://leanpub.com/SLUG/sales.json

or

https://leanpub.com/SLUG/sales.xml

Here's an example with curl:

curl "https://leanpub.com/SLUG/sales.json?api_key=YOUR_API_KEY"

All Sales Data

You can access data for all of your individualy purchases in JSON and XML format by doing a GET request to

https://leanpub.com/SLUG/individual_purchases.json

or

https://leanpub.com/SLUG/individual_purchases.xml

This data is paginated, and by default gives you your last 50 sales. Here's an example to get the last 50 sales of your book:

curl "https://leanpub.com/SLUG/individual_purchases.json?api_key=YOUR_API_KEY"

If you want to get the next 50 sales, request page 2 of your sales data like this:

curl "https://leanpub.com/SLUG/individual_purchases.json?api_key=YOUR_API_KEY&page=2"

Coupons

You can get information about the coupons for a given book and create new coupons for a book.

Getting a list of coupons for a book

To get a list of coupons, make a GET request to

https://leanpub.com/SLUG/coupons.json

or

https://leanpub.com/SLUG/coupons.xml

The response will include a list of all coupons for your book. Here is an example JSON response for a book with a single coupon:

[
  {
    "coupon_code": "NOT_A_REAL_COUPON",
    "created_at": "2013-04-17T22:12:58Z",
    "package_discounts": [
      {
        "package_slug": "book",
        "discounted_price": 2.0
      },
      {
        "package_slug": "teamedition",
        "discounted_price": 4.0
      }
    ],
    "end_date": "2016-05-17",
    "max_uses": null,
    "note": "This is not a real coupon",
    "num_uses": 12,
    "start_date": "2013-04-17",
    "suspended": false,
    "updated_at": "2013-04-17T22:12:58Z",
    "book_slug": "yourbook"
  }
]

Creating coupons

You can create coupons by POSTing to https://leanpub.com/SLUG/coupons.json.

You need to send the following data:

Name	Required?	Description
coupon_code	Yes	The coupon code for this coupon. This must be unique for your book.
package_discounts_attributes	Yes	An array of discounts, one for each package that you want this coupon to apply to. Each discount is an object with two keys: package_slug is the slug of the package that this discount applies to, and discounted_price is the amount that the package can be purchased for.
start_date	Yes	The date the coupon is valid from. Formatted like YYYY-MM-DD.
end_date	No	The date the coupon is valid until. Formatted like YYYY-MM-DD.
max_uses	No	The max number of uses available for a coupon. An integer. Null means unlimited.
note	No	A description of the coupon. This is just used to remind you of what it was for.
suspended	No	Whether or not the coupon is suspended. true or false.

You can send data as either form-encoded data or JSON. If you send JSON, you must set the Content-Type header to application/json.

Here is an example using curl with json data:

curl -H "Content-Type: application/json" -X POST \
-d '{"coupon_code":"coupon-code-123456","package_discounts_attributes":[{"package_slug":"book","discounted_price":0.0}], \
"start_date":"2013-12-28"}' "http://leanpub.com/thes3cookbook/coupons.json?api_key=YOUR_API_KEY"

If you use form-encoded data, then all of the fields must be prefixed with coupon. I.e., instead of sending up coupon_code, you send up coupon[coupon_code]. Here's an example:

curl -d "coupon[coupon_code]=coupon-code-123456" -d "coupon[discounted_price]=0.0" \
 -d "coupon[start_date]=2013-10-21" -d "api_key=YOUR_API_KEY" \
-d "coupon[package_discounts_attributes][][package_slug]=book"
-d "coupon[package_discounts_attributes][][discounted_price]=0.00"
https://leanpub.com/YOUR_BOOK/coupons.json

Updating Coupons

You can update a coupon by making a PUT request to https://leanpub.com/SLUG/coupons/COUPON_CODE.json. You use all of the same parameters as when you create a coupon, but none are required. Here is an example using curl:

curl -H "Content-Type: application/json" -XPUT -d '{"suspended":false}' \
"https://leanpub.com/SLUG/coupons/some_coupon_code.json?api_key=YOUR_API_KEY"