Leanpub has an API or "application programming interface" for authors who would like to do some actions without having to sign in to Leanpub and use our website.
In this article, we're going to show you how the API works, and some of the things you can use it to do.
(If you are on a Free or Standard plan, and you'd like to upgrade to Pro so you can use API, please go to your subscriptions page here.)
You don't need to be a programmer to use the API! This article is intended to show non-programmers how to use the API to be more efficient using Leanpub.
If there are any gaps in our explanation, please let us know by clicking the little icon you should see at the bottom right of the page, and sending us a message:
OK, here we go!
You will be using the Leanpub API through the "command line" on your computer. In this example, we're using a Mac, so the program we'll be using is called "Terminal".
To open Terminal, hit Command + Space and type "terminal" in the search option that will pop up on your screen. Select Terminal.app:
This will open Terminal. Yours will probably have a different color scheme, but here's how it will look:
(You'll notice that we blur some stuff in pictures throughout this tutorial. You can just ignore that!)
Next, you should navigate in Terminal to the folder where you work on your book on your computer.
Type cd and the folder name of the first folder in your folder hierarchy, and then keep doing the same thing until you to get to your book's folder.
For example, if you are working on your book in Dropbox, the "Dropbox" folder is probably at the top level or your home folder (or "home directory": "cd" stands for "change directory).
So, if you have a book in Dropbox, and the book's folder is named "my-book", the "path" would be like this:
Dropbox > my-book
If that were the folder path you wanted to follow on your computer, you would start by typing the following command in Terminal, and then hitting the Return key to execute the command:
cd Dropbox
That would take you to the "Dropbox" folder in Terminal.
Then, you would type the following and hit Return:
cd my-book
That would take you to the "my-book" folder in Terminal.
In the example below, we're using a book in Leanpub's GitHub writing mode, where the book folder is called sample-nonfiction-book and it is in a top-level folder called repos.
So, we type:
cd repos
...and hit Return, and then type:
cd sample-nonfiction-book
...and hit Return. Here is where we are now:
OK, all we did was just navigate to a folder in Terminal, and we're actually ready to use the API now!
The Leanpub API Docs
The details of how the API works are set out on our API Docs page here:
Now, if you're not familiar with how programmers typically explain things to each other, that page probably looks very unhelpful. That's what this article is for!
First Step: Get your API Key
First, you need to get the unique "API Key" for your Leanpub account. To get yours, just go here:
You'll see something like this:
We've covered up the API key in this example, but there is one there! It's a long series of letters and numbers. You should never show it to anyone!
If you've got a password keeper, you may want to save your Leanpub API key in it to easily get at it in the future.
Previewing Your Book Using the API
To use the API, you type commands into the command line (in this example, in Terminal).
To preview your book, type this in Terminal:
curl -d "api_key=YOUR_API_KEY" https://leanpub.com/SLUG/preview.json
...making sure to replace YOUR_API_KEY with your unique API, and SLUG with your book's unique "slug".
The "slug" is the part of the URL for your book after https://leanpub.com/. For example, if your book's Leanpub landing page is https://leanpub.com/my_book, then your book's slug is my_book.
In this example, the book we're using is https://leanpub.com/sample-nonfiction-book, so the "slug" is "sample-nonfiction-book".
Now, type the command into Terminal (we've blurred out the API key in this example):
You may want to save the command in your password keeper if you have one, so you don't need to type it out all the time.
OK, now let's hit Return to run the command!
If you go to your book's Preview page, you will see that this command has magically set off Leanpub's book generators, and they are now creating a new preview of your book:
Please note that you may need to wait a moment and refresh the page to see the progress bar, like in the example above.
If you've made it to this point, congratulations! You have now used an API.
Publishing a New Version of Your Book Using the API
The command to publish a new version your book is just like the command to preview, but with the word "publish" instead of "preview:
curl -d "api_key=YOUR_API_KEY" https://leanpub.com/SLUG/publish.json
Let's give that a try in Terminal:
(Again, we've blurred out the API key in the example.)
Once you've typed in the command to publish a new version, hit Return.
If you go to your Publish page, you'll see there's a progress bar, indicating that Leanpub's book generators are publishing a new version:
Again, please note that you may need to wait a moment and refresh the page to see the progress bar, like in the example above.
Getting Your Book's Summary Information Using the Leanpub API
Next, you can get "Summary Information" about your book from the API.
Here is the command to get your book's summary information:
curl https://leanpub.com/SLUG.json?api_key=YOUR_API_KEY
...making sure to replace YOUR_API_KEY with your unique API, and SLUG with your book's unique "slug".
Let's try this command in Terminal, with the actual API key at the end blurred out as usual:
The result you'll currently get will look something like this:
{"id":47174,"title":"Sample Nonfiction Theme Book","subtitle":"","slug":"sample-nonfiction-book","about_the_book":"\u003cp\u003eThis is an example of a Leanpub book formatted using our Nonfiction theme.\u003c/p\u003e\u003cp\u003e \u003c/p\u003e\u003cp\u003eYou can download a zip file with the complete manuscript folder from which this course is generated by clicking \u003ca href=\"https://github.com/leanpub/sample-nonfiction-book/archive/refs/heads/master.zip\" target=\"_blank\"\u003ehere\u003c/a\u003e.\u003c/p\u003e","total_revenue":"0.0","last_published_at":"2021-04-16T01:05:35.000Z","word_count":179,"page_count":6,"word_count_published":179,"page_count_published":6,"total_copies_sold":14,"meta_description":"","author_string":"Len Epp","url":"http://leanpub.com/sample-nonfiction-book","title_page_url":"https://d2sofvawe08yqg.cloudfront.net/sample-nonfiction-book/original?1618003911","minimum_price":0.0,"suggested_price":0.0,"image":"https://d2sofvawe08yqg.cloudfront.net/sample-nonfiction-book/medium?1618003911","possible_reader_count":0,"pdf_preview_url":"http://leanpub.com/s/YRUlnmq4sU1d8MZfgi9TXQ.pdf","epub_preview_url":"http://leanpub.com/s/YRUlnmq4sU1d8MZfgi9TXQ.epub","mobi_preview_url":"http://leanpub.com/s/YRUlnmq4sU1d8MZfgi9TXQ.mobi","pdf_published_url":"http://leanpub.com/s/HY7bF3k-KAhrG6GUBUaHKQ.pdf","epub_published_url":"http://leanpub.com/s/HY7bF3k-KAhrG6GUBUaHKQ.epub","mobi_published_url":"http://leanpub.com/s/HY7bF3k-KAhrG6GUBUaHKQ.mobi"}
Yes, we know that's gross, but we will improve it, hopefully sometime soon!
Here's what it should look like:
{"id":47174,
"title":"Sample Nonfiction Theme Book",
"subtitle":"",
"slug":"sample-nonfiction-book",
"about_the_book":"\u003cp\u003eThis is an example of a Leanpub book formatted using our Nonfiction theme.\u003c/p\u003e\u003cp\u003e \u003c/p\u003e\u003cp\u003eYou can download a zip file with the complete manuscript folder from which this course is generated by clicking \u003ca href=\"https://github.com/leanpub/sample-nonfiction-book/archive/refs/heads/master.zip\" target=\"_blank\"\u003ehere\u003c/a\u003e.\u003c/p\u003e","total_revenue":"0.0",
"last_published_at":"2021-04-16T01:05:35.000Z",
"word_count":179,
"page_count":6,
"word_count_published":179,
"page_count_published":6,
"total_copies_sold":14,
"meta_description":"",
"author_string":"Len Epp",
"url":"http://leanpub.com/sample-nonfiction-book",
"title_page_url":"https://d2sofvawe08yqg.cloudfront.net/sample-nonfiction-book/original?1618003911",
"minimum_price":0.0,
"suggested_price":0.0,
"image":"https://d2sofvawe08yqg.cloudfront.net/sample-nonfiction-book/medium?1618003911",
"possible_reader_count":0,
"pdf_preview_url":"http://leanpub.com/s/YRUlnmq4sU1d8MZfgi9TXQ.pdf",
"epub_preview_url":"http://leanpub.com/s/YRUlnmq4sU1d8MZfgi9TXQ.epub",
"mobi_preview_url":"http://leanpub.com/s/YRUlnmq4sU1d8MZfgi9TXQ.mobi",
"pdf_published_url":"http://leanpub.com/s/HY7bF3k-KAhrG6GUBUaHKQ.pdf",
"epub_published_url":"http://leanpub.com/s/HY7bF3k-KAhrG6GUBUaHKQ.epub"
"mobi_published_url":"http://leanpub.com/s/HY7bF3k-KAhrG6GUBUaHKQ.mobi"}
Downloading the Latest Version of Your Book Using the API
You can use the URLs provided in the summary information to download the latest version of your book using the API.
Do not share these URLs with anyone, as that will give them access to your book! (If you're interested in our approach to URLs, please see this article.)
Also, these URLs do not change, so you may want to save them somewhere for easy reference.
Here is the URL for the latest published version of this book, in the book summary information example above:
"pdf_published_url":"http://leanpub.com/s/HY7bF3k-KAhrG6GUBUaHKQ.pdf"
There's More!
As we show in the Leanpub API docs, there's more you can do in the API, like creating coupons, getting a list of coupons, and getting a list of email addresses that your readers have chosen to share with you.
We'll add more articles to this Help Center for doing all of those things in the future, but for now, we just wanted to be able to get you started using our API for authors!
OK, that;'s it!
If you have any feedback or questions about this article, please email the Leanpub team about it at hello@leanpub.com!
If you have any questions or thoughts on writing and self-publishing with Leanpub, please join our global community of authors in our Authors Forum here!
Are you interested in self-publishing, and creating your first Leanpub book? Here are some quick tutorials for our most popular writing modes: http://help.leanpub.com/en/articles/3088382-quick-walkthroughs-for-getting-started-on-a-leanpub-book
Are you looking for great deals on Leanpub ebooks, ebook bundles, and courses? Sign up for our Weekly and Monthly newsletter sales here!
Subscribe to our YouTube channel here: https://www.youtube.com/leanpub
Please subscribe to our YouTube channel here: https://www.youtube.com/leanpub
You can also follow Leanpub in lots of other places!
