Skip to main content

GitBook

GitBook is a modern documentation platform that enables teams to create, manage, and publish technical documentation, API references, and knowledge bases. It provides a collaborative writing environment with version control, integrations with developer tools like GitHub, and support for OpenAPI specifications—making it a popular choice for software teams that need to maintain accurate, up-to-date documentation alongside their code.

GitBook icon

Power end-to-end data operations for your GitBook API with Nexla. Our bi-directional GitBook connector is purpose-built for GitBook, making it simple to ingest data, sync it across systems, and deliver it anywhere — all with no coding required. Nexla turns API-sourced data into ready-to-use, reusable data products and makes it easy to send data to GitBook or any other destination. With comprehensive monitoring, lineage tracking, and access controls, Nexla keeps your GitBook workflows fast, secure, and fully governed.

Features

Type: API

SourceDestination

  • Seamless API Integration: Connect to any endpoint as source or destination without coding, with automatic data product creation
  • Visual Composition & Chaining: Build complex integrations using visual templates, chain API calls, and compose workflows with data validation and filtering
  • API Proxy: Expose curated slices of your data securely with a secure and customizable API proxy that validates and transforms data on the fly
  • Request optimization with intelligent batching, retry, and caching to minimize API calls and costs

Prerequisites​

GitBook authenticates API requests using personal access tokens. Before creating a GitBook credential in Nexla, you will need to generate a personal access token from your GitBook account's Developer settings.

Generate a GitBook Personal Access Token​

  1. Sign in to your GitBook account at gitbook.com.

  2. Click on your profile avatar in the lower-left corner of the GitBook interface to open the account menu, then select Settings.

  3. In the left-hand navigation of your account settings, select Developer.

  4. Under the Personal Access Tokens section, click the Create new token button.

  5. Enter a descriptive name for the token in the Token Name field — for example, "Nexla Integration" — to help you identify its purpose later.

  6. Click Create to generate the token.

  7. Copy the token value immediately and store it securely. GitBook displays the full token only once at creation time. If you lose the token, you will need to revoke it and create a new one.

    Your personal access token provides the same level of access and privileges as your GitBook user account. Keep the token secure and do not share it in emails, chat messages, client-side code, or any publicly accessible location. Additional information about GitBook API authentication is available in the GitBook Authentication documentation.

Authenticate​

Create a credential in Nexla​

  1. After selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

  2. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

  3. Enter the personal access token you generated in Prerequisites into the API Token field. This token is used to authenticate all API requests Nexla makes on your behalf to the GitBook API at https://api.gitbook.com/v1/.

    The GitBook API uses the Bearer authentication scheme. Nexla automatically includes the token in the Authorization header of every request in the format Authorization: Bearer {your_token}. You do not need to add this header manually.

  4. Click the Save button at the bottom of the overlay. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation.

Use as a data source​

To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Select the GitBook connector tile, then select the credential that will be used to connect to the GitBook instance, and click Next; or, create a new GitBook credential for use in this flow.

Endpoint templates​

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common GitBook endpoints. Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below.

Get Current User

Returns the profile information of the authenticated GitBook user, including name, email, and account details.

  • Sends a GET request to https://api.gitbook.com/v1/user and returns the authenticated user's profile object.
  • Response data is located at $ (the top-level response object).

No parameters are required. This endpoint is useful for verifying connectivity and confirming the identity of the authenticated API token holder.

List Organizations

Returns a list of all GitBook organizations that the authenticated user is a member of.

No parameters are required. Use the returned organization IDs with other endpoints that require an Organization ID parameter.

Get Space Traffic Insights

Returns traffic and analytics data for a specific GitBook space, useful for measuring documentation engagement and page views.

Traffic insights may be subject to data retention limits depending on your GitBook plan. Use List Organization Spaces to retrieve valid Space IDs.

Get Space Content

Returns the full content structure and page hierarchy for a specific GitBook space, enabling documentation content synchronization.

Returns the full page tree including nested pages. For very large spaces, the response may be large — consider specifying a Path to Data to extract only the needed fields.

List Organization Members

Returns a list of members in a specific GitBook organization, including their roles and join dates.

Use the List Organizations endpoint to retrieve valid Organization IDs. Results are paginated using the standard GitBook pagination cursor.

Get Space Current Revision

Retrieves the current revision and content metadata for a GitBook space, useful for change detection and documentation versioning workflows.

  • Sends a GET request to https://api.gitbook.com/v1/spaces/{spaceId}/content/v and returns the revision metadata object.
  • Response data is located at $ (the top-level response object).
  • Configure the following parameters: Space Id — the unique identifier of the space; Include metadata — whether to include additional metadata; Include computed fields — whether to include computed fields in the response.

The Include metadata and Include computed fields parameters are optional. This endpoint is particularly useful for detecting content changes since the last sync.

List Organization Spaces

Lists all spaces belonging to a GitBook organization — the canonical way to discover which spaces exist before reading their content or analytics.

Use the List Organizations endpoint to retrieve valid Organization IDs. Returned Space IDs can be used with other space-scoped endpoints.

List Space Change Requests

Lists open change requests (draft editing branches) for a specific GitBook space, enabling documentation workflow monitoring.

Change requests represent pending edits that have not yet been merged into the published space content.

List Organization Collections

Lists all collections within a GitBook organization. Collections are groups of related spaces used to organize documentation.

Use the List Organizations endpoint to retrieve valid Organization IDs. Each collection includes its name, visibility settings, and member spaces.

List Organization Teams

Lists all teams defined within a GitBook organization, useful for auditing access controls and team membership.

Use the List Organizations endpoint to retrieve valid Organization IDs. Team IDs returned here can be used with space permission endpoints.

List Space User Permissions

Lists all users and their assigned permission roles on a specific GitBook space, enabling access control auditing.

Use the List Organization Spaces endpoint to retrieve valid Space IDs. This endpoint returns only user-level permissions, not team-level permissions.

List Space Comments

Lists inline comments and discussion threads on a specific GitBook space, enabling documentation review workflow tracking.

Inline comments are anchored to specific pages or sections within a space. Each comment record includes the author, creation time, and page reference.

Once the selected endpoint template has been configured, click the Test button to the right of the endpoint selection menu to retrieve a sample of the data that will be fetched. Sample data will be displayed in the Endpoint Test Result panel on the right, allowing you to verify that the source is configured correctly before saving.

Manual configuration​

GitBook sources can also be manually configured to ingest data from any valid GitBook API endpoint, including endpoints not covered by the pre-built templates, chained API calls, or custom request parameters. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, endpoint URL, date/time and lookup macros, path to data, metadata, and request headers.

The GitBook REST API is accessible at https://api.gitbook.com/v1/ and supports retrieval of spaces, pages, organizations, users, change requests, and more — for example, https://api.gitbook.com/v1/orgs/{'{organizationId}'}/spaces to list spaces in an organization, or https://api.gitbook.com/v1/spaces/{'{spaceId}'}/content to retrieve the full content of a space. Replace {'{organizationId}'}, {'{spaceId}'}, and {'{pageId}'} with the actual IDs from your GitBook account, which can be found in the GitBook URL when browsing your content, or by querying the /v1/orgs endpoint.

Most GitBook list endpoints wrap records inside a top-level items array alongside pagination metadata (next, previous, total) — set Set Path to Data in Response to $.items[*] and, if you want to preserve the pagination fields, point Path to Metadata in Response at the surrounding object. Endpoints that return a single object, such as Get Current User or Get Space Current Revision, use $ for the whole response. Date/time macros in the API URL are useful when querying endpoints that accept date-based filters, such as filtering revisions or change requests by date range.

You do not need to include the Authorization header manually — Nexla automatically adds it using the API token from the configured credential. The GitBook API currently uses a single API version, so no versioning headers are typically required.

Once all of the relevant settings have been configured, click the Create button in the upper right corner of the screen to save and create the new GitBook data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.

Use as a destination​

Click the + icon on the Nexset that will be sent to the GitBook destination, and select the Send to Destination option from the menu. Select the GitBook connector from the list of available destination connectors, then select the credential that will be used to connect to the GitBook organization, and click Next; or, create a new GitBook credential for use in this flow.

Endpoint templates​

Nexla provides pre-built templates that can be used to rapidly configure destinations to send data to common GitBook endpoints. Select the endpoint to which data will be sent from the Endpoint pulldown menu. Then, click on the template in the list below to expand it, and follow the instructions to configure additional endpoint settings.

Create Space in Organization

Creates a new GitBook space inside a specified organization, enabling automated documentation space provisioning.

Use the List Organizations source endpoint to retrieve valid Organization IDs. The space will be created with the authenticated user as the owner.

Update Space

Updates the properties and settings of an existing GitBook space, such as its title, visibility, or custom domain.

Use the List Organization Spaces source endpoint to retrieve valid Space IDs. Only the fields included in the payload will be updated.

Delete Space

Archives (deletes) a GitBook space by its unique ID. This action removes the space and all of its content.

This operation is irreversible. All pages and content within the space will be permanently removed. Ensure you have backed up any necessary content before proceeding.

Create Page in Space

Creates a new page inside a specified GitBook space, enabling automated documentation page creation.

The page is created as a draft within the space. Publish or merge a change request to make the page visible to readers.

Update Space Page

Updates the content or metadata of an existing page within a GitBook space.

Use the Get Space Content source endpoint to retrieve valid Page IDs within a space.

Delete Space Page

Permanently deletes a page from a GitBook space by its ID.

This action is irreversible. Use Get Space Content to retrieve valid Page IDs before proceeding.

Invite User or Team to Space

Invites a user or team to a GitBook space with a specified role, enabling automated access management workflows.

Use the List Organization Members and List Organization Teams source endpoints to retrieve valid user and team identifiers.

Update Team Permission in Space

Updates an organization team's role and permission level within a specific GitBook space.

Use the List Organization Teams source endpoint to retrieve valid team IDs.

Remove Organization Member

Removes a member from a GitBook organization, revoking their access to all spaces within that organization.

This action revokes the member's access to the entire organization. Use the List Organization Members source endpoint to retrieve valid User IDs.

Create Space Change Request

Creates a new change request on a GitBook space for staged content editing, enabling review-based documentation workflows.

Change requests are GitBook's equivalent of branches — they allow staged edits to be reviewed before being merged into the published space content.

Update Organization

Updates GitBook organization settings such as title, hostname, default member role, or SSO configuration.

Use the List Organizations source endpoint to retrieve valid Organization IDs. Only the fields included in the payload will be modified.

Import Content into Space

Imports content (Markdown, HTML, or other supported formats) into a GitBook space, enabling bulk documentation migration.

Refer to the GitBook API Reference for supported content formats and the required payload structure.

Create Collection

Creates a new collection within a GitBook organization to group related spaces together.

Use the List Organizations source endpoint to retrieve valid Organization IDs. Spaces can be added to collections after creation using the Update Space endpoint.

Remove Space User Permission

Removes a user's permission from a specific GitBook space, revoking their access to that space.

This removes the user's direct space-level permission. Organization-level access may still grant the user access if they are an organization member.

Manual configuration​

GitBook destinations can also be manually configured to send data to any valid GitBook API endpoint. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, data format, endpoint URL, request headers, attribute exclusions, record batching, and response webhooks.

Using Nexla's GitBook destination, you can push records to the GitBook REST API at https://api.gitbook.com/v1/ to create or update content, manage spaces, import documentation, trigger change requests, and more. The GitBook API accepts and returns data in JSON format — select JSON as the content format for all GitBook destination operations. Common methods include POST for creating spaces, pages, or change requests; PUT for replacing content; PATCH for partial updates such as space settings or member roles; and DELETE for removing resources. For update or upsert operations, include the ID of the object to be updated at the end of the URL, for example https://api.gitbook.com/v1/spaces/{'{spaceId}'}.

You do not need to include the Authorization header — this is automatically managed by Nexla using the API token from the configured credential, and the Content-Type: application/json header is also handled automatically. Many GitBook write endpoints accept only a single object per request, so review the GitBook API Reference to confirm whether the target endpoint supports batch payloads before enabling record batching. Enabling the response webhook option is useful for capturing values such as the ID of a newly created space or the status of an import operation.

Save & activate​

Once all endpoint settings have been configured, click the Done button in the upper right corner of the screen to save and create the destination. To send the data to the configured GitBook endpoint, open the destination resource menu, and select Activate.

The Nexset data will not be sent to GitBook until the destination is activated. Destinations can be activated immediately or at a later time, providing full control over data movement.