Skip to main content

​
About GitBook

GitBook is a documentation and knowledge base platform. The Serval GitBook integration connects to GitBook with a personal access token, giving Serval workflows read-only access to GitBook content through Serval’s authenticated proxy. The integration includes a ready-to-use workflow, Search and Read GitBook Pages, that searches a space and reads matching pages as Markdown. Authentication: API token. GitBook calls these personal access tokens. Serval stores the token securely and attaches it to requests automatically; the token is only sent to GitBook’s API host (api.gitbook.com), and workflow code never sees it. Data sync: On demand only. Workflows read from GitBook at run time. There is no background sync or webhook setup in this integration.

​
What the GitBook integration enables

CapabilityDescription
GitBook API requests from workflowsWorkflows can call the modeled GitBook API surface through Serval’s built-in GitBook action, with your token injected automatically.
Search and read pagesThe Search and Read GitBook Pages workflow searches one GitBook space, reads up to 10 matching pages, and returns each page’s title, path, URL when available, excerpt, and Markdown content.
Health checksTwo checks verify that the token can read the current user and list spaces visible to that user.
Anything in the integration’s modeled GitBook API surface can be accessed through Serval, including current-user lookup, space listing, space search, current revision lookup, and page retrieval by ID or path.

​
Get your credentials

You need a GitBook personal access token. GitBook tokens are tied to the user account that creates them and have the same access that user has in GitBook.
1

Open Developer settings

In GitBook, open your user account’s Developer settings. GitBook documents token management under API authentication.
2

Create a personal access token

Create a new access token for Serval. Copy it immediately and store it securely.
3

Confirm content access

Make sure the GitBook user that created the token can read every space and page Serval workflows should access. A token cannot read content that its user cannot see.
Treat the token like a password. If it is shared or exposed, revoke it in GitBook Developer settings and create a replacement token.

​
Connect in Serval

1

Add a GitBook connection

In Serval, open the GitBook integration and start a new connection.
2

Paste your API token

Paste the personal access token into the API Token field. The field is a password field, so the value is hidden as you type.
3

Submit the form

Submit the form, then run the health checks below to confirm the token works and has access to the expected spaces.

​
Find your GitBook space ID

The Search and Read GitBook Pages workflow requires a spaceId. You can find a space ID in either place:
  • In a GitBook space URL: https://app.gitbook.com/o/<organizationId>/s/<spaceId>. The value after /s/ is the space ID.
  • In GitBook’s space menu, use Copy space ID when it is available.

​
Verifying the connection

After connecting, run the integration’s health checks from the integration page:
  • Get GitBook Current User - verifies that the token authenticates by reading the current GitBook user.
    • Success: “Successfully connected to GitBook as [display name].” If GitBook returns an email address, the message includes it in parentheses.
    • Failure: “Unable to read the current GitBook user. Please verify your API token is valid.”
  • List GitBook Spaces - verifies that the token can list spaces visible to the current user.
    • Success: “Successfully listed [number] GitBook space(s).”
    • Failure: “Unable to list GitBook spaces. Please verify your API token has read access.”
A successful connection only proves that the token works. The spaces and pages available to workflows still depend on what the token’s GitBook user can read.

​
Gotchas and troubleshooting

Confirm the spaceId belongs to the space you want to search and that the token’s GitBook user can read that space. Also try a shorter search query. GitBook’s space search can be strict about matching all words in a query.
The token reads as the GitBook user who created it. If that user cannot open the page in GitBook, Serval cannot read it either. Grant the user access or create the token from a user with the right access.
Use the internal GitBook space ID, not the published docs URL. In https://app.gitbook.com/o/<organizationId>/s/<spaceId>, copy only the value after /s/.
When rotating the token, paste the complete replacement token into Serval and save. Do not save a blank or partial value; Serval will use exactly what you submit.
Need help? Contact support@serval.com for assistance with your GitBook integration.