Table

of Contents

Overview
Introduction 1.1
OAuth 1.2

Books
Overview 2.1
Traffic 2.2
Access Keys 2.3
Versions 2.4
Contents 2.5
Discussions 2.6
Webhooks 2.7

Authors
Overview 3.1

Miscellaneous
Search 4.1
Topics 4.2

1
Introduction

GitBook API Reference

This documentation is intended to get you up-and-running with the GitBook APIs. We’ll cover
everything you need to know, from authentication, to manipulating results, to combining
results with other services.

The REST APIs provide programmatic access to read and write GitBook data. List books,
edit content, proofread text, and more. The REST API identifies users using basic auth;
responses are available in JSON.

Schema
All API access is over HTTPS, and accessed through https://api.gitbook.com . All data is
sent and received as JSON.

$ curl -i https://api.gitbook.com/author/gitbookio

HTTP/1.1 200 OK
Server: GitBook.com
Connection: keep-alive
Content-Type: application/json; charset=utf-8
Content-Length: 275
Etag: W/"113-25d22777"
Date: Thu, 11 Jun 2015 14:49:26 GMT
Via: 1.1 vegur

{ ... }

Install the GitBook API client from NPM:

$ npm install gitbook-api

Initialize a client:

const GitBook = require('gitbook-api');

const client = new GitBook();

Install the GitBook API client using go get :

2
Introduction

$ go get github.com/GitbookIO/go-gitbook-api

Initialize a client:

package main

import (
"fmt"
"github.com/GitbookIO/go-gitbook-api"
)

func main() {
api := gitbook.NewAPI(gitbook.APIOptions{})
}

Authentication
While the API provides multiple methods for authentication, we strongly recommend using
OAuth for production applications. The other methods provided are intended to be used for
scripts or testing (i.e., cases where full OAuth would be overkill).

Third party applications that rely on GitBook for authentication should not ask for or collect
GitBook credentials. Instead, they should use the OAuth web flow.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

The API supports Basic Authentication as defined in RFC2617 with a few slight differences.

Requests that require authentication will return 404 Not Found , instead of 403 Forbidden , in
some places. This is to prevent the accidental leakage of private books to unauthorized
users.

Via Username and Password

To use Basic Authentication with the GitBook API, simply send the username and password
associated with the account.

For example, if you’re accessing the API via cURL, the following command would
authenticate you if you replace with your GitBook username. (cURL will prompt you to enter
the password.)

Alternatively, you can use personal access tokens or OAuth tokens instead of your
password.

3
Introduction

$ curl -u <username>:<password or token> https://api.gitbook.com/account

Via OAuth Tokens

The access token allows you to make requests to the API on a behalf of a user.

$ curl -H "Authorization: token OAUTH-TOKEN" https://api.gitbook.com/account

Via Username and Password

const client = new GitBook({

username: 'MyUsername',
token: 'password'
});

Via OAuth Tokens

const client = new GitBook({

token: 'oauth token'
});

Via Username and Password

api := gitbook.NewAPI(gitbook.APIOptions{
Username: "username",
Password: "password",
})

Via OAuth Tokens

api := gitbook.NewAPI(gitbook.APIOptions{
Token: "token"
})

Errors
GitBook uses conventional HTTP response codes to indicate the success or failure of an
API request.

4
Introduction

In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an
error that failed given the information provided (e.g., a required parameter was omitted, a
charge failed, etc.), and codes in the 5xx range indicate an error with Stripe's servers
(these are rare).

Not all errors map cleanly onto HTTP response codes, however.

HTTP status code summary

Status Description
200 - OK Everything worked as expected.
400 - Bad The request was unacceptable, often due to missing a required
Request parameter.
404 - Not Found The requested resource doesn't exist.

Example Response

{
"error": "A human-readable message providing more details about the error.",
"code": 400
}

All API calls return promises.

client.books()
.then(function(result) {

}, function(err) {

});

The status code can be access using the code property of the error: err.code .

All API calls return both the result and the error:

book, err := api.Book.Get("gitbookio/javascript")

Pagination
Requests that return multiple items will be paginated to 50 items by default.

