GitBook

https://docs.gitbook.com/llms.txt
Admin
GitBook is a documentation platform that enables teams to create, collaborate on, and publish...
Tokens:968,859
Snippets:8,070
Trust Score:10
Update:1 day ago
Show doc for...
Tokens:
Raw
### Navigation tree example

Source: https://gitbook.com/docs/create-content/content-structure/page

Shows a sample navigation tree with API, Guides, and Install.

```text
API
└── Guides
    └── Install
```

--------------------------------

### Run integration development server

Source: https://gitbook.com/docs/developers/integrations/quickstart

Start local development for your integration. Changes are sent to the installed space or site.

```bash
gitbook integrations dev
```

--------------------------------

### Install GitBook CLI from NPM

Source: https://gitbook.com/docs/developers/integrations/quickstart

Install the GitBook CLI globally using npm. Requires Node v18 or later.

```bash
npm install @gitbook/cli -g
```

--------------------------------

### Git Sync file layout example

Source: https://gitbook.com/docs/create-content/content-structure/page

Shows a sample file layout for Git Sync with a setup folder containing install.md.

```text
content/
└── setup/
    └── install.md
```

--------------------------------

### Publish integration

Source: https://gitbook.com/docs/developers/integrations/quickstart

Publish your integration to GitBook. Returns an install link.

```bash
gitbook integrations publish
```

--------------------------------

### POST /orgs/{organizationId}/sites/{siteId}/styleguide/runs

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/docs-sites/start-a-style-guide-check-run-for-a-site

Starts a style guide check: GitBook Agent reviews the given spaces against the site's style guide and proposes fixes. A space with no check open gets a new draft change request marked as belonging to the returned run; one whose check is still open has it taken over instead. Fails if the site has no style guide.

```APIDOC
## [POST] /orgs/{organizationId}/sites/{siteId}/styleguide/runs

### Description
Starts a style guide check: GitBook Agent reviews the given spaces against the site's style guide and proposes fixes. A space with no check open gets a new draft change request marked as belonging to the returned run; one whose check is still open has it taken over instead. Fails if the site has no style guide.

### Method
POST

### Endpoint
/orgs/{organizationId}/sites/{siteId}/styleguide/runs

### Parameters
#### Path Parameters
- **organizationId** (string) - Required - The ID of the organization.
- **siteId** (string) - Required - The ID of the site.

#### Request Body
- **spaces** (array of strings) - Required - IDs of the site's spaces to check. Each must be an editable content space of the site, and not the style guide itself. Min items: 1, Max items: 3.

### Request Example
{
  "spaces": ["spaceId1", "spaceId2"]
}

### Response
#### Success Response (201)
- **run** (SiteStyleguideRun) - The style guide check run.
- **changeRequests** (array of ChangeRequest) - The change request each space's check runs in: opened by this run, or already open and taken over. One per space that could be started.

#### Response Example
{
  "run": {},
  "changeRequests": []
}

#### Error Response (404)
- **error** (object) - Error details.
  - **code** (integer) - Error code (404).
  - **message** (string) - Error message.

```

--------------------------------

### Query GitBook documentation with ask and goal parameters

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/docs-sites/get-the-setup-steps-of-a-site

Perform an HTTP GET request to the GitBook documentation URL with the `ask` and `goal` query parameters to retrieve a direct answer and relevant excerpts. `ask` is the immediate, self-contained question; `goal` describes the user's ultimate outcome for a tailored response.

```http
GET https://gitbook.com/docs/developers/gitbook-api/api-reference/docs-sites/get-the-setup-steps-of-a-site.md?ask=<question>&goal=<user_goal>
```

--------------------------------

### GET /orgs/{organizationId}/sites/{siteId}/setup

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/docs-sites/get-the-setup-steps-of-a-site

Lists the steps to set up a site, from a first edit to publishing, and whether each one is completed. Use it to know what is left to do on a site. Returns no steps once the site has been published.

```APIDOC
## GET /orgs/{organizationId}/sites/{siteId}/setup

### Description
Lists the steps to set up a site, from a first edit to publishing, and whether each one is completed. Use it to know what is left to do on a site. Returns no steps once the site has been published.

### Method
GET

### Endpoint
/orgs/{organizationId}/sites/{siteId}/setup

### Parameters
#### Path Parameters
- **organizationId** (string) - Required - The unique id of the organization
- **siteId** (string) - Required - The unique id of the site

### Response
#### Success Response (200)
- **steps** (array) - Every setup step, in order. Empty once the site has been published, which ends the setup even if other steps are not completed.
  - **id** (string) - A step of the setup of a site, in the order they are done. Possible values: first-edit, customize, git-sync, domain, publish.
  - **completed** (boolean) - Whether the step is completed.
  - **action** (string) - How to complete the step. Only present when it is not completed.

#### Response Example
{
  "steps": [
    {
      "id": "first-edit",
      "completed": false,
      "action": "string"
    }
  ]
}

#### Error Response (400)
- **error** (object) - Error details.
  - **code** (integer) - Error code (400).
  - **message** (string) - Error message.

```

