Quickstart

Learn how to use the GitBook API within minutes

The GitBook API allows you to read and write information across the spaces and pages you have access to in GitBook.

You can use the GitBook API to:

Create, update, and delete organizations, spaces, collections, and published docs sites
Manage users, teams, and access permissions at both the space and organization level
Import and export content (pages, files, and reusable content)
Create, list, review, merge, and update change requests
Post, retrieve, update, and delete comments (and comment replies)
Configure custom hostnames, URLs, and search settings
Monitor content performance with analytics endpoints
Manage integrations and OpenAPI documentation

…and much more, all via simple REST calls.

Getting started

You’ll need a GitBook account to start using the developer platform. If you don’t already have an account, you can sign up for free here.

Create a personal access token

After creating a GitBook account, you'll be able to create a personal access token in your developer settings.

This token represents your user in GitBook, and allows you to make API calls, create integrations, and publish them to any GitBook spaces you're a part of to test them.

As always with access tokens, this token is specific to your user and should not be shared for use outside of your personal account.

Once you have your personal access token, you'll want to understand the differences between the pieces of the GitBook Integrations Platform in order to start developing your first app.

Make your first API call

The example below shows how to make an API call that asks GitBook Assistant a question in a site within your organization.

To query a GitBook site using the Ask API, send a POST request to the /v1/orgs/{organizationId}/sites/{siteId}/ask endpoint. Include your developer token for authentication, provide the question you want answered, and optionally pass context and scope settings.

Make a basic Ask API request

Set your required headers:
- Authorization: Bearer YOUR_SECRET_TOKEN
- Content-Type: application/json
Send a POST request with your query details:

POST /v1/orgs/{organizationId}/sites/{siteId}/ask HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*

{
  "question": "How do I get started?",
  "scope": {
    "mode": "default",
  }
}

The API will return an answer generated from your site’s content.

To send a question to the Ask API from JavaScript, you can use GitBook’s client library. After initializing the client with your personal access token, call the askQueryInSpace() method with your organization ID, site ID, and query payload.

Ask a question using GitBook’s JavaScript SDK

Install the GitBook API client:

npm install @gitbook/api

Initialize the client and send your Ask query:

index.js

import { GitBookAPI } from "@gitbook/api";

const ORGANIZATION_ID = "<your organization id>"
const SITE_ID = "<your site id>"
const API_TOKEN = "<your gitbook api token>"

const client = new GitBookAPI({
    authToken: API_TOKEN
});

const stream = await client.orgs.streamAskInSite(
    ORGANIZATION_ID,
    SITE_ID,
    {
        question: "How do I get started?",
        scope: {
            mode: "default",
    },
);

// Stream chunks as they arrive
for await (const chunk of stream) {
    console.log(chunk);
}

The response will contain the generated answer based on your site’s content.

To send a question to the Ask API using Python, make a POST request to the /v1/orgs/{organizationId}/sites/{siteId}/ask endpoint. Include your API token for authentication and pass the question, context, and scope in the request body.

Ask a question using Python

ask_query.py

import json
import requests

ORGANIZATION_ID = "<your organization id>"
SITE_ID = "<your site id>"
API_TOKEN = "<your gitbook api token>"

response = requests.post(
    f"https://api.gitbook.com/v1/orgs/{ORGANIZATION_ID}/sites/{SITE_ID}/ask",
    headers={
        "Authorization": f"Bearer {API_TOKEN}",
        "Content-Type": "application/json"
    },
    json={
        "question": "How do I get started?",
        "scope": {"mode": "default"}
    },
    stream=True
)

# Get the last response before "done"
final = None
for line in response.iter_lines():
    if line:
        line = line.decode('utf-8')
        if line.startswith('data: ') and line[6:] != 'done':
            final = json.loads(line[6:])

print(final)

This will return the Ask API’s generated answer based on your site’s content.

GitBook’s API has many different API calls that allow you to interact with GitBook in different ways. After sending your first request, head to the API reference to explore the different endpoints GitBook offers.

Explore GitBook’s API

Create and edit content

Update a site

Work with analytics

Last updated 6 months ago

Was this helpful?