Leanpub Header

Skip to main content
Go to Leanpub.comLeanpub

Leanpub API Documentation

The Leanpub API allows authors to programmatically preview, publish, and manage their books and courses.

Note: This documentation contains forward-looking statements within the meaning of the "we'll get to it eventually" securities regulations. Sections marked with ⚠️ describe planned functionality that is not yet implemented. These forward-looking statements involve known and unknown risks, including the risk that we got distracted by something shiny. Past API performance is not indicative of future results. Please consult your doctor before starting any new API integration.

(In all seriousness: We just shipped the largest update in Leanpub's 15+ year history, and this affected the API. We are in the process of restoring the API. This documentation is an attempt to capture what does work, what is broken, and what has been removed.)

Authentication

All API requests require authentication via an API key.

Getting Your API Key

  1. You need a Pro plan to access the API
  2. Go to your API Key settings to generate one
  3. Keep your API key secret—it provides full access to your books

Using Your API Key

Include your API key in every request using one of these methods:

Query parameter (GET requests):

GET https://leanpub.com/your-book.json?api_key=YOUR_API_KEY

Form data (POST/PUT requests):

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

JSON body (POST/PUT requests):

curl -H "Content-Type: application/json" \
  -d '{"api_key":"YOUR_API_KEY"}' \
  https://leanpub.com/your-book/preview.json

Book Information

Get Book Summary

Returns detailed information about a book.

GET https://leanpub.com/{slug}.json

Response:

{
  "slug": "your-book",
  "title": "Your Book Title",
  "subtitle": "An Optional Subtitle",
  "about_the_book": "Description of the book...",
  "author_string": "Author Name",
  "url": "https://leanpub.com/your-book",
  "title_page_url": "https://...",
  "image": "https://...",
  "minimum_paid_price": "9.99",
  "suggested_price": "19.99",
  "page_count": 150,
  "page_count_published": 148,
  "word_count": 45000,
  "word_count_published": 44500,
  "total_copies_sold": 1234,
  "total_revenue": "15000.00",
  "last_published_at": "2024-01-15T19:21:50Z",
  "meta_description": "SEO description",
  "possible_reader_count": 50,
  "pdf_preview_url": "https://leanpub.com/s/...",
  "epub_preview_url": "https://leanpub.com/s/...",
  "pdf_published_url": "https://leanpub.com/s/...",
  "epub_published_url": "https://leanpub.com/s/..."
}

The pdf_preview_url, epub_preview_url, pdf_published_url, and epub_published_url fields are secret URLs for downloading your book files. Keep them private.

Preview & Publish

Preview Book

Starts a full preview generation of your book.

POST https://leanpub.com/{slug}/preview.json

Response:

{
  "success": true
}

Preview Subset

Generates a preview using only the files listed in Subset.txt. This creates only a PDF for faster iteration.

POST https://leanpub.com/{slug}/preview/subset.json

Response:

{
  "success": true
}

Preview Single File

Generates a preview from raw Markdown content. Useful for previewing a single chapter without modifying Subset.txt. The output is saved as {slug}-single-file.pdf in your Dropbox previews folder.

POST https://leanpub.com/{slug}/preview/single.json
Content-Type: text/plain

# Chapter Title

Your markdown content here...

Response:

{
  "success": true
}

Publish Book

Publishes your book, making the latest version available to readers.

POST https://leanpub.com/{slug}/publish.json

Parameters:

Examples:

Publish without notifying readers:

curl -d "api_key=YOUR_API_KEY" \
  https://leanpub.com/your-book/publish.json

Publish and notify readers:

curl -d "api_key=YOUR_API_KEY" \
  -d "publish[email_readers]=true" \
  -d "publish[release_notes]=Fixed typos in chapter 3" \
  https://leanpub.com/your-book/publish.json

Publish with multi-line release notes (URL-encoded):

curl -d "api_key=YOUR_API_KEY" \
  -d "publish[email_readers]=true" \
  -d "publish[release_notes]=New+in+this+release%3A%0A%0A-+Fixed+typos%0A-+Added+chapter+4" \
  https://leanpub.com/your-book/publish.json

Response:

{
  "success": true
}

Get Job Status

Check the status of a running preview or publish job.

GET https://leanpub.com/{slug}/job_status.json

Response (job in progress):

{
  "num": 8,
  "total": 28,
  "job_type": "GenerateBookJob#preview",
  "message": "Generating PDF...",
  "status": "working",
  "name": "Preview your-book",
  "time": 1376073552,
  "options": {
    "requested_by": "you@example.com",
    "slug": "your-book",
    "action": "preview"
  }
}

Response fields:

The num and total fields can be used to display progress like "Step 8 of 28".

Response (job complete): Returns an empty object {} when no job is running.

Poll this endpoint to track progress, but limit requests to once every 5 seconds.

Sales & Royalties

Get Royalties Summary

Returns a summary of your book's sales and royalties.

GET https://leanpub.com/{slug}/royalties.json

Here's an example with curl:

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

Response:

{
  "total_royalties": 12500.00,
  "royalties_bundled": 500.00,
  "royalties_unbundled": 12000.00,
  "last_week_royalties": 250.00,
  "royalties_to_revenue_ratio": 0.80,
  "total_revenue": 15625.00,
  "revenue_bundled": 625.00,
  "revenue_unbundled": 15000.00,
  "total_copies_sold": 1234,
  "num_copies_sold_bundled": 50,
  "num_copies_sold_unbundled": 1184
}

Get Individual Purchases

Returns a paginated list of individual purchases for your book.

GET https://leanpub.com/{slug}/individual_purchases.json

Parameters:

Response:

[
  {
    "id": "123",
    "author_royalties": 8.00,
    "state": "paid",
    "payable_at": "2024-02-01T00:00:00Z",
    "purchased_package_id": "456",
    "free": false,
    "user_email": "reader@example.com",
    "username": "reader123"
  }
]

Coupons

List Coupons

Returns all coupons for a book.

GET https://leanpub.com/{slug}/coupons.json

Response:

[
  {
    "coupon_code": "LAUNCH50",
    "created_at": "2024-01-01T00:00:00Z",
    "package_discounts": [
      {
        "package_slug": "book",
        "discounted_price": 4.99
      }
    ],
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "max_uses": 100,
    "num_uses": 25,
    "note": "Launch promotion",
    "suspended": false,
    "book_slug": "your-book"
  }
]

Get Single Coupon

Returns details for a specific coupon.

GET https://leanpub.com/{slug}/coupons/{coupon_code}.json

Response:

{
  "coupon_code": "LAUNCH50",
  "created_at": "2024-01-01T00:00:00Z",
  "package_discounts": [
    {
      "package_slug": "book",
      "discounted_price": 4.99
    }
  ],
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "max_uses": 100,
  "num_uses": 25,
  "note": "Launch promotion",
  "suspended": false,
  "book_slug": "your-book"
}

Create Coupon

Creates a new coupon for your book.

POST https://leanpub.com/{slug}/coupons.json

Parameters:

Example (JSON):

curl -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "coupon": {
      "coupon_code": "SAVE50",
      "package_discounts_attributes": [
        {"package_slug": "book", "discounted_price": 4.99}
      ],
      "start_date": "2024-01-01",
      "end_date": "2024-12-31",
      "max_uses": 100,
      "note": "Half price promotion"
    }
  }' \
  https://leanpub.com/your-book/coupons.json