--------------------------------

### Query GitBook documentation with ask and goal parameters

Source: https://gitbook.com/docs/developers/integrations/quickstart

Perform an HTTP GET request to the documentation URL with the `ask` and `goal` query parameters. `ask` is the immediate question, `goal` describes the user's ultimate objective. The response contains a direct answer and relevant excerpts.

```http
GET https://gitbook.com/docs/developers/integrations/quickstart.md?ask=<question>&goal=<user_goal>
```

--------------------------------

### Query GitBook Documentation with ask and goal Parameters

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/list-all-integration-site-installations

Perform an HTTP GET request to query the GitBook documentation. Use the 'ask' parameter for the immediate question and 'goal' for the user's ultimate objective to get a tailored answer.

```http
GET https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/list-all-integration-site-installations.md?ask=<question>&goal=<user_goal>
```

--------------------------------

### Query documentation with ask and goal parameters

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/create-an-integration-installation-api-token

HTTP GET request to retrieve additional information from the documentation. Use the ask parameter for a specific question and goal for the user's ultimate objective. The response includes a direct answer and relevant excerpts.

```http
GET https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/create-an-integration-installation-api-token.md?ask=<question>&goal=<user_goal>
```

--------------------------------

### Query GitBook documentation with ask and goal parameters

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/get-an-integration-installation-by-its-id

Perform an HTTP GET request to query the documentation when the answer is not explicitly present on the page. Use the 'ask' parameter for the immediate question and 'goal' for the user's ultimate objective to get a tailored answer.

```http
GET https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/get-an-integration-installation-by-its-id.md?ask=<question>&goal=<user_goal>
```

--------------------------------

### Query GitBook documentation with ask and goal parameters

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/get-an-integration-site-installation

Perform an HTTP GET request to query the documentation for additional information not present on the page. Use the 'ask' parameter for the immediate question and 'goal' for the user's ultimate objective.

```http
GET https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/get-an-integration-site-installation.md?ask=<question>&goal=<user_goal>
```

--------------------------------

### POST /integrations/{integrationName}/installations

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/install-an-integration

Installs an integration on an organization, creating the account-level installation that space and site installations hang off. Configure it with the update operation, then enable it on individual spaces or sites.

```APIDOC
## POST /integrations/{integrationName}/installations

### Description
Installs an integration on an organization, creating the account-level installation that space and site installations hang off. Configure it with the update operation, then enable it on individual spaces or sites.

### Method
POST

### Endpoint
/integrations/{integrationName}/installations

### Parameters
#### Path Parameters
- **integrationName** (string) - Required - The name of the integration to install.

#### Request Body
- **organizationId** (string) - Required - The ID of the organization where the integration will be installed.

### Request Example
{
  "organizationId": "org_123"
}

### Response
#### Success Response (201)
- **id** (string) - The unique identifier of the installation.
- **status** (string) - The status of the installation (e.g., active, pending, paused).
- **space_selection** (string) - Whether all spaces are selected or a selection is involved.
- **site_selection** (string) - Whether all sites are selected or a selection is involved.
- **spaces** (array) - List of spaces associated with the installation.
- **configuration** (object) - Configuration of the integration at the account level.
- **urls** (object) - URLs related to the installation.
- **externalIds** (array) - External IDs assigned by the integration.
- **target** (object) - Target of the integration installation.
- **network** (object) - Network configuration for the installation.
- **createdAt** (string) - Timestamp of creation.
- **updatedAt** (string) - Timestamp of last update.

#### Response Example
{
  "id": "inst_123",
  "status": "active",
  "space_selection": "all",
  "site_selection": "all",
  "spaces": [],
  "configuration": {},
  "urls": {},
  "externalIds": [],
  "target": {},
  "network": {},
  "createdAt": "2023-01-01T00:00:00Z",
  "updatedAt": "2023-01-01T00:00:00Z"
}

### Error Responses
#### 404 Not Found
- **error** (object) - Contains error details.
  - **code** (integer) - Error code (404).
  - **message** (string) - Error message.
```

--------------------------------

### Query GitBook documentation with ask and goal parameters

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/install-an-integration-on-a-site

Perform an HTTP GET request to the GitBook documentation URL with the `ask` and `goal` query parameters to retrieve a direct answer and relevant excerpts. `ask` is the immediate question, `goal` describes the user's ultimate objective.

```http
GET https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/install-an-integration-on-a-site.md?ask=<question>&goal=<user_goal>
```

--------------------------------

### Query Documentation via HTTP GET with ask and goal parameters

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/list-all-integration-installations-1

Use this HTTP request to query the GitBook documentation when the answer is not explicitly present on the page. The `ask` parameter is the immediate, self-contained question; `goal` describes the user's ultimate outcome to help tailor the answer. The response contains a direct answer with relevant excerpts and sources.

