> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cymph.io/llms.txt
> Use this file to discover all available pages before exploring further.

# GitBook

> Fetch documentation pages and spaces from GitBook.

## What Cymph uses it for

Cymph connects to GitBook for two purposes:

1. **Importing content** — fetches documentation pages and spaces. *(read)*
2. **Publishing documentation** — adds a playbook's documentation to a space as a new page. *(write)* See [Deploy playbooks](/how-tos/deploy-playbooks).

The endpoint is fixed to GitBook's SaaS API (`https://api.gitbook.com`), so no instance URL is required.

**If you only import, the token's account needs read access to your spaces; publishing requires edit access** — see [Permissions](#permissions) below.

## Requirements

| Field         | Description                     |
| ------------- | ------------------------------- |
| **API token** | A GitBook API token (see below) |

## Token setup

Create an API token from your GitBook [developer settings](https://gitbook.com/docs/developers/gitbook-api/quickstart) (**Account settings → Developer → API tokens**).

## Permissions

GitBook has no per-token scope selector — a token inherits the permissions of the account that created it. What matters is the account's role on the target spaces:

| If you want to                       | The token's account needs                                                                     |
| ------------------------------------ | --------------------------------------------------------------------------------------------- |
| Import content only                  | **Read** access to the organizations and spaces you want to sync                              |
| Import **and** publish documentation | **Edit** access on the target space, including permission to create and merge change requests |

<Tip>
  Create the token from a dedicated service account rather than a personal admin account, and grant it access only to the spaces Cymph should touch. Published pages are attributed to the token's account.
</Tip>

## What Cymph reads and writes

Cymph reads your organizations, their spaces, and page content.

Publishing goes through GitBook's **change request** workflow rather than writing to the live space directly — three calls, in order:

| Step                       | GitBook API call                                          |
| -------------------------- | --------------------------------------------------------- |
| 1. Open a change request   | `POST /v1/spaces/{space_id}/change-requests`              |
| 2. Insert the page         | `POST /v1/spaces/{space_id}/change-requests/{id}/content` |
| 3. Merge it into the space | `POST /v1/spaces/{space_id}/change-requests/{id}/merge`   |

Because the merge is automatic, a published playbook lands in the live space — the change request is a mechanism, not a review gate.

<Note>
  Each publish inserts a **new** page. Cymph does not update or delete existing GitBook pages, so publishing the same playbook twice produces two pages.
</Note>

## Publishing formats

GitBook accepts **Markdown documentation only** — PDF publishing is not supported. Image blocks are omitted.

## Testing the connection