Example (form data):

curl -d "api_key=YOUR_API_KEY" \
  -d "coupon[coupon_code]=SAVE50" \
  -d "coupon[package_discounts_attributes][][package_slug]=book" \
  -d "coupon[package_discounts_attributes][][discounted_price]=4.99" \
  -d "coupon[start_date]=2024-01-01" \
  -d "coupon[end_date]=2024-12-31" \
  https://leanpub.com/your-book/coupons.json

Response: Returns the created coupon (see Get Single Coupon).

Update Coupon

Updates an existing coupon. Only include fields you want to change.

PUT https://leanpub.com/{slug}/coupons/{coupon_code}.json

Example:

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"api_key": "YOUR_API_KEY", "suspended": true}' \
  https://leanpub.com/your-book/coupons/SAVE50.json

Response: Returns the updated coupon (see Get Single Coupon).

Account

Verify API Key

Validates your API key and returns information about the authenticated user. Useful for testing your integration.

GET https://leanpub.com/current_user.json

Response:

{
  "username": "yourname",
  "email": "you@example.com"
}

Get Reader Emails

Returns email addresses of readers who have opted to share their email with you.

GET https://leanpub.com/u/{username}/reader_emails.json

Parameters:

Example:

curl "https://leanpub.com/u/yourname/reader_emails.json?api_key=YOUR_API_KEY&type=book"