```http
GET https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/list-all-integration-installations-1.md?ask=<question>&goal=<user_goal>
```

--------------------------------

### GET /integrations/{integrationName}/installations/{installationId}

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/get-an-integration-installation-by-its-id

Retrieves a specific integration installation by its ID. This endpoint returns details about the installation, including its status, configuration, and associated URLs.

```APIDOC
## [GET] /integrations/{integrationName}/installations/{installationId}

### Description
Retrieves a specific integration installation by its ID. This endpoint returns details about the installation, including its status, configuration, and associated URLs.

### Method
GET

### Endpoint
/integrations/{integrationName}/installations/{installationId}

### Parameters
#### Path Parameters
- **integrationName** (string) - Required - Name of the integration. Pattern: ^[a-zA-Z0-9-_.]+$, maxLength: 100
- **installationId** (string) - Required - Identifier of the installation

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the installation
- **status** (IntegrationInstallationStatus) - The status of the installation
- **space_selection** (IntegrationInstallationSpaceSelection) - The space selection configuration
- **site_selection** (IntegrationInstallationSiteSelection) - The site selection configuration
- **spaces** (number) - Count of spaces the installation is managing
- **configuration** (IntegrationInstallationConfiguration) - The configuration of the installation
- **createdAt** (Timestamp) - The creation timestamp
- **updatedAt** (Timestamp) - The last update timestamp
- **urls** (object) - URLs associated with the object
  - **location** (string) - URL of the installation in the API (format: uri)
  - **app** (string) - URL of the integration's installation in the application (format: uri)
  - **publicEndpoint** (string) - Public HTTP endpoint for the integration's installation (format: uri)
  - **publicContentEndpoint** (string) - Public endpoint serving the integration's rendered content (e.g. WebFrames), isolated from the cookie-bearing publicEndpoint origin.

#### Response Example
{
  "id": "string",
  "status": "string",
  "space_selection": {},
  "site_selection": {},
  "spaces": 0,
  "configuration": {},
  "createdAt": "string",
  "updatedAt": "string",
  "urls": {
    "location": "string",
    "app": "string",
    "publicEndpoint": "string",
    "publicContentEndpoint": "string"
  }
}
```

--------------------------------

### GET /integrations/{integrationName}/installations/{installationId}/spaces/{spaceId}

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/get-an-integration-space-installation

Retrieves the installation of a specific integration on a specific space. This endpoint returns the installation details including configuration, status, and associated URLs.

```APIDOC
## [GET] /integrations/{integrationName}/installations/{installationId}/spaces/{spaceId}

### Description
Retrieves the installation of a specific integration on a specific space. This endpoint returns the installation details including configuration, status, and associated URLs.

### Method
GET

### Endpoint
/integrations/{integrationName}/installations/{installationId}/spaces/{spaceId}

### Parameters
#### Path Parameters
- **integrationName** (string) - Required - Name of the integration. Must match pattern `^[a-zA-Z0-9-_.]+$` and have max length 100.
- **installationId** (string) - Required - Identifier of the installation.
- **spaceId** (string) - Required - The unique id of the space. Must match pattern `^[a-zA-Z0-9_-]+$`.

### Response
#### Success Response (200)
- **integration** (string) - Unique name identifier of the integration.
- **installation** (string) - ID of the integration installation.
- **status** (string) - Status of the installation. Possible values: `active`, `pending`, `paused`.
- **configuration** (object) - Configuration of the integration for this site.
- **externalIds** (array of strings) - External IDs assigned by the integration. Max 5 items.
- **urls** (object) - URLs associated with the object.
  - **location** (string) - URL of the integration's installation in the API.
  - **publicEndpoint** (string) - Public HTTP endpoint for the integration's installation.
  - **publicContentEndpoint** (string) - Public endpoint serving the integration's rendered content (e.g. WebFrames), isolated from the cookie-bearing publicEndpoint origin. Equals publicEndpoint when no separate content origin is configured.
- **space** (object) - The space the integration is installed on. Contains `object` (always "space"), `id`, `title`, and `emoji`.

#### Response Example
{
  "integration": "my-integration",
  "installation": "inst_123",
  "status": "active",
  "configuration": {},
  "externalIds": ["ext-1"],
  "urls": {
    "location": "https://api.gitbook.com/v1/integrations/my-integration/installations/inst_123",
    "publicEndpoint": "https://example.com/integration",
    "publicContentEndpoint": "https://content.example.com/integration"
  },
  "space": {
    "object": "space",
    "id": "space_123",
    "title": "My Space",
    "emoji": "📚"
  }
}
```

--------------------------------

### GET /integrations/{integration}/installations/{installationId}/spaces/{spaceId}

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/get-an-integration-space-installation

Retrieves details about a specific space installation for an integration. This endpoint returns information about how the integration is installed in a particular space, including configuration and state.