You can specify further pages with the ?page parameter. For some resources, you can also
set a custom page size up to 100 with the ?limit .

5
Introduction

Paginated results will be returned with information about the page context.

{
list: [ ... ],
page: 0,
limit: 50,
total: 0
}

Paginated methods return a Page object.

Calling page.next() or page.prev() will fetch the next/previous page and return a promise
with a new Page object.

page.list: Array<Mixed> contains the items of current page.

page.total: Number is count of all elements.

client.books()
.then(function(page) {
console.log('Total:', page.total);
console.log('In this page:', page.list.length);

// Fetch next page

return page.next();
}, function(err) {
// Error occured
});

Enterprise
All API endpoints are prefixed with the following URL: http(s)://hostname/api/ .

Most methods require an authentication when using an enterprise instance.

$ curl https://gitbook/myenterprise.com/api/books/all

const client = new GitBook({

host: 'http://gitbook.mycompany.com'
});

api := gitbook.NewAPI(gitbook.APIOptions{
Host: "http://gitbook.mycompany.com/api/"
})

6
Introduction

Help and Support

We're always happy to help out with your applications or any other questions you might
have. You can ask a question or signal an issue using inline comments.

7
OAuth

OAuth
OAuth2 is a protocol that lets external applications request authorization to private details in
a user's GitBook account without getting their password. This is preferred over Basic
Authentication because tokens can be limited to specific types of data, and can be revoked
by users at any time.

All developers need to register their application before getting started. A registered OAuth
application is assigned a unique Client ID and Client Secret. The Client Secret should not be
shared.

You may create a personal access token for your own use or implement the web flow below
to allow other users to authorize your application.

Web Application Flow

This is a description of the OAuth2 flow from 3rd party web sites.

1. Redirect users to request GitBook access

The first step is to redirect the user to the authorization dialog, this dialog will ask user to
grant access to your application.

GET https://api.gitbook.com/oauth/authorize

Parameter Type Description

client_id string
Required. The client ID you received from GitBook when
you registered.

redirect_uri string
Required. The URL in your application where users will
be sent after authorization.

response_type string
Required. Type of response expected, currently only
valid value is code

2. GitBook redirects back to your site

If the user accepts your request, GitBook redirects back to your site with a temporary code
in a code parameter as well as the state you provided in the previous step in a state
parameter. If the states don't match, the request has been created by a third party and the

8
OAuth

process should be aborted.

You can exchange this code for an access token.

POST https://api.gitbook.com/oauth/access_token

Parameters

Name Type Description

client_id string
Required. The client ID you received from GitBook when
you registered.

client_secret string
Required. The client secret you received from GitBook
when you registered.

code string
Required. The code you received as a response to Step
1.

grant_type string
Required. authorization_code to exchange an oauth
code

Response

By default, the response will take the following form:

access_token=e72e16c7e42f292c6912e7710c838347ae178b4a&token_type=bearer

access_token can also be returned as JSON.

3. Use the access token to access the API

The access token allows you to make requests to the API on a behalf of a user.

Include it in the Authorization header

Authorization: Bearer OAUTH-TOKEN

For example, in cUrl you can set the Authorization header like this:

$ curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.gitbook.com/account

9
Overview

Books

List your books

List books that are accessible to the authenticated user.

This includes books owned by the authenticated user, books where the authenticated user is
a collaborator, and books that the authenticated user has access to through an organization
membership.

GET /books

Parameters

Name Type Description

page number Index of current page

List author books

List public books for the specified user/organization.

GET /authors/:username/books

Parameters

Name Type Description

page number Index of current page

List all public books

This provides a dump of every public repository, in the order that they were created.

GET /books/all

Parameters

10
Overview

Name Type Description

page number Index of current page

Create a book
Create a new book for the specified author.

POST /books

Parameters

Name Type Description

author string Required: Username of the owner
title string Required: The title of the book
description string The description of the book

Get a book
Get details about a book.

GET /book/:username/:name

Example Response

{
"id": "johndoe/mybook",
"title": "My Book"
}

