If you can't find what you need here, see the Leanpub FAQ, the Leanpub Author FAQ, The Leanpub Manual, The Leanpub Authors Forum, The Markua Manual or The Leanpub Flavoured Markdown Manual. If none of those help, please Contact Us.

The Leanpub API

IMPORTANT NOTE: As of December 8, 2025, the Leanpub API is being overhauled, and the information below is outdated. Please do not try use our API for the next 2 months or so until we finish updating it. When the Leanpub API is working properly again, these docs will be updated below and this notice will go away.

Terms

Using the Leanpub API requires a Pro plan. To upgrade to a Pro plan, please go here.

All use of the Leanpub API must be authenticated with an API key.

Access to the Leanpub API may be revoked for any user, at any time, for any reason. In other words, please don't hammer our servers :)

Authentication

Getting your API key

You need to get an API key to start using the API. Go here to get one. Note that you typically need a Pro plan to get an API key. You can also get an API key if you are the author of a book for an organization which has an Organization Pro Plan, but in that case your API key will only work for that book.

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. A subset preview only generates a PDF, to go as fast as possible.

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.

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 organization logo...",
  "status": "working",
  "name": "Publish scotttest99",
  "time": 1376073552,
  "options": {
    "requested_by": "peter@leanpub.com",
    "release_notes": "this is a test\n\nwith two lines",
    "slug": "scotttest99",
    "action": "publish",
    "email_readers": true
  }
}

Getting Book Summary Information

You can get information about a book using curl with your API key:

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

Like all Leanpub API calls, this requires authentication. We only show you information about books where you are one of the authors (or if the book is published by an organization, and you are one of the editors).

Getting sales data

Summary Sales Data

You can get a summary of your sales and royalties at

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

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

Here's an example with curl:

curl "https://leanpub.com/SLUG/royalties.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

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

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:

coupon_code (Required): The coupon code for this coupon. This must be unique for your book.
package_discounts_attributes (Required): 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 (Required): The date the coupon is valid from. Formatted like YYYY-MM-DD.
end_date (Optional): The date the coupon is valid until. Formatted like YYYY-MM-DD.
max_uses (Optional): The max number of uses available for a coupon. An integer. Null means unlimited.
note (Optional): A description of the coupon. This is just used to remind you of what it was for.
suspended (Optional): 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": {"coupon_code":"coupon-code-123456","package_discounts_attributes":[{"package_slug":"book","discounted_price":0.0}], "start_date":"2013-12-28"}}' \
  "https://leanpub.com/thes3cookbook/coupons.json?api_key=YOUR_API_KEY"

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" \
https://leanpub.com/YOUR_BOOK/coupons.json

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

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

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"

curl "https://leanpub.com/u/USERNAME/reader_emails.json?api_key=API_KEY&purchase_type=book"

Getting a List of Your Readers' Emails

You can get a list of the email addresses of those readers who have decided to share their email with you by making a GET request to https://leanpub.com/u/USERNAME/reader_emails.json?api_key=YOUR_API_KEY. This returns a JSON formatted array of user emails.

These are the parameters:

api_key (Required): Your api key. This must be the api key for the user specified by USERNAME in the url.
purchase_type (Optional): The accepted values for this are book, course or all returning the list for your books, courses or both respectively. If no purchase_type is provided, the default is all.

For example a query would look like:

curl "https://leanpub.com/u/USERNAME/reader_emails.json?api_key=API_KEY&purchase_type=book"

This would return like:

[
  "someuser@gmail.com",
  "other.user@outlook.com"
]

Where "someuser@gmail.com" and "other.user@outlook.com" are emails of readers who have shared their email with you.

Previewing and Publishing Your Course

Your course's slug

If you have self published your course you'll need to know your course's slug. It's the part of the URL for your course after https://leanpub.com/c/. E.g. if your course is found at https://leanpub.com/c/your_course, then your book's slug is your_course.

If your course is published under an organization on Leanpub then you will need both the course and organization slug. If your course is published under an organization its landing page URL will look like https://leanpub.com/courses/ORGANIZATION/SLUG so if your course is found at https://leanpub.com/courses/your_organization/your_course the organization slug would be your_organization and the course slug would be your_course.

If your course is published under a university on Leanpub then you will need both the course and university slug. If your course is published under a university its landing page URL will look like https://leanpub.com/universities/courses/UNIVERSITY/COURSE so if your course is found at https://leanpub.com/universities/courses/your_university/your_course the university slug would be your_university and the course slug would be your_course.

Previewing

To start a preview of your course, you POST to https://leanpub.com/c/SLUG/preview.json if your course is self-published or https://leanpub.com/c/ORGANIZATION/SLUG/preview.json if your course is under an organization replacing ORGANIZATION slug with UNIVERSITY slug if your course is under a university and passing api_key as part of the post data. Here's some examples with cURL:

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

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

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

Publishing

To publish your course, you POST to https://leanpub.com/c/SLUG/publish.json if your course is self-published or https://leanpub.com/c/ORGANIZATION/SLUG/publish.json if your course is under an organization replacing ORGANIZATION slug with UNIVERSITY slug if your course is under a university and passing api_key as part of the post data. Here's some examples with cURL:

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

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

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