```APIDOC
## [GET] /integrations/{integration}/installations/{installationId}/spaces/{spaceId}

### Description
Retrieves details about a specific space installation for an integration. This endpoint returns information about how the integration is installed in a particular space, including configuration and state.

### Method
GET

### Endpoint
/integrations/{integration}/installations/{installationId}/spaces/{spaceId}

### Parameters
#### Path Parameters
- **integration** (string) - Required - The integration identifier.
- **installationId** (string) - Required - The installation identifier.
- **spaceId** (string) - Required - The space identifier.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the space installation.
- **space** (object) - The space details.
- **configuration** (object) - The configuration of the integration in the space.
- **state** (object) - The state of the integration in the space.

#### Response Example
{
  "id": "string",
  "space": {},
  "configuration": {},
  "state": {}
}
```

--------------------------------

### Bootstrap a new integration

Source: https://gitbook.com/docs/developers/integrations/quickstart

Create a new integration scaffold. Prompts ask for name, title, organization, and scopes.

```bash
gitbook integrations new
```

--------------------------------

### GET /integrations/{integrationName}/installations/{installationId}/spaces/{spaceId}

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/get-an-integration-space-installation

Returns the installation of an integration on one space, including the configuration of the integration for that space. This endpoint is used to retrieve details about a specific integration installation for a given space.

```APIDOC
## GET /integrations/{integrationName}/installations/{installationId}/spaces/{spaceId}

### Description
Returns the installation of an integration on one space, including the configuration of the integration for that space.

### Method
GET

### Endpoint
/integrations/{integrationName}/installations/{installationId}/spaces/{spaceId}

### Parameters
#### Path Parameters
- **integrationName** (string) - Required - Name of the integration
- **installationId** (string) - Required - ID of the installation
- **spaceId** (string) - Required - ID of the space

#### Query Parameters
- **extended** (boolean) - Optional - If true, returns the space object in each items. If false, returns the space ID in each items. Default: false

### Response
#### Success Response (200)
- **IntegrationSpaceInstallation** - The integration space installation object

#### Response Example
(No response example provided in the source)

#### Error Response (404)
- **error** (object) - Contains error details
  - **code** (integer) - Error code (404)
  - **message** (string) - Error message
```

--------------------------------

### GET /integrations/{integrationName}/installations/{installationId}/sites/{siteId}

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/get-an-integration-site-installation

Retrieves details about a specific integration installation on a site. This endpoint returns the installation's configuration, status, external IDs, and associated URLs.

```APIDOC
## GET /integrations/{integrationName}/installations/{installationId}/sites/{siteId}

### Description
Retrieves details about a specific integration installation on a site. This endpoint returns the installation's configuration, status, external IDs, and associated URLs.

### Method
GET

### Endpoint
/integrations/{integrationName}/installations/{installationId}/sites/{siteId}

### Parameters
#### Path Parameters
- **integrationName** (string) - Required - Name of the integration. Must match pattern `^[a-zA-Z0-9-_.]+$` and have max length 100.
- **installationId** (string) - Required - Identifier of the installation.
- **siteId** (string) - Required - The unique id of the site.

### Response
#### Success Response (200)
- **integration** (string) - Unique name identifier of the integration.
- **installation** (string) - ID of the integration installation.
- **status** (string) - Status of the installation. Possible values: `active`, `pending`, `paused`.
- **configuration** (object) - Configuration of the integration for this site.
- **externalIds** (array of strings) - External IDs assigned by the integration. Max 5 items.
- **urls** (object) - URLs associated with the object.
  - **location** (string) - URL of the integration's installation in the API.
  - **publicEndpoint** (string) - Public HTTP endpoint for the integration's installation.
  - **publicContentEndpoint** (string) - Public endpoint serving the integration's rendered content (e.g., WebFrames), isolated from the cookie-bearing publicEndpoint origin. Equals publicEndpoint when no separate content origin is configured.
- **site** (object or string) - The site the integration is installed on. Using the string value is deprecated in favor of `site.id`.
  - **object** (string) - Always `site`.
  - **id** (string) - Unique identifier of the site.
  - **type** (string) - Type of the site.
  - **appliedType** (string) - The currently applied type of the site. For example, frozen sites will have this set to Basic.
  - **unpublishedBy** (string) - Who unpublished this site last. Possible values: `user`, `system`.

#### Response Example
```json
{
  "integration": "my-integration",
  "installation": "inst_123",
  "status": "active",
  "configuration": {},
  "externalIds": ["ext-1"],
  "urls": {
    "location": "https://api.gitbook.com/v1/integrations/my-integration/installations/inst_123",
    "publicEndpoint": "https://example.com",
    "publicContentEndpoint": "https://content.example.com"
  },
  "site": {
    "object": "site",
    "id": "site_456",
    "type": "basic",
    "appliedType": "basic",
    "unpublishedBy": "user"
  }
}
```
```

--------------------------------

### Publish a site

Source: https://gitbook.com/docs/guides/editing-and-publishing-documentation/create-and-publish-a-site-from-the-command-line

