Overview

The GitBook API is currently in beta phase. If you wish to be one of our testers, please contact our team at [email protected].

The GitBook REST API can be used to fetch and update content on GitBook.

Authentication

There is currently one way to authenticate through GitBook API v1: authentication token. A token can be created in the user account settings.

This token can then be used in the Headers section of your HTTP request:

curl -H "Authorization: Bearer [YOUR_TOKEN]" https://api-beta.gitbook.com

Pagination

Some methods return paginated results. The formatting of a paginated result is always:

{
"items": [
...
],
"next": {
"page_id": "..."
},
"previous": {
"page_id": "..."
}
}

The objects previous and next will be omitted if there are no previous or next items respectively.

Errors

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

As a general rule:

  • Codes in the 2xx range indicate success

  • Codes in the 4xx range indicate incorrect or incomplete parameters (e.g., a required parameter was omitted, an operation failed with a 3rd party, etc.)

  • Codes in the 5xx range indicate an error with GitBook's servers (these are rare)

GitBook also outputs an error message and an error code formatted in JSON:

{
"error": {
"code": 404,
"message": "Page not found in this space"
}
}

Postman configuration

If you wish to rapidly test the GitBook's API endpoints we have created a Postman configuration containing the basic routes to read and update content.

Once imported in Postman you will need to define two variables in the collection's settings:

  • A Bearer Token in the Authorization tab.

  • A BASE_URL in the Variables tab.