11
Traffic

Traffic
The Traffic API lets you fetch statistics about views and downloads.

Get summary
This methods returns a summary of traffic statistics.

GET /book/:author/:book/traffic

Response

{
views: 100,
unique: 10,
downloads: {
pdf: 3,
epub: 3,
mobi: 1
}
}

Get visits per countries

This method returns the count of visits per countries.

GET /book/:author/:book/traffic/countries

Get visits per platforms

This method returns the count of visits per platforms.

GET /book/:author/:book/traffic/platforms

12
Access Keys

Access Keys
Access keys allow non-collaborator to access a private book. Each access key can be
converted to an unique read-only access url.

Create an access key

Create a new book for the specified author.

POST /book/:author/:book/keys

Parameters

Name Type Description

label string Required: Label to identify the key
Optional value of the key, if not provided it'll be set as a random
key string
string

List access keys for a book

GET /book/:author/:book/keys/

Example Response

13
Access Keys

{
"list": [
{
"id": "564c97a917c24e09ddd8b765",
"label": "For Aaron",
"key": "aaron_private_key",
"active": true,
"dates": {
"created": "2015-11-19T12:22:27.765Z",
"updated": "2015-11-19T12:22:27.765Z"
}
}
...
],
"total": 15,
"limit": 10,
"page": 0
}

14
Versions

Versions
The versions API can be used to list available versions of a book (branches, tags or
commits). The Contents API can then be used to fetch files for a specific version.

See Format for details about the version object format.

The Versions plugins can be enabled to list versions of the book in the sidebar.

List branches
This method returns the list of active branches in the book's git repository.

GET /book/:author/:book/versions/branches

List tags
This method returns the list of Git tags in the book's git repository.

GET /book/:author/:book/versions/tags

List languages
For multilingual book, this method returns the list of languages.

GET /book/:author/:book/versions/languages

Version Format
Each version (Tag, Branch or Language) is represented by a version object.

The current is set to true when its represent the main version (current branch, current
language, etc).

15
Versions

{
"name": "master",
"urls": {
"website": "https://samypesse.gitbooks.io/how-to-create-an-operating-system/co
ntent/",
"epub": "https://www.gitbook.com/download/epub/book/samypesse/how-to-create
-an-operating-system/",
"pdf": "https://www.gitbook.com/download/pdf/book/samypesse/how-to-create-
an-operating-system/",
"mobi": "https://www.gitbook.com/download/mobi/book/samypesse/how-to-create
-an-operating-system/"
},
"current": true
}

16
Contents

Contents
These API methods let you retrieve the contents of pages within a book.

It can be used to programmatically integrate your documentation content into your

application.

Get contents
This method returns the contents of a page in a book. All pages are ending with a .json
extension.

See Format for details about the output.

GET /book/:author/:book/contents/:file

Parameters

Name Type Description

file string Required: Path of the file to retrieve (with .json extension)

Get contents for a specific version

The Contents API can also serve other versions than the main one.

It can be used to retrieve contents for a specific Git tag, branch or commit.

See the Versions API for details on how to list versions.

GET /book/:author/:book/contents/v/:version/:file

Parameters

Name Type Description

version string Required: SHA, Branch name or Tag
file string Required: Path of the file to retrieve (with .json extension)

17
Contents

File format
The GitBook Contents API serve content of JSON build from the GitBook Toolchain. The
format may vary between GitBook version being used to generate your book.

Version 2
Currently the default version, but soon to be deprecated.

Example

{
"progress": {
...
},
"sections": [
{
"type": "normal",
"content": "<h1>My Awesome book</h1>"
}
],
"langs": []
}

Version 3
This format is generated since GitBook >=3.0.0 . It is a modern and easier format to work
with.

Contents API can output all books with this format when the client accepts
application/vnd.gitbook.format.v3 :

curl -H "Accept: application/json;application/vnd.gitbook.format.v3" \

"https://api.gitbook.com/book/you/your-book/contents/README.json"

Example

18
Contents

