Content

Read and update content of a space

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

Overall flow

Space content on GitBook is versioned in a similar way to Git, each change result in a complete snapshot of the content (called Revision). Each revision is linked to the previous content snapshot: its parent.

Each space contains a reference to the latest snapshot to use (primary revision). Drafts in a space also contain references to revisions (current content and ancestor).

Revisions

A revision is a snapshot of the space content at a specific point in time. It contains everything used to display a space:

type Revision {
uid: string;
variants: Variant[];
assets: Asset[];
}

Variants

Variants are alternative sets of pages in a revision. You can create variants from the UI to document multiple languages or multiple versions of an API.

type Variant = {
uid: string;
ref: string;
page: Page;
}

Pages

Each variant starts with a root page, the tree of pages represent the table of content visible to the end user. GitBook has 3 kind of pages:

  • Document pages

  • Group (only possible under the root page)

  • External links

type Page = PageDocument | PageGroup | PageLink;
type PageDocument = {
uid: string;
title: string;
path: string;
pages: Page[];
document: Document;
}
type PageGroup = {
uid: string;
title: string;
pages: Page[];
}
type PageLink = {
uid: string;
title: string;
href: string;
}

Documents

Documents is the lowest primitives of content, it defines the inner content of a page. Documents can be obtained (or set) from the API using our JSON format or Markdown (?format=markdown).

Assets

Assets represent binary files that are stored with the text content, documents can reference assets to include images or files.

type Asset = {
uid: string;
name: string;
contentType: string;
downloadURL: string;
};