Publishes the site. The `--full` flag shows all fields; look for `published` under `urls` to find the live site.

```bash
gitbook organizations sites publish <organizationId> <siteId> --full
```

--------------------------------

### GET /orgs/{organizationId}/integrations/{integrationName}/installation_status

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/get-the-status-of-an-integration

Returns whether an integration is installed for the organization and the status of that installation. Use this for a single integration instead of listing every status.

```APIDOC
## [GET] /orgs/{organizationId}/integrations/{integrationName}/installation_status

### Description
Returns whether an integration is installed for the organization and the status of that installation. Use this for a single integration instead of listing every status.

### Method
GET

### Endpoint
/orgs/{organizationId}/integrations/{integrationName}/installation_status

### Parameters
#### Path Parameters
- **organizationId** (string) - Required - The unique id of the organization
- **integrationName** (string) - Required - Name of the integration.

### Response
#### Success Response (200)
- **status** (string) - The status of the integration installation. Possible values: active, pending, paused.

#### Response Example
{
  "status": "active"
}

#### Error Response (404)
- **error** (object) - Error details
  - **code** (integer) - Error code (404)
  - **message** (string) - Error message
```

--------------------------------

### Create a site

Source: https://gitbook.com/docs/guides/editing-and-publishing-documentation/create-and-publish-a-site-from-the-command-line

Creates a site with the space as its content source. The `--visibility public` makes it public; `--spaces` accepts a JSON array of space IDs. Add `--type basic` to start on the free tier if needed.

```bash
gitbook organizations sites create <organizationId> --title "Product docs" --visibility public --spaces '["<spaceId>"]'
```

--------------------------------

### GET /integrations/{integrationName}/installations/{installationId}/spaces

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/list-all-space-integration-installations

Lists all space integration installations for a given integration and installation. This endpoint requires the integration:installations:read scope.

```APIDOC
## [GET] /integrations/{integrationName}/installations/{installationId}/spaces

### Description
Lists all space integration installations for a given integration and installation. This endpoint requires the integration:installations:read scope.

### Method
GET

### Endpoint
/integrations/{integrationName}/installations/{installationId}/spaces

### Parameters
#### Path Parameters
- **integrationName** (string) - Required - Name of the integration. Pattern: ^[a-zA-Z0-9-_.]+$, maxLength: 100
- **installationId** (string) - Required - Identifier of the installation

#### Query Parameters
- **page** (string) - Optional - Identifier of the page results to fetch.
- **limit** (number) - Optional - The number of results per page. Minimum: 0, Maximum: 1000

### Response
#### Success Response (200)
- **next** (object) - Contains the next page identifier
  - **page** (string) - Unique identifier to query the next results page
- **count** (number) - Total count of objects in the list
- **items** (array) - List of IntegrationSpaceInstallation objects
  - **integration** (string) - Unique name identifier of the integration
  - **installation** (string) - ID of the integration installation
  - **status** (IntegrationInstallationStatus) - Status of the installation
  - **configuration** (object) - Configuration of the integration for this site
  - **externalIds** (IntegrationInstallationExternalIds) - External IDs associated with the installation
  - **urls** (object) - URLs associated with the object
    - **location** (string) - URL of the integration's installation in the API
    - **publicEndpoint** (string) - Public HTTP endpoint for the integration's installation
    - **publicContentEndpoint** (string) - Public endpoint serving the integration's rendered content
  - **space** (object or string) - The space the integration is installed on. Using the string value is deprecated in favor of space.id

#### Response Example
{
  "next": {
    "page": "string"
  },
  "count": 0,
  "items": [
    {
      "integration": "string",
      "installation": "string",
      "status": "string",
      "configuration": {},
      "externalIds": {},
      "urls": {
        "location": "string",
        "publicEndpoint": "string",
        "publicContentEndpoint": "string"
      },
      "space": {}
    }
  ]
}
```

--------------------------------

### GET /integrations/{integrationName}/installations/{installationId}/sites

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/list-all-site-integration-installations

Returns a paginated list of the sites an installation is enabled on, with the configuration of the integration for each of them. Pass extended to get the full site object instead of its ID.

```APIDOC
## [GET] /integrations/{integrationName}/installations/{installationId}/sites

### Description
Returns a paginated list of the sites an installation is enabled on, with the configuration of the integration for each of them. Pass extended to get the full site object instead of its ID.

### Method
GET

### Endpoint
/integrations/{integrationName}/installations/{installationId}/sites

### Parameters
#### Path Parameters
- **integrationName** (string) - Required - The name of the integration.
- **installationId** (string) - Required - The ID of the installation.

#### Query Parameters
- **extended** (boolean) - Optional - If true, returns the full site object instead of its ID.

### Response
#### Success Response (200)
- **sites** (array) - List of sites with their configuration.

#### Response Example
{
  "sites": [
    {
      "id": "string",
      "configuration": {}
    }
  ]
}
```