{
"page": {
"title": "Introduction",
"level": "1.1",
"depth": 1,
"next": {
"title": "OAuth",
"level": "1.2",
"depth": 1,
"path": "overview/oauth.md",
"ref": "overview/oauth.md",
"articles": []
},
"content": "<h1>....</h1> ..."
},
"file": {
"path": "README.md",
"mtime": "2016-08-22T21:58:34.000Z",
"type": "markdown"
},
"version": "3"
}

19
Discussions

Discussions
The Discussion API lets you create, list and comment discussions in books.

List discussions for a book

List all opened discussions in a book, all or closed discussions can be listed using the
state parameter.

This method is paginated.

GET /book/:author/:book/discussions

Parameters

Name Type Description

state string State of the discussions ( open , closed or all ), default is

open

filename string Optional file to filter discussions

Create a new discussion

Any user with read access can create a discussion.

POST /book/:author/:book/discussions

Parameters

Name Type Description

title string Required. Title of the discussion.
body string The contents of the discussion.

Close a list of discussions

Mark a list of discussions as closed for a book.

20
Discussions

POST /book/:author/:book/discussions/close

Parameters

Name Type Description

Required. An array containing the threads numbers to mark as
list array
closed.

Open a list of discussions

Mark a list of discussions as open for a book.

POST /book/:author/:book/discussions/open

Parameters

Name Type Description

list array Required. An array containing the threads numbers to mark as open.

21
Webhooks

Webhooks
Webhooks allow you to build or set up integrations which subscribe to certain events on
GitBook.com. When one of those events is triggered, we’ll send a HTTP POST payload to
the webhook’s configured URL.

Example of Integrations
Slack Notifications

List webhooks
List webhooks in a book requires admin" permission.

GET /book/:author/:book/webhooks/

Get single hook

GET /book/:author/:book/webhooks/:id

Get deliveries for a hook

GitBook stores deliveries for a period of 30days.

GET /book/:author/:book/webhooks/:id/deliveries

Get single delivery

Use this method to inspect payload and result of a webhook delivery.

GET /book/:author/:book/webhooks/:id/deliveries/:delivery

Receiving webhooks
22
Webhooks

Events

When configuring a webhook, you can choose which events you would like to receive
payloads for. You can even opt-in to all current and future events. Only subscribing to the
specific events you plan on handling is useful for limiting the number of HTTP requests to
your server. You can change the list of subscribed events through the UI anytime.

By default, webhooks are only subscribed to all events. The available events are:

Name Description
all Any time any event is triggered (Wildcard Event).
publish Content of the book has been updated.
thread Any time a Discussion is opened, closed, or reopened.
thread_comment Any time a Discussion or Pull Request is commented on.

Delivery headers

HTTP requests made to your webhook’s configured URL endpoint will contain several
special headers:

Header Description
X-GitBook-Event Name of the event that triggered this delivery.
X-GitBook- HMAC hex digest of the payload, using the hook’s secret as the key
Signature (if configured).
X-GitBook-
Delivery Unique ID for this delivery.

Also, the User-Agent for the requests will have the prefix GitBook/ .

Example delivery

23
Webhooks

POST /payload HTTP/1.1

Host: localhost:4567
X-GitBook-Delivery: 72d3162e81ab4c9367dc0958
X-GitBook-Event: publish
X-GitBook-Signature: sha1=6adfb183a4a2c94a2f92dab5ade762a47889a5a1
User-Agent: GitBook/10.2.0
Content-Type: application/json
Content-Length: 6615

{
"payload": {
...
}
}

24
Overview

Authors
The Authors API let you access details of users and organizations.

Get a single author

This method returns the details about a specific author.

See Format for details about the output.

GET /authors/:username

List user organizations

This paginated method list public organization memberships for the specified user.

GET /authors/:username/orgs

25
Topics

Topics

List topics
List all topics in GitBook sorted by the count of books.

GET /topics

Parameters

Name Type Description

q string The search keywords, as well as any qualifiers.

Response

{
"list": [
{
"id": "programming",
"name": "Programming",
"books": 320
}
...
],
"total": 76,
"limit": 10,
"page": 0
}

Get a single topic

GET /topic/:id

26