Response:

[
  "reader1@example.com",
  "reader2@example.com"
]

Downloading Book Files

The book summary endpoint returns secret URLs for downloading your book files:

These URLs redirect to S3. Use the -L flag with curl to follow redirects:

curl -L "https://leanpub.com/s/your-secret-id.pdf" > book.pdf
curl -L "https://leanpub.com/s/your-secret-id.epub" > book.epub

Error Handling

HTTP Status Codes:

Error Response:

{
  "success": false,
  "errors": ["Coupon code already exists"]
}

Usage Guidelines

The API is designed for individual authors automating their publishing workflow. Please be reasonable:

API access may be revoked if we notice abusive patterns.

Your Book's Slug

Your book's slug is the URL-friendly identifier in your book's URL:

https://leanpub.com/your-book
                     ^^^^^^^^^ this is the slug

⚠️ Course API (Planned)

Not Yet Implemented: The Course API endpoints described below are planned but not yet available. This section documents our intended API design for course authors.

Leanpub courses can be previewed and published via the API, similar to books.

Your Course's Slug

Courses have different URL patterns depending on how they're published:

Preview Course

Starts a preview generation of your course.

Self-published course:

POST https://leanpub.com/c/{slug}/preview.json

Organization course:

POST https://leanpub.com/c/{organization_slug}/{slug}/preview.json

University course:

POST https://leanpub.com/c/{university_slug}/{slug}/preview.json

Examples:

# Self-published course
curl -d "api_key=YOUR_API_KEY" https://leanpub.com/c/your-course/preview.json

# Organization course
curl -d "api_key=YOUR_API_KEY" https://leanpub.com/c/your-org/your-course/preview.json

# University course
curl -d "api_key=YOUR_API_KEY" https://leanpub.com/c/your-university/your-course/preview.json

Response:

{
  "success": true
}

Publish Course

Publishes your course, making the latest version available to students.

Self-published course:

POST https://leanpub.com/c/{slug}/publish.json

Organization course:

POST https://leanpub.com/c/{organization_slug}/{slug}/publish.json

University course:

POST https://leanpub.com/c/{university_slug}/{slug}/publish.json

Examples:

# Self-published course
curl -d "api_key=YOUR_API_KEY" https://leanpub.com/c/your-course/publish.json

# Organization course
curl -d "api_key=YOUR_API_KEY" https://leanpub.com/c/your-org/your-course/publish.json

# University course
curl -d "api_key=YOUR_API_KEY" https://leanpub.com/c/your-university/your-course/publish.json

Response:

{
  "success": true
}

⚠️ XML Endpoints (Deprecated)

Deprecated: XML endpoints were available in the legacy API but are not supported in the current version. All API responses are now JSON-only.

The following XML endpoints existed in the previous API version:

If you have existing integrations that rely on XML responses, please migrate to the equivalent .json endpoints.