--------------------------------

### Manual remote setup instructions for handoff

Source: https://gitbook.com/docs/skill/configure-site

Provide these instructions to the user when neither gh nor glab is available, to create a remote repository manually and push the local repository.

```bash
git remote add origin <url> && git push -u origin main
```

--------------------------------

### GET /integrations/{integrationName}/installations/{installationId}

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/get-an-integration-installation-by-its-id

Returns the organization-level installation of an integration, including its account configuration and how many spaces it manages. The configuration can contain credentials the integration stored for third-party services.

```APIDOC
## GET /integrations/{integrationName}/installations/{installationId}

### Description
Returns the organization-level installation of an integration, including its account configuration and how many spaces it manages. The configuration can contain credentials the integration stored for third-party services.

### Method
GET

### Endpoint
/integrations/{integrationName}/installations/{installationId}

### Parameters
#### Path Parameters
- **integrationName** (string) - Required - The name of the integration.
- **installationId** (string) - Required - The ID of the integration installation.

### Response
#### Success Response (200)
- **id** (string) - Required - The unique identifier of the installation.
- **status** (IntegrationInstallationStatus) - Required - The status of the installation (active, pending, paused).
- **space_selection** (IntegrationInstallationSpaceSelection) - Required - Whether all spaces have been selected or there's a selection involved (all, selected).
- **site_selection** (IntegrationInstallationSiteSelection) - Required - Whether all sites have been selected or there's a selection involved (all, selected).
- **spaces** (array) - Required - The spaces managed by the installation.
- **configuration** (IntegrationInstallationConfiguration) - Required - Configuration of the integration at the account level.
- **urls** (object) - Required - URLs for the installation, including location, app, publicEndpoint, and publicContentEndpoint.
- **externalIds** (IntegrationInstallationExternalIds) - Required - External IDs assigned by the integration (max 5 items).
- **target** (IntegrationInstallationTarget) - Required - Target of the integration installation (organization).
- **network** (IntegrationNetwork) - Required - Network configuration for the installation (proxy flag).
- **createdAt** (Timestamp) - Required - Creation timestamp.
- **updatedAt** (Timestamp) - Required - Last update timestamp.

#### Response Example
```json
{
  "id": "string",
  "status": "active",
  "space_selection": "all",
  "site_selection": "all",
  "spaces": [],
  "configuration": {},
  "urls": {
    "location": "string",
    "app": "string",
    "publicEndpoint": "string",
    "publicContentEndpoint": "string"
  },
  "externalIds": [],
  "target": {
    "organization": "string"
  },
  "network": {
    "proxy": false
  },
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}
```

#### Error Response (404)
- **error** (object) - Required - Error details.
  - **code** (integer) - Required - Error code (404).
  - **message** (string) - Required - Error message.

#### Error Response Example
```json
{
  "error": {
    "code": 404,
    "message": "Not Found"
  }
}
```
```

--------------------------------

### Initialize Git repository and initial commit

Source: https://gitbook.com/docs/skill/configure-site

Run after scaffolding the site to initialize a local Git repository and create the initial commit.

```bash
cd my-docs
git init
git add .
git commit -m "Initial scaffold"
```

--------------------------------

### GET /integrations/{integrationName}/installations/{installationId}

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/get-an-integration-installation-by-its-id

Returns the organization-level installation of an integration, including its account configuration and how many spaces it manages. The configuration can contain credentials the integration stored for third-party services.

```APIDOC
## [GET] /integrations/{integrationName}/installations/{installationId}

### Description
Returns the organization-level installation of an integration, including its account configuration and how many spaces it manages. The configuration can contain credentials the integration stored for third-party services.

### Method
GET

### Endpoint
`/integrations/{integrationName}/installations/{installationId}`

### Parameters
#### Path Parameters
- **integrationName** (string) - Required - The name of the integration.
- **installationId** (string) - Required - The ID of the integration installation.

### Response
#### Success Response (200)
Returns the integration installation details, including account configuration and space count.

#### Response Example
```json
{
  "id": "string",
  "integration": "string",
  "organization": "string",
  "configuration": {},
  "spaces_count": 0
}
```

### Authentication
Requires authentication via one of the following schemes: `user`, `integration`, `integration-installation`, or OAuth with scope `integration:installations:read`.
```

--------------------------------

### GET /integrations/{integrationName}/installations/{installationId}/sites

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/list-all-site-integration-installations

Retrieves a paginated list of all site installations for a specific integration installation. This endpoint requires the integration:installations:read permission.

```APIDOC
## GET /integrations/{integrationName}/installations/{installationId}/sites

### Description
Retrieves a paginated list of all site installations for a specific integration installation. This endpoint requires the integration:installations:read permission.

### Method
GET

### Endpoint
/integrations/{integrationName}/installations/{installationId}/sites

### Parameters
#### Path Parameters
- **integrationName** (string) - Required - Name of the integration. Must match pattern `^[a-zA-Z0-9-_.]+$` and have a maximum length of 100.
- **installationId** (string) - Required - Identifier of the installation.

#### Query Parameters
- **page** (string) - Optional - Identifier of the page results to fetch.
- **limit** (number) - Optional - The number of results per page. Minimum 0, maximum 1000.

### Response
#### Success Response (200)
- **next** (object) - Contains the pagination token for the next page.
  - **page** (string) - Unique identifier to query the next results page.
- **count** (number) - Total count of objects in the list.
- **items** (array) - List of integration site installations.
  - **integration** (string) - Unique name identifier of the integration.
  - **installation** (string) - ID of the integration installation.
  - **status** (IntegrationInstallationStatus) - Status of the installation.
  - **configuration** (object) - Configuration of the integration for this site.
  - **externalIds** (object) - External identifiers associated with the installation.
  - **urls** (object) - URLs associated with the installation.
    - **location** (string) - URL of the integration's installation in the API.
    - **publicEndpoint** (string) - Public HTTP endpoint for the integration's installation.
    - **publicContentEndpoint** (string) - Public endpoint serving the integration's rendered content.
  - **site** (object) - The site the integration is installed on. Can be a string (deprecated) or an object with an `id` field.

#### Response Example
```json
{
  "next": {
    "page": "string"
  },
  "count": 0,
  "items": [
    {
      "integration": "string",
      "installation": "string",
      "status": "string",
      "configuration": {},
      "externalIds": {},
      "urls": {
        "location": "string",
        "publicEndpoint": "string",
        "publicContentEndpoint": "string"
      },
      "site": {
        "id": "string"
      }
    }
  ]
}
```
```

--------------------------------

### JavaScript: Install GitBook API client

Source: https://gitbook.com/docs/developers/gitbook-api/quickstart

Install the GitBook API client library using npm. Required before initializing the client and sending an Ask query.

```bash
npm install @gitbook/api
```

--------------------------------

### Example configuration with account and site properties

Source: https://gitbook.com/docs/developers/integrations/configurations

Shows a full `configurations` block with `account` and `site` keys, including required properties and various property types.

```yaml
configurations:
    account:
        properties:
            oauth_credentials:
                type: button
                title: Connection
                description: Authorization between my app and GitBook.
                button_text: Authorize
                callback_url: /oauth
            default_channel:
                type: string
                title: Default Channel
                description: Select a channel to post messages to, when none is configured for a specific space.
                completion_url: /channels
        required:
            - oauth_credentials
            - default_channel
    site:
        properties:
            channel:
                type: string
                title: Channel
                description: Select a channel to post messages related to this space.
                completion_url: /channels
            notify_content_update:
                type: boolean
                title: Notify Content Update
                description: Post a notification message every time the content of the space is updated.
                default: true
            notify_visibility_update:
                type: boolean
                title: Notify Visibility Update
                description: Post a notification message every time the visibility of the space is updated.
                default: true
```

--------------------------------

### GET /integrations/{integrationName}/installations/{installationId}/sites/{siteId}

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/get-an-integration-site-installation

Returns the installation of an integration on one site, including the configuration of the integration for that site. This endpoint is part of the GitBook API integrations reference.

```APIDOC
## GET /integrations/{integrationName}/installations/{installationId}/sites/{siteId}

### Description
Returns the installation of an integration on one site, including the configuration of the integration for that site.

### Method
GET

### Endpoint
/integrations/{integrationName}/installations/{installationId}/sites/{siteId}

### Parameters
#### Path Parameters
- **integrationName** (string) - Required - The name of the integration.
- **installationId** (string) - Required - The ID of the installation.
- **siteId** (string) - Required - The ID of the site.

#### Query Parameters
- **extended** (boolean) - Optional - If true, returns the site object in each items. If false, returns the site ID in each items. Default: false.

### Response
#### Success Response (200)
- **IntegrationSiteInstallation** (object) - The integration site installation object.

#### Response Example
```json
{
  "type": "object",
  "properties": {
    "site": {
      "type": "string"
    },
    "configuration": {
      "type": "object"
    }
  },
  "required": ["site", "configuration"]
}
```

#### Error Response (404)
- **error** (object) - Error details.
  - **code** (integer) - Error code, always 404.
  - **message** (string) - Error message.

#### Error Response Example
```json
{
  "error": {
    "code": 404,
    "message": "Not Found"
  }
}
```
```

--------------------------------

### GET /orgs/{organizationId}/styleguides

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/organizations/list-all-style-guides-in-an-organization

Retrieves all style guides within a specified organization. Each style guide includes its associated space and the sites that reference it.

```APIDOC
## [GET] /orgs/{organizationId}/styleguides

### Description
Retrieves all style guides within a specified organization. Each style guide includes its associated space and the sites that reference it.

### Method
GET

### Endpoint
/orgs/{organizationId}/styleguides

### Parameters
#### Path Parameters
- **organizationId** (string) - Required - The unique id of the organization

### Response
#### Success Response (200)
- **styleguides** (array) - List of style guides in the organization
  - **space** (object) - The space associated with the style guide
  - **sites** (array) - Sites in the organization that reference this style guide

#### Response Example
{
  "styleguides": [
    {
      "space": {
        "object": "space",
        "id": "string",
        "title": "string",
        "emoji": "string",
        "visibility": "string",
        "createdAt": "string",
        "updatedAt": "string",
        "deletedAt": "string",
        "editMode": "string",
        "type": "styleguide",
        "mergeRules": {},
        "urls": {
          "location": "string",
          "app": "string",
          "published": "string",
          "public": "string",
          "icon": "string"
        },
        "organization": "string",
        "parent": "string",
        "language": "string",
        "gitSync": {},
        "previousGitSync": {},
        "imports": []
      },
      "sites": [
        {
          "id": "string",
          "title": "string"
        }
      ]
    }
  ]
}
```

--------------------------------

### Query GitBook Documentation with ask and goal Parameters

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/spaces/space-content/apply-a-content-template-to-populate-a-space-with-initial-pages

Perform an HTTP GET request to query the GitBook documentation for additional information. Use the `ask` parameter for the immediate question and `goal` for the user's ultimate objective to get a tailored answer.

```http
GET https://gitbook.com/docs/developers/gitbook-api/api-reference/spaces/space-content/apply-a-content-template-to-populate-a-space-with-initial-pages.md?ask=<question>&goal=<user_goal>
```

--------------------------------

### Prompt for an AI agent to create and publish a docs site

Source: https://gitbook.com/docs/guides/editing-and-publishing-documentation/create-and-publish-a-site-from-the-command-line

Paste this prompt into an AI coding agent to automate the entire workflow. It instructs the agent to check sign-in, list organizations, ask for details, create a space, add a page via a change request, create and publish a site, and read the live URL. The agent must use --json, show each command, and stop on failure.

```markdown
Using the `gitbook` CLI, create and publish a new GitBook docs site for me.

1. Run `gitbook whoami` to check I'm signed in. If I'm not, tell me to run `gitbook login` and stop there.
2. Run `gitbook organizations list` and show me what you find. Ask me which organization to use — don't guess, even if there's only one.
3. Ask me what the site should be called and what the first page should say. Show me the title, visibility and page outline you're planning, then wait for my yes before you create anything.
4. Create the space. Add the first page through a change request: create it, apply the content with `--changes`, then merge it. Use `##` and below for headings within the page.
5. Create the site with the space attached, publish it, then read the live URL back to me from `urls.published`.

Use `--json` so you can parse the output, show me each command before you run it, and stop if any of them fail.
```

--------------------------------

### GET /orgs/{organizationId}/installations

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/list-all-integration-installations-1

Retrieves a list of all integration installations for a given organization. Returns a paginated list of integrations with their associated installations.

```APIDOC
## [GET] /orgs/{organizationId}/installations

### Description
Retrieves a list of all integration installations for a given organization. Returns a paginated list of integrations with their associated installations.

### Method
GET

### Endpoint
/orgs/{organizationId}/installations

### Parameters
#### Path Parameters
- **organizationId** (string) - Required - The unique identifier of the organization.

#### Query Parameters
- **page** (integer) - Optional - The page number to retrieve.
- **limit** (integer) - Optional - The number of items per page.
- **query** (string) - Optional - A search query to filter integrations.

### Response
#### Success Response (200)
- **items** (array) - List of objects containing integration and installation details.
  - **integration** (Integration) - The integration object.
  - **installation** (IntegrationInstallation) - The installation object.

#### Response Example
{
  "items": [
    {
      "integration": {},
      "installation": {}
    }
  ]
}
```

--------------------------------

### Query the documentation with ask and goal parameters

Source: https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/render-an-integration-ui-with-get-method

Perform an HTTP GET request to retrieve additional documentation context. Use the `ask` parameter for the immediate question and `goal` for the user's ultimate objective. The response contains a direct answer and relevant excerpts.

```http
GET https://gitbook.com/docs/developers/gitbook-api/api-reference/integrations/render-an-integration-ui-with-get-method.md?ask=<question>&goal=<user_goal>
```

--------------------------------

### Repo-level README.md example

Source: https://gitbook.com/docs/skill/configure-site

A short paragraph for the repo-level README.md that explains the folder's purpose and relation to the published site, without duplicating docs.

```markdown
# my-docs

Source for the [My Product docs site](https://docs.example.com). Each top-level folder
is a separate GitBook space; edits flow in both directions via Git Sync once configured.
```

--------------------------------

### Initialize GitBook instance

Source: https://gitbook.com/docs/publish/embedding/implementation/nodejs

Create a GitBook instance with your docs site URL.

```javascript
const gitbook = createGitBook({
  siteURL: "https://docs.company.com",
});
```
Tokens:
Raw