The State of Docs Survey 2025. Use your voice to prove why docs matter:
Take the survey
Product
PricingLog inSign up

Docs sites

Manage your published docs sites.

List all the sites created in an organization

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Query parameters
pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

spacestringoptional

Identifier of the space to filter the sites by

titlestringoptional

Filter sites by their title

publishedbooleanoptional

Filter sites by their published status

typestring · enum[]optional

Filter by site type

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "site",
      "id": "text",
      "type": "basic",
      "title": "text",
      "hostname": "text",
      "basename": "text",
      "proxy": {
        "origin": "text",
        "target": "text"
      },
      "visibility": "public",
      "published": true,
      "siteSpaces": 1,
      "createdAt": "2025-04-03T19:42:46.828Z",
      "adaptiveContent": {
        "enabled": true
      },
      "ads": {
        "status": "pending",
        "submittable": true
      },
      "features": [
        {
          "id": "sites-sections",
          "plan": "basic",
          "frozen": true
        }
      ],
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com",
        "published": "https://example.com"
      }
    }
  ]
}

OK

Create a site in an organization

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

Body
typestring · enumoptional

The type of the site, defaults to Basic

Available options:
titlestring · min: 2 · max: 128optional

Title of the site

visibilitystring · enumoptional

The visibility setting of the site determines the audience of the site.

  • public: Anyone can access the site, and the site is indexed by search engines.
  • unlisted: Anyone can access the site, and the site is not indexed by search engines
  • share-link: Anyone with a secret token in the url can access the site.
  • visitor-auth: Anyone authenticated through a JWT token can access the site.
Available options:
spacesone ofoptional

ID of spaces to be added to the site

Create a new space associated to the site

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "basic",
    "title": "text",
    "visibility": "public",
    "spaces": [
      "text"
    ]
  }'
{
  "object": "site",
  "id": "text",
  "type": "basic",
  "title": "text",
  "hostname": "text",
  "basename": "text",
  "proxy": {
    "origin": "text",
    "target": "text"
  },
  "visibility": "public",
  "published": true,
  "siteSpaces": 1,
  "createdAt": "2025-04-03T19:42:46.828Z",
  "adaptiveContent": {
    "enabled": true
  },
  "ads": {
    "status": "pending",
    "submittable": true
  },
  "features": [
    {
      "id": "sites-sections",
      "plan": "basic",
      "frozen": true
    }
  ],
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com"
  }
}

Site created

Get an organization site by its ID

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "object": "site",
  "id": "text",
  "type": "basic",
  "title": "text",
  "hostname": "text",
  "basename": "text",
  "proxy": {
    "origin": "text",
    "target": "text"
  },
  "visibility": "public",
  "published": true,
  "siteSpaces": 1,
  "createdAt": "2025-04-03T19:42:46.828Z",
  "adaptiveContent": {
    "enabled": true
  },
  "ads": {
    "status": "pending",
    "submittable": true
  },
  "features": [
    {
      "id": "sites-sections",
      "plan": "basic",
      "frozen": true
    }
  ],
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com"
  }
}

OK

Delete a site in an organization

delete
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Responses
curl -L \
  --request DELETE \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No body

Site has been deleted

Update a site in an organization

patch
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Body
titlestring · min: 2 · max: 128optional

Title of the site

visibilitystring · enumoptional

The visibility setting of the site determines the audience of the site.

  • public: Anyone can access the site, and the site is indexed by search engines.
  • unlisted: Anyone can access the site, and the site is not indexed by search engines
  • share-link: Anyone with a secret token in the url can access the site.
  • visitor-auth: Anyone authenticated through a JWT token can access the site.
Available options:
basenamestring · min: 1 · max: 100optional

Basename for the site. For e.g. api

adaptiveContentobjectoptional

defaultSiteSpacestringoptional

ID of the site-space to be used as the default at the root level. If site has sections, this will mark the default site space in the site's default section.

defaultSiteSectionstringoptional

ID of the site-section to be used as the default.

proxyone ofoptional

Configure a proxy URL for a site. For example, you can use it to host the site on a subdirectory of your domain like https://company.com/docs. Use null to remove the proxy.

Proxy URL for the site, for e.g. company.com/docs or www.company.com/developer/docs etc.

Responses
curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "text",
    "visibility": "public",
    "basename": "text",
    "adaptiveContent": {
      "enabled": true
    },
    "defaultSiteSpace": "text",
    "defaultSiteSection": "text",
    "proxy": "text"
  }'
{
  "object": "site",
  "id": "text",
  "type": "basic",
  "title": "text",
  "hostname": "text",
  "basename": "text",
  "proxy": {
    "origin": "text",
    "target": "text"
  },
  "visibility": "public",
  "published": true,
  "siteSpaces": 1,
  "createdAt": "2025-04-03T19:42:46.828Z",
  "adaptiveContent": {
    "enabled": true
  },
  "ads": {
    "status": "pending",
    "submittable": true
  },
  "features": [
    {
      "id": "sites-sections",
      "plan": "basic",
      "frozen": true
    }
  ],
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com"
  }
}

OK

Get the complete profile of a site in an organization to provide the published experience. It includes site, customization, structure, integration scripts etc.

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters
shareKeystringoptional

For sites published via share-links, the share key is useful to resolve published URLs.

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/published' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "object": "published-content-site",
  "site": {
    "object": "site",
    "id": "text",
    "type": "basic",
    "title": "text",
    "hostname": "text",
    "basename": "text",
    "proxy": {
      "origin": "text",
      "target": "text"
    },
    "visibility": "public",
    "published": true,
    "siteSpaces": 1,
    "createdAt": "2025-04-03T19:42:46.828Z",
    "adaptiveContent": {
      "enabled": true
    },
    "ads": {
      "status": "pending",
      "submittable": true
    },
    "features": [
      {
        "id": "sites-sections",
        "plan": "basic",
        "frozen": true
      }
    ],
    "urls": {
      "location": "https://example.com",
      "app": "https://example.com",
      "published": "https://example.com"
    }
  },
  "structure": {
    "type": "sections",
    "structure": [
      {
        "object": "site-section",
        "id": "text",
        "title": "text",
        "description": "text",
        "default": true,
        "path": "text",
        "condition": "text",
        "sectionGroup": "text",
        "siteSpaces": [
          {
            "object": "site-space",
            "id": "text",
            "path": "text",
            "section": "text",
            "space": {
              "object": "space",
              "id": "text",
              "title": "text",
              "emoji": "🎉",
              "visibility": "public",
              "createdAt": "2025-04-03T19:42:46.828Z",
              "updatedAt": "2025-04-03T19:42:46.828Z",
              "deletedAt": "2025-04-03T19:42:46.828Z",
              "editMode": "live",
              "urls": {
                "location": "https://example.com",
                "app": "https://example.com",
                "published": "https://example.com",
                "public": "https://example.com",
                "icon": "https://example.com"
              },
              "organization": "text",
              "parent": "text",
              "gitSync": {
                "repoName": "text",
                "installationProvider": "github",
                "integration": "text",
                "url": "text",
                "updatedAt": "2025-04-03T19:42:46.828Z"
              },
              "visitorAuth": {
                "backend": "custom"
              },
              "revision": "text",
              "defaultLevel": "admin",
              "comments": 1,
              "changeRequests": 1,
              "changeRequestsOpen": 1,
              "changeRequestsDraft": 1,
              "permissions": {
                "access": true,
                "admin": true,
                "edit": true,
                "comment": true,
                "merge": true,
                "review": true
              }
            },
            "title": "text",
            "default": true,
            "condition": "text",
            "hasAdvancedCustomizationFeature": true,
            "urls": {
              "published": "https://example.com"
            }
          }
        ],
        "urls": {
          "published": "https://example.com"
        },
        "icon": "gear"
      }
    ]
  },
  "customizations": {
    "site": {
      "title": "text",
      "styling": {
        "theme": "clean",
        "primaryColor": {
          "light": "text",
          "dark": "text"
        },
        "tint": {
          "color": {
            "light": "text",
            "dark": "text"
          }
        },
        "infoColor": {
          "light": "text",
          "dark": "text"
        },
        "successColor": {
          "light": "text",
          "dark": "text"
        },
        "warningColor": {
          "light": "text",
          "dark": "text"
        },
        "dangerColor": {
          "light": "text",
          "dark": "text"
        },
        "corners": "straight",
        "links": "default",
        "font": "ABCFavorit",
        "background": "plain",
        "icons": "regular",
        "sidebar": {
          "background": "default",
          "list": "default"
        },
        "search": "prominent"
      },
      "internationalization": {
        "locale": "en"
      },
      "favicon": {
        "icon": {
          "light": "https://example.com",
          "dark": "https://example.com"
        }
      },
      "header": {
        "preset": "default",
        "logo": {
          "light": "https://example.com",
          "dark": "https://example.com"
        },
        "backgroundColor": {
          "light": "text",
          "dark": "text"
        },
        "linkColor": {
          "light": "text",
          "dark": "text"
        },
        "links": [
          {
            "title": "text",
            "style": "link",
            "to": {
              "kind": "file",
              "file": "text"
            },
            "links": [
              {
                "title": "text",
                "to": {
                  "kind": "file",
                  "file": "text"
                }
              }
            ]
          }
        ]
      },
      "footer": {
        "logo": {
          "light": "https://example.com",
          "dark": "https://example.com"
        },
        "groups": [
          {
            "title": "text",
            "links": [
              {
                "title": "text",
                "to": {
                  "kind": "file",
                  "file": "text"
                }
              }
            ]
          }
        ],
        "copyright": "text"
      },
      "announcement": {
        "enabled": true,
        "message": "text",
        "link": {
          "title": "text",
          "to": {
            "kind": "file",
            "file": "text"
          }
        },
        "style": "info"
      },
      "themes": {
        "default": "light",
        "toggeable": true
      },
      "pdf": {
        "enabled": true
      },
      "feedback": {
        "enabled": true
      },
      "aiSearch": {
        "enabled": true
      },
      "ai": {
        "pageLinkSummaries": {
          "enabled": true
        }
      },
      "advancedCustomization": {
        "enabled": true
      },
      "git": {
        "showEditLink": true
      },
      "pagination": {
        "enabled": true
      },
      "trademark": {
        "enabled": true
      },
      "privacyPolicy": {
        "url": "https://example.com"
      },
      "socialPreview": {
        "url": "https://example.com"
      },
      "insights": {
        "trackingCookie": true
      }
    },
    "siteSpaces": {
      "ANY_ADDITIONAL_PROPERTY": {
        "title": "text",
        "styling": {
          "theme": "clean",
          "primaryColor": {
            "light": "text",
            "dark": "text"
          },
          "tint": {
            "color": {
              "light": "text",
              "dark": "text"
            }
          },
          "infoColor": {
            "light": "text",
            "dark": "text"
          },
          "successColor": {
            "light": "text",
            "dark": "text"
          },
          "warningColor": {
            "light": "text",
            "dark": "text"
          },
          "dangerColor": {
            "light": "text",
            "dark": "text"
          },
          "corners": "straight",
          "links": "default",
          "font": "ABCFavorit",
          "background": "plain",
          "icons": "regular",
          "sidebar": {
            "background": "default",
            "list": "default"
          },
          "search": "prominent"
        },
        "internationalization": {
          "locale": "en"
        },
        "favicon": {
          "icon": {
            "light": "https://example.com",
            "dark": "https://example.com"
          }
        },
        "header": {
          "preset": "default",
          "logo": {
            "light": "https://example.com",
            "dark": "https://example.com"
          },
          "backgroundColor": {
            "light": "text",
            "dark": "text"
          },
          "linkColor": {
            "light": "text",
            "dark": "text"
          },
          "links": [
            {
              "title": "text",
              "style": "link",
              "to": {
                "kind": "file",
                "file": "text"
              },
              "links": [
                {
                  "title": "text",
                  "to": {
                    "kind": "file",
                    "file": "text"
                  }
                }
              ]
            }
          ]
        },
        "footer": {
          "logo": {
            "light": "https://example.com",
            "dark": "https://example.com"
          },
          "groups": [
            {
              "title": "text",
              "links": [
                {
                  "title": "text",
                  "to": {
                    "kind": "file",
                    "file": "text"
                  }
                }
              ]
            }
          ],
          "copyright": "text"
        },
        "announcement": {
          "enabled": true,
          "message": "text",
          "link": {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          },
          "style": "info"
        },
        "themes": {
          "default": "light",
          "toggeable": true
        },
        "pdf": {
          "enabled": true
        },
        "feedback": {
          "enabled": true
        },
        "aiSearch": {
          "enabled": true
        },
        "ai": {
          "pageLinkSummaries": {
            "enabled": true
          }
        },
        "advancedCustomization": {
          "enabled": true
        },
        "git": {
          "showEditLink": true
        },
        "pagination": {
          "enabled": true
        },
        "trademark": {
          "enabled": true
        },
        "privacyPolicy": {
          "url": "https://example.com"
        },
        "socialPreview": {
          "url": "https://example.com"
        },
        "insights": {
          "trackingCookie": true
        }
      }
    }
  },
  "scripts": [
    {
      "script": "https://example.com",
      "contentSecurityPolicy": "text",
      "cookies": true
    }
  ]
}

OK

Publishes the site to the audience defined in the site's visibility setting.

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/publish' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "object": "site",
  "id": "text",
  "type": "basic",
  "title": "text",
  "hostname": "text",
  "basename": "text",
  "proxy": {
    "origin": "text",
    "target": "text"
  },
  "visibility": "public",
  "published": true,
  "siteSpaces": 1,
  "createdAt": "2025-04-03T19:42:46.828Z",
  "adaptiveContent": {
    "enabled": true
  },
  "ads": {
    "status": "pending",
    "submittable": true
  },
  "features": [
    {
      "id": "sites-sections",
      "plan": "basic",
      "frozen": true
    }
  ],
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com"
  }
}

Site published successfully

Unpublishes the site.

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/unpublish' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "object": "site",
  "id": "text",
  "type": "basic",
  "title": "text",
  "hostname": "text",
  "basename": "text",
  "proxy": {
    "origin": "text",
    "target": "text"
  },
  "visibility": "public",
  "published": true,
  "siteSpaces": 1,
  "createdAt": "2025-04-03T19:42:46.828Z",
  "adaptiveContent": {
    "enabled": true
  },
  "ads": {
    "status": "pending",
    "submittable": true
  },
  "features": [
    {
      "id": "sites-sections",
      "plan": "basic",
      "frozen": true
    }
  ],
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com"
  }
}

Site unpublished successfully

List all the share links created in a site

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters
pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/share-links' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "share-link",
      "id": "text",
      "createdAt": "2025-04-03T19:42:46.828Z",
      "name": "text",
      "active": true,
      "urls": {
        "published": "https://example.com"
      }
    }
  ]
}

OK

Create a share link in a site

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Body
namestring · max: 50required

Name of the share link

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/share-links' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "text"
  }'
{
  "object": "share-link",
  "id": "text",
  "createdAt": "2025-04-03T19:42:46.828Z",
  "name": "text",
  "active": true,
  "urls": {
    "published": "https://example.com"
  }
}

The share link has been created

Deletes a site share link

delete
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

shareLinkIdstringrequired

The unique id of the share link

Responses
curl -L \
  --request DELETE \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/share-links/{shareLinkId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No body

Site share link has been deleted

Update the details of a site share link

patch
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

shareLinkIdstringrequired

The unique id of the share link

Body
activebooleanoptional
namestring · max: 50optional

Name of the share link

Responses
curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/share-links/{shareLinkId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "active": true,
    "name": "text"
  }'
{
  "object": "share-link",
  "id": "text",
  "createdAt": "2025-04-03T19:42:46.828Z",
  "name": "text",
  "active": true,
  "urls": {
    "published": "https://example.com"
  }
}

The site share link has been updated

Get the structure of a site which includes site-sections and site-spaces

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters
shareKeystringoptional

For sites published via share-links, the share key is useful to resolve published URLs.

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/structure' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "type": "sections",
  "structure": [
    {
      "object": "site-section",
      "id": "text",
      "title": "text",
      "description": "text",
      "default": true,
      "path": "text",
      "condition": "text",
      "sectionGroup": "text",
      "siteSpaces": [
        {
          "object": "site-space",
          "id": "text",
          "path": "text",
          "section": "text",
          "space": {
            "object": "space",
            "id": "text",
            "title": "text",
            "emoji": "🎉",
            "visibility": "public",
            "createdAt": "2025-04-03T19:42:46.828Z",
            "updatedAt": "2025-04-03T19:42:46.828Z",
            "deletedAt": "2025-04-03T19:42:46.828Z",
            "editMode": "live",
            "urls": {
              "location": "https://example.com",
              "app": "https://example.com",
              "published": "https://example.com",
              "public": "https://example.com",
              "icon": "https://example.com"
            },
            "organization": "text",
            "parent": "text",
            "gitSync": {
              "repoName": "text",
              "installationProvider": "github",
              "integration": "text",
              "url": "text",
              "updatedAt": "2025-04-03T19:42:46.828Z"
            },
            "visitorAuth": {
              "backend": "custom"
            },
            "revision": "text",
            "defaultLevel": "admin",
            "comments": 1,
            "changeRequests": 1,
            "changeRequestsOpen": 1,
            "changeRequestsDraft": 1,
            "permissions": {
              "access": true,
              "admin": true,
              "edit": true,
              "comment": true,
              "merge": true,
              "review": true
            }
          },
          "title": "text",
          "default": true,
          "condition": "text",
          "hasAdvancedCustomizationFeature": true,
          "urls": {
            "published": "https://example.com"
          }
        }
      ],
      "urls": {
        "published": "https://example.com"
      },
      "icon": "gear"
    }
  ]
}

OK

Get the publishing authentication settings for a site.

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/publishing/auth' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "backend": "custom",
  "object": "publishing-auth",
  "privateKey": "text",
  "fallbackURL": "https://example.com",
  "integration": "text"
}

OK

Update the publishing authentication settings for a site.

patch
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Body
all ofoptional

Responses
curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/publishing/auth' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "backend": "custom",
    "fallbackURL": "https://example.com"
  }'
{
  "backend": "custom",
  "object": "publishing-auth",
  "privateKey": "text",
  "fallbackURL": "https://example.com",
  "integration": "text"
}

OK

Regenerate the publishing authentication settings for a site. This will re-generate the private key.

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/publishing/auth/regenerate' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "backend": "custom",
  "object": "publishing-auth",
  "privateKey": "text",
  "fallbackURL": "https://example.com",
  "integration": "text"
}

OK

Get a URL to preview the published content of a site. The URL will be valid for 1 hour.

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters
siteSpacestringoptional

ID of the site-space to preview. If not provided, the default site-space will be used.

claimsstringoptional

Rison encoded string of attributes/assertions about the visitor for which we want to preview the site.

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/publishing/preview' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "url": "https://example.com"
}

OK

Get the customization configuration for a site.

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters
unmaskedboolean · default: falseoptionalDeprecated

(Deprecated) Use the getRawCustomizationSettingsById internal endpoint.

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/customization' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "title": "text",
  "styling": {
    "theme": "clean",
    "primaryColor": {
      "light": "text",
      "dark": "text"
    },
    "tint": {
      "color": {
        "light": "text",
        "dark": "text"
      }
    },
    "infoColor": {
      "light": "text",
      "dark": "text"
    },
    "successColor": {
      "light": "text",
      "dark": "text"
    },
    "warningColor": {
      "light": "text",
      "dark": "text"
    },
    "dangerColor": {
      "light": "text",
      "dark": "text"
    },
    "corners": "straight",
    "links": "default",
    "font": "ABCFavorit",
    "background": "plain",
    "icons": "regular",
    "sidebar": {
      "background": "default",
      "list": "default"
    },
    "search": "prominent"
  },
  "internationalization": {
    "locale": "en"
  },
  "favicon": {
    "icon": {
      "light": "https://example.com",
      "dark": "https://example.com"
    }
  },
  "header": {
    "preset": "default",
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "backgroundColor": {
      "light": "text",
      "dark": "text"
    },
    "linkColor": {
      "light": "text",
      "dark": "text"
    },
    "links": [
      {
        "title": "text",
        "style": "link",
        "to": {
          "kind": "file",
          "file": "text"
        },
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ]
  },
  "footer": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "groups": [
      {
        "title": "text",
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ],
    "copyright": "text"
  },
  "announcement": {
    "enabled": true,
    "message": "text",
    "link": {
      "title": "text",
      "to": {
        "kind": "file",
        "file": "text"
      }
    },
    "style": "info"
  },
  "themes": {
    "default": "light",
    "toggeable": true
  },
  "pdf": {
    "enabled": true
  },
  "feedback": {
    "enabled": true
  },
  "aiSearch": {
    "enabled": true
  },
  "ai": {
    "pageLinkSummaries": {
      "enabled": true
    }
  },
  "advancedCustomization": {
    "enabled": true
  },
  "git": {
    "showEditLink": true
  },
  "pagination": {
    "enabled": true
  },
  "trademark": {
    "enabled": true
  },
  "privacyPolicy": {
    "url": "https://example.com"
  },
  "socialPreview": {
    "url": "https://example.com"
  },
  "insights": {
    "trackingCookie": true
  }
}

OK

Update the customization configuration for a site.

put
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Body
titlestring · min: 2 · max: 128optional

Title to use for the published site. If not defined, it'll fallback to the default content title.

stylingobjectrequired

internationalizationobjectrequired

faviconone ofrequired

headerobjectrequired

footerobjectrequired

announcementobjectoptional

themesobjectrequired

Customization options for the dark/light theme modes.

pdfobjectrequired

feedbackobjectrequired

aiSearchobjectrequired

aiobjectoptional

advancedCustomizationobjectrequired

gitobjectrequired

paginationobjectrequired

trademarkobjectrequired

privacyPolicyobjectrequired

socialPreviewobjectrequired

insightsobjectrequired

Responses
curl -L \
  --request PUT \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/customization' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "text",
    "styling": {
      "theme": "clean",
      "primaryColor": {
        "light": "text",
        "dark": "text"
      },
      "tint": {
        "color": {
          "light": "text",
          "dark": "text"
        }
      },
      "infoColor": {
        "light": "text",
        "dark": "text"
      },
      "successColor": {
        "light": "text",
        "dark": "text"
      },
      "warningColor": {
        "light": "text",
        "dark": "text"
      },
      "dangerColor": {
        "light": "text",
        "dark": "text"
      },
      "corners": "straight",
      "links": "default",
      "font": "ABCFavorit",
      "background": "plain",
      "icons": "regular",
      "sidebar": {
        "background": "default",
        "list": "default"
      },
      "search": "prominent"
    },
    "internationalization": {
      "locale": "en"
    },
    "favicon": {
      "icon": {
        "light": "https://example.com",
        "dark": "https://example.com"
      }
    },
    "header": {
      "preset": "default",
      "logo": {
        "light": "https://example.com",
        "dark": "https://example.com"
      },
      "backgroundColor": {
        "light": "text",
        "dark": "text"
      },
      "linkColor": {
        "light": "text",
        "dark": "text"
      },
      "links": [
        {
          "title": "text",
          "style": "link",
          "to": {
            "kind": "file",
            "file": "text"
          },
          "links": [
            {
              "title": "text",
              "to": {
                "kind": "file",
                "file": "text"
              }
            }
          ]
        }
      ]
    },
    "footer": {
      "logo": {
        "light": "https://example.com",
        "dark": "https://example.com"
      },
      "groups": [
        {
          "title": "text",
          "links": [
            {
              "title": "text",
              "to": {
                "kind": "file",
                "file": "text"
              }
            }
          ]
        }
      ],
      "copyright": "text"
    },
    "announcement": {
      "enabled": true,
      "message": "text",
      "link": {
        "title": "text",
        "to": {
          "kind": "file",
          "file": "text"
        }
      },
      "style": "info"
    },
    "themes": {
      "default": "light",
      "toggeable": true
    },
    "pdf": {
      "enabled": true
    },
    "feedback": {
      "enabled": true
    },
    "aiSearch": {
      "enabled": true
    },
    "ai": {
      "pageLinkSummaries": {
        "enabled": true
      }
    },
    "advancedCustomization": {
      "enabled": true
    },
    "git": {
      "showEditLink": true
    },
    "pagination": {
      "enabled": true
    },
    "trademark": {
      "enabled": true
    },
    "privacyPolicy": {
      "url": "https://example.com"
    },
    "socialPreview": {
      "url": "https://example.com"
    },
    "insights": {
      "trackingCookie": true
    }
  }'
{
  "title": "text",
  "styling": {
    "theme": "clean",
    "primaryColor": {
      "light": "text",
      "dark": "text"
    },
    "tint": {
      "color": {
        "light": "text",
        "dark": "text"
      }
    },
    "infoColor": {
      "light": "text",
      "dark": "text"
    },
    "successColor": {
      "light": "text",
      "dark": "text"
    },
    "warningColor": {
      "light": "text",
      "dark": "text"
    },
    "dangerColor": {
      "light": "text",
      "dark": "text"
    },
    "corners": "straight",
    "links": "default",
    "font": "ABCFavorit",
    "background": "plain",
    "icons": "regular",
    "sidebar": {
      "background": "default",
      "list": "default"
    },
    "search": "prominent"
  },
  "internationalization": {
    "locale": "en"
  },
  "favicon": {
    "icon": {
      "light": "https://example.com",
      "dark": "https://example.com"
    }
  },
  "header": {
    "preset": "default",
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "backgroundColor": {
      "light": "text",
      "dark": "text"
    },
    "linkColor": {
      "light": "text",
      "dark": "text"
    },
    "links": [
      {
        "title": "text",
        "style": "link",
        "to": {
          "kind": "file",
          "file": "text"
        },
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ]
  },
  "footer": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "groups": [
      {
        "title": "text",
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ],
    "copyright": "text"
  },
  "announcement": {
    "enabled": true,
    "message": "text",
    "link": {
      "title": "text",
      "to": {
        "kind": "file",
        "file": "text"
      }
    },
    "style": "info"
  },
  "themes": {
    "default": "light",
    "toggeable": true
  },
  "pdf": {
    "enabled": true
  },
  "feedback": {
    "enabled": true
  },
  "aiSearch": {
    "enabled": true
  },
  "ai": {
    "pageLinkSummaries": {
      "enabled": true
    }
  },
  "advancedCustomization": {
    "enabled": true
  },
  "git": {
    "showEditLink": true
  },
  "pagination": {
    "enabled": true
  },
  "trademark": {
    "enabled": true
  },
  "privacyPolicy": {
    "url": "https://example.com"
  },
  "socialPreview": {
    "url": "https://example.com"
  },
  "insights": {
    "trackingCookie": true
  }
}

OK

List all the site spaces under a site in an organization

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters
shareKeystringoptional

For sites published via share-links, the share key is useful to resolve published URLs.

pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

defaultbooleanoptional

If true, only the default site space will be returned. If false, only the non-default site spaces are returned. If undefined, all site spaces are returned.

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/site-spaces' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "site-space",
      "id": "text",
      "path": "text",
      "section": "text",
      "space": {
        "object": "space",
        "id": "text",
        "title": "text",
        "emoji": "🎉",
        "visibility": "public",
        "createdAt": "2025-04-03T19:42:46.828Z",
        "updatedAt": "2025-04-03T19:42:46.828Z",
        "deletedAt": "2025-04-03T19:42:46.828Z",
        "editMode": "live",
        "urls": {
          "location": "https://example.com",
          "app": "https://example.com",
          "published": "https://example.com",
          "public": "https://example.com",
          "icon": "https://example.com"
        },
        "organization": "text",
        "parent": "text",
        "gitSync": {
          "repoName": "text",
          "installationProvider": "github",
          "integration": "text",
          "url": "text",
          "updatedAt": "2025-04-03T19:42:46.828Z"
        },
        "visitorAuth": {
          "backend": "custom"
        },
        "revision": "text",
        "defaultLevel": "admin",
        "comments": 1,
        "changeRequests": 1,
        "changeRequestsOpen": 1,
        "changeRequestsDraft": 1,
        "permissions": {
          "access": true,
          "admin": true,
          "edit": true,
          "comment": true,
          "merge": true,
          "review": true
        }
      },
      "title": "text",
      "default": true,
      "condition": "text",
      "hasAdvancedCustomizationFeature": true,
      "urls": {
        "published": "https://example.com"
      }
    }
  ]
}

OK

Add a space to a site in an organization

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Body
spaceIdstringrequired

ID of the space

sectionIdstringoptional

ID of the section to add the space to. If not provided, the space will be added to the default section or at the root level if the site has no sections.

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/site-spaces' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "spaceId": "text",
    "sectionId": "text"
  }'
{
  "object": "site-space",
  "id": "text",
  "path": "text",
  "section": "text",
  "space": {
    "object": "space",
    "id": "text",
    "title": "text",
    "emoji": "🎉",
    "visibility": "public",
    "createdAt": "2025-04-03T19:42:46.828Z",
    "updatedAt": "2025-04-03T19:42:46.828Z",
    "deletedAt": "2025-04-03T19:42:46.828Z",
    "editMode": "live",
    "urls": {
      "location": "https://example.com",
      "app": "https://example.com",
      "published": "https://example.com",
      "public": "https://example.com",
      "icon": "https://example.com"
    },
    "organization": "text",
    "parent": "text",
    "gitSync": {
      "repoName": "text",
      "installationProvider": "github",
      "integration": "text",
      "url": "text",
      "updatedAt": "2025-04-03T19:42:46.828Z"
    },
    "visitorAuth": {
      "backend": "custom"
    },
    "revision": "text",
    "defaultLevel": "admin",
    "comments": 1,
    "changeRequests": 1,
    "changeRequestsOpen": 1,
    "changeRequestsDraft": 1,
    "permissions": {
      "access": true,
      "admin": true,
      "edit": true,
      "comment": true,
      "merge": true,
      "review": true
    }
  },
  "title": "text",
  "default": true,
  "condition": "text",
  "hasAdvancedCustomizationFeature": true,
  "urls": {
    "published": "https://example.com"
  }
}

Space added to the site

List all the section groups under a site in an organization

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters
pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/section-groups' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "site-section-group",
      "id": "text",
      "title": "text",
      "sections": [
        {
          "object": "site-section",
          "id": "text",
          "title": "text",
          "description": "text",
          "default": true,
          "path": "text",
          "condition": "text",
          "sectionGroup": "text",
          "siteSpaces": [
            {
              "object": "site-space",
              "id": "text",
              "path": "text",
              "section": "text",
              "space": {
                "object": "space",
                "id": "text",
                "title": "text",
                "emoji": "🎉",
                "visibility": "public",
                "createdAt": "2025-04-03T19:42:46.828Z",
                "updatedAt": "2025-04-03T19:42:46.828Z",
                "deletedAt": "2025-04-03T19:42:46.828Z",
                "editMode": "live",
                "urls": {
                  "location": "https://example.com",
                  "app": "https://example.com",
                  "published": "https://example.com",
                  "public": "https://example.com",
                  "icon": "https://example.com"
                },
                "organization": "text",
                "parent": "text",
                "gitSync": {
                  "repoName": "text",
                  "installationProvider": "github",
                  "integration": "text",
                  "url": "text",
                  "updatedAt": "2025-04-03T19:42:46.828Z"
                },
                "visitorAuth": {
                  "backend": "custom"
                },
                "revision": "text",
                "defaultLevel": "admin",
                "comments": 1,
                "changeRequests": 1,
                "changeRequestsOpen": 1,
                "changeRequestsDraft": 1,
                "permissions": {
                  "access": true,
                  "admin": true,
                  "edit": true,
                  "comment": true,
                  "merge": true,
                  "review": true
                }
              },
              "title": "text",
              "default": true,
              "condition": "text",
              "hasAdvancedCustomizationFeature": true,
              "urls": {
                "published": "https://example.com"
              }
            }
          ],
          "urls": {
            "published": "https://example.com"
          },
          "icon": "gear"
        }
      ],
      "icon": "gear"
    }
  ]
}

OK

Add a section group to a site in an organization

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Body
titlestring · min: 1 · max: 100required

Title of the site section group

iconone ofoptional

Name of the icon

sectionsstring[]optional

IDs of the sections to be added to the section group

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/section-groups' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "text",
    "icon": "gear",
    "sections": [
      "text"
    ]
  }'
{
  "object": "site-section-group",
  "id": "text",
  "title": "text",
  "sections": [
    {
      "object": "site-section",
      "id": "text",
      "title": "text",
      "description": "text",
      "default": true,
      "path": "text",
      "condition": "text",
      "sectionGroup": "text",
      "siteSpaces": [
        {
          "object": "site-space",
          "id": "text",
          "path": "text",
          "section": "text",
          "space": {
            "object": "space",
            "id": "text",
            "title": "text",
            "emoji": "🎉",
            "visibility": "public",
            "createdAt": "2025-04-03T19:42:46.828Z",
            "updatedAt": "2025-04-03T19:42:46.828Z",
            "deletedAt": "2025-04-03T19:42:46.828Z",
            "editMode": "live",
            "urls": {
              "location": "https://example.com",
              "app": "https://example.com",
              "published": "https://example.com",
              "public": "https://example.com",
              "icon": "https://example.com"
            },
            "organization": "text",
            "parent": "text",
            "gitSync": {
              "repoName": "text",
              "installationProvider": "github",
              "integration": "text",
              "url": "text",
              "updatedAt": "2025-04-03T19:42:46.828Z"
            },
            "visitorAuth": {
              "backend": "custom"
            },
            "revision": "text",
            "defaultLevel": "admin",
            "comments": 1,
            "changeRequests": 1,
            "changeRequestsOpen": 1,
            "changeRequestsDraft": 1,
            "permissions": {
              "access": true,
              "admin": true,
              "edit": true,
              "comment": true,
              "merge": true,
              "review": true
            }
          },
          "title": "text",
          "default": true,
          "condition": "text",
          "hasAdvancedCustomizationFeature": true,
          "urls": {
            "published": "https://example.com"
          }
        }
      ],
      "urls": {
        "published": "https://example.com"
      },
      "icon": "gear"
    }
  ],
  "icon": "gear"
}

Section group added to the site

Delete a section group on a site in an organization

delete
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

siteSectionGroupIdstringrequired

The unique id of the site group

Responses
curl -L \
  --request DELETE \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/section-groups/{siteSectionGroupId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No body

Site section group has been deleted

Update a section group on a site in an organization

patch
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

siteSectionGroupIdstringrequired

The unique id of the site group

Body
titlestring · min: 1 · max: 100optional

Title of the site section group

iconone ofoptional

Name of the icon

Responses
curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/section-groups/{siteSectionGroupId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "text",
    "icon": "gear"
  }'
{
  "object": "site-section-group",
  "id": "text",
  "title": "text",
  "sections": [
    {
      "object": "site-section",
      "id": "text",
      "title": "text",
      "description": "text",
      "default": true,
      "path": "text",
      "condition": "text",
      "sectionGroup": "text",
      "siteSpaces": [
        {
          "object": "site-space",
          "id": "text",
          "path": "text",
          "section": "text",
          "space": {
            "object": "space",
            "id": "text",
            "title": "text",
            "emoji": "🎉",
            "visibility": "public",
            "createdAt": "2025-04-03T19:42:46.828Z",
            "updatedAt": "2025-04-03T19:42:46.828Z",
            "deletedAt": "2025-04-03T19:42:46.828Z",
            "editMode": "live",
            "urls": {
              "location": "https://example.com",
              "app": "https://example.com",
              "published": "https://example.com",
              "public": "https://example.com",
              "icon": "https://example.com"
            },
            "organization": "text",
            "parent": "text",
            "gitSync": {
              "repoName": "text",
              "installationProvider": "github",
              "integration": "text",
              "url": "text",
              "updatedAt": "2025-04-03T19:42:46.828Z"
            },
            "visitorAuth": {
              "backend": "custom"
            },
            "revision": "text",
            "defaultLevel": "admin",
            "comments": 1,
            "changeRequests": 1,
            "changeRequestsOpen": 1,
            "changeRequestsDraft": 1,
            "permissions": {
              "access": true,
              "admin": true,
              "edit": true,
              "comment": true,
              "merge": true,
              "review": true
            }
          },
          "title": "text",
          "default": true,
          "condition": "text",
          "hasAdvancedCustomizationFeature": true,
          "urls": {
            "published": "https://example.com"
          }
        }
      ],
      "urls": {
        "published": "https://example.com"
      },
      "icon": "gear"
    }
  ],
  "icon": "gear"
}

OK

Add a section to a section group

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

siteSectionGroupIdstringrequired

The unique id of the site group

Body
sectionIdstringrequired

ID of the section to add to the section group

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/section-groups/{siteSectionGroupId}/sections' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "sectionId": "text"
  }'
{
  "object": "site-section-group",
  "id": "text",
  "title": "text",
  "sections": [
    {
      "object": "site-section",
      "id": "text",
      "title": "text",
      "description": "text",
      "default": true,
      "path": "text",
      "condition": "text",
      "sectionGroup": "text",
      "siteSpaces": [
        {
          "object": "site-space",
          "id": "text",
          "path": "text",
          "section": "text",
          "space": {
            "object": "space",
            "id": "text",
            "title": "text",
            "emoji": "🎉",
            "visibility": "public",
            "createdAt": "2025-04-03T19:42:46.828Z",
            "updatedAt": "2025-04-03T19:42:46.828Z",
            "deletedAt": "2025-04-03T19:42:46.828Z",
            "editMode": "live",
            "urls": {
              "location": "https://example.com",
              "app": "https://example.com",
              "published": "https://example.com",
              "public": "https://example.com",
              "icon": "https://example.com"
            },
            "organization": "text",
            "parent": "text",
            "gitSync": {
              "repoName": "text",
              "installationProvider": "github",
              "integration": "text",
              "url": "text",
              "updatedAt": "2025-04-03T19:42:46.828Z"
            },
            "visitorAuth": {
              "backend": "custom"
            },
            "revision": "text",
            "defaultLevel": "admin",
            "comments": 1,
            "changeRequests": 1,
            "changeRequestsOpen": 1,
            "changeRequestsDraft": 1,
            "permissions": {
              "access": true,
              "admin": true,
              "edit": true,
              "comment": true,
              "merge": true,
              "review": true
            }
          },
          "title": "text",
          "default": true,
          "condition": "text",
          "hasAdvancedCustomizationFeature": true,
          "urls": {
            "published": "https://example.com"
          }
        }
      ],
      "urls": {
        "published": "https://example.com"
      },
      "icon": "gear"
    }
  ],
  "icon": "gear"
}

Section added to the section group

Remove a section from a section group

delete
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

siteSectionGroupIdstringrequired

The unique id of the site group

siteSectionIdstringrequired

The unique id of the section within a site

Responses
curl -L \
  --request DELETE \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/section-groups/{siteSectionGroupId}/sections/{siteSectionId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No body

Section has been removed from the section group

List all the site sections under a site in an organization

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters
shareKeystringoptional

For sites published via share-links, the share key is useful to resolve published URLs.

pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/sections' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "site-section",
      "id": "text",
      "title": "text",
      "description": "text",
      "default": true,
      "path": "text",
      "condition": "text",
      "sectionGroup": "text",
      "siteSpaces": [
        {
          "object": "site-space",
          "id": "text",
          "path": "text",
          "section": "text",
          "space": {
            "object": "space",
            "id": "text",
            "title": "text",
            "emoji": "🎉",
            "visibility": "public",
            "createdAt": "2025-04-03T19:42:46.828Z",
            "updatedAt": "2025-04-03T19:42:46.828Z",
            "deletedAt": "2025-04-03T19:42:46.828Z",
            "editMode": "live",
            "urls": {
              "location": "https://example.com",
              "app": "https://example.com",
              "published": "https://example.com",
              "public": "https://example.com",
              "icon": "https://example.com"
            },
            "organization": "text",
            "parent": "text",
            "gitSync": {
              "repoName": "text",
              "installationProvider": "github",
              "integration": "text",
              "url": "text",
              "updatedAt": "2025-04-03T19:42:46.828Z"
            },
            "visitorAuth": {
              "backend": "custom"
            },
            "revision": "text",
            "defaultLevel": "admin",
            "comments": 1,
            "changeRequests": 1,
            "changeRequestsOpen": 1,
            "changeRequestsDraft": 1,
            "permissions": {
              "access": true,
              "admin": true,
              "edit": true,
              "comment": true,
              "merge": true,
              "review": true
            }
          },
          "title": "text",
          "default": true,
          "condition": "text",
          "hasAdvancedCustomizationFeature": true,
          "urls": {
            "published": "https://example.com"
          }
        }
      ],
      "urls": {
        "published": "https://example.com"
      },
      "icon": "gear"
    }
  ]
}

OK

Add a section to a site in an organization

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Body
spaceIdstringrequired

ID of the space to be added to the section as a site space variant

titlestring · max: 64optional

Title of the section

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/sections' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "spaceId": "text",
    "title": "text"
  }'
{
  "object": "site-section",
  "id": "text",
  "title": "text",
  "description": "text",
  "default": true,
  "path": "text",
  "condition": "text",
  "sectionGroup": "text",
  "siteSpaces": [
    {
      "object": "site-space",
      "id": "text",
      "path": "text",
      "section": "text",
      "space": {
        "object": "space",
        "id": "text",
        "title": "text",
        "emoji": "🎉",
        "visibility": "public",
        "createdAt": "2025-04-03T19:42:46.828Z",
        "updatedAt": "2025-04-03T19:42:46.828Z",
        "deletedAt": "2025-04-03T19:42:46.828Z",
        "editMode": "live",
        "urls": {
          "location": "https://example.com",
          "app": "https://example.com",
          "published": "https://example.com",
          "public": "https://example.com",
          "icon": "https://example.com"
        },
        "organization": "text",
        "parent": "text",
        "gitSync": {
          "repoName": "text",
          "installationProvider": "github",
          "integration": "text",
          "url": "text",
          "updatedAt": "2025-04-03T19:42:46.828Z"
        },
        "visitorAuth": {
          "backend": "custom"
        },
        "revision": "text",
        "defaultLevel": "admin",
        "comments": 1,
        "changeRequests": 1,
        "changeRequestsOpen": 1,
        "changeRequestsDraft": 1,
        "permissions": {
          "access": true,
          "admin": true,
          "edit": true,
          "comment": true,
          "merge": true,
          "review": true
        }
      },
      "title": "text",
      "default": true,
      "condition": "text",
      "hasAdvancedCustomizationFeature": true,
      "urls": {
        "published": "https://example.com"
      }
    }
  ],
  "urls": {
    "published": "https://example.com"
  },
  "icon": "gear"
}

Section added to the site

Delete a section on a site in an organization

delete
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

siteSectionIdstringrequired

The unique id of the section within a site

Responses
curl -L \
  --request DELETE \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/sections/{siteSectionId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No body

Site section has been deleted

Update a section on a site in an organization

patch
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

siteSectionIdstringrequired

The unique id of the section within a site

Body
titlestring · min: 2 · max: 128optional

Title of the site section

pathstring · min: 1 · max: 100optional

Path to the section on the site

defaultSiteSpacestringoptional

ID of the site-space to be used as the default in this section.

conditionone ofoptional

Conditional expression used to evaluate whether the site section should be shown to the site's visitor (should evaluate to a boolean). If not set, the condition will remain unchanged. If set to null, the condition will be removed.

iconone ofoptional

Name of the icon

descriptionone ofoptional

Description of the site section

Responses
curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/sections/{siteSectionId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "text",
    "path": "text",
    "defaultSiteSpace": "text",
    "condition": "text",
    "icon": "gear",
    "description": "text"
  }'
{
  "object": "site-section",
  "id": "text",
  "title": "text",
  "description": "text",
  "default": true,
  "path": "text",
  "condition": "text",
  "sectionGroup": "text",
  "siteSpaces": [
    {
      "object": "site-space",
      "id": "text",
      "path": "text",
      "section": "text",
      "space": {
        "object": "space",
        "id": "text",
        "title": "text",
        "emoji": "🎉",
        "visibility": "public",
        "createdAt": "2025-04-03T19:42:46.828Z",
        "updatedAt": "2025-04-03T19:42:46.828Z",
        "deletedAt": "2025-04-03T19:42:46.828Z",
        "editMode": "live",
        "urls": {
          "location": "https://example.com",
          "app": "https://example.com",
          "published": "https://example.com",
          "public": "https://example.com",
          "icon": "https://example.com"
        },
        "organization": "text",
        "parent": "text",
        "gitSync": {
          "repoName": "text",
          "installationProvider": "github",
          "integration": "text",
          "url": "text",
          "updatedAt": "2025-04-03T19:42:46.828Z"
        },
        "visitorAuth": {
          "backend": "custom"
        },
        "revision": "text",
        "defaultLevel": "admin",
        "comments": 1,
        "changeRequests": 1,
        "changeRequestsOpen": 1,
        "changeRequestsDraft": 1,
        "permissions": {
          "access": true,
          "admin": true,
          "edit": true,
          "comment": true,
          "merge": true,
          "review": true
        }
      },
      "title": "text",
      "default": true,
      "condition": "text",
      "hasAdvancedCustomizationFeature": true,
      "urls": {
        "published": "https://example.com"
      }
    }
  ],
  "urls": {
    "published": "https://example.com"
  },
  "icon": "gear"
}

OK

Search content in a site

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters
pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

Body
all ofoptional

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/search' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "text",
    "scope": {
      "mode": "default",
      "includedSiteSpaces": [
        "text"
      ]
    }
  }'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "id": "text",
      "title": "text",
      "pages": [
        {
          "id": "text",
          "title": "text",
          "path": "text",
          "sections": [
            {
              "id": "text",
              "title": "text",
              "path": "text",
              "body": "text",
              "urls": {
                "app": "https://example.com"
              }
            }
          ],
          "urls": {
            "app": "https://example.com"
          }
        }
      ]
    }
  ]
}

OK

Delete a space on a site in an organization

delete
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

siteSpaceIdstringrequired

The unique id of the site-space relationship

Responses
curl -L \
  --request DELETE \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No body

Site space has been deleted

Update a space on a site in an organization

patch
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

siteSpaceIdstringrequired

The unique id of the site-space relationship

Body
pathstring · min: 1 · max: 100optional

Path to the space on the site

conditionone ofoptional

Conditional expression used to evaluate whether the site space should be shown to the site's visitor (should evaluate to a boolean). If not set, the condition will remain unchanged. If set to null, the condition will be removed.

Responses
curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "path": "text",
    "condition": "text"
  }'
{
  "object": "site-space",
  "id": "text",
  "path": "text",
  "section": "text",
  "space": {
    "object": "space",
    "id": "text",
    "title": "text",
    "emoji": "🎉",
    "visibility": "public",
    "createdAt": "2025-04-03T19:42:46.828Z",
    "updatedAt": "2025-04-03T19:42:46.828Z",
    "deletedAt": "2025-04-03T19:42:46.828Z",
    "editMode": "live",
    "urls": {
      "location": "https://example.com",
      "app": "https://example.com",
      "published": "https://example.com",
      "public": "https://example.com",
      "icon": "https://example.com"
    },
    "organization": "text",
    "parent": "text",
    "gitSync": {
      "repoName": "text",
      "installationProvider": "github",
      "integration": "text",
      "url": "text",
      "updatedAt": "2025-04-03T19:42:46.828Z"
    },
    "visitorAuth": {
      "backend": "custom"
    },
    "revision": "text",
    "defaultLevel": "admin",
    "comments": 1,
    "changeRequests": 1,
    "changeRequestsOpen": 1,
    "changeRequestsDraft": 1,
    "permissions": {
      "access": true,
      "admin": true,
      "edit": true,
      "comment": true,
      "merge": true,
      "review": true
    }
  },
  "title": "text",
  "default": true,
  "condition": "text",
  "hasAdvancedCustomizationFeature": true,
  "urls": {
    "published": "https://example.com"
  }
}

OK

Get the customization configuration for a site space.

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

siteSpaceIdstringrequired

The unique id of the site-space relationship

Query parameters
unmaskedboolean · default: falseoptionalDeprecated

(Deprecated) Use the getRawCustomizationSettingsById internal endpoint.

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/customization' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "title": "text",
  "styling": {
    "theme": "clean",
    "primaryColor": {
      "light": "text",
      "dark": "text"
    },
    "tint": {
      "color": {
        "light": "text",
        "dark": "text"
      }
    },
    "infoColor": {
      "light": "text",
      "dark": "text"
    },
    "successColor": {
      "light": "text",
      "dark": "text"
    },
    "warningColor": {
      "light": "text",
      "dark": "text"
    },
    "dangerColor": {
      "light": "text",
      "dark": "text"
    },
    "corners": "straight",
    "links": "default",
    "font": "ABCFavorit",
    "background": "plain",
    "icons": "regular",
    "sidebar": {
      "background": "default",
      "list": "default"
    },
    "search": "prominent"
  },
  "internationalization": {
    "locale": "en"
  },
  "favicon": {
    "icon": {
      "light": "https://example.com",
      "dark": "https://example.com"
    }
  },
  "header": {
    "preset": "default",
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "backgroundColor": {
      "light": "text",
      "dark": "text"
    },
    "linkColor": {
      "light": "text",
      "dark": "text"
    },
    "links": [
      {
        "title": "text",
        "style": "link",
        "to": {
          "kind": "file",
          "file": "text"
        },
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ]
  },
  "footer": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "groups": [
      {
        "title": "text",
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ],
    "copyright": "text"
  },
  "announcement": {
    "enabled": true,
    "message": "text",
    "link": {
      "title": "text",
      "to": {
        "kind": "file",
        "file": "text"
      }
    },
    "style": "info"
  },
  "themes": {
    "default": "light",
    "toggeable": true
  },
  "pdf": {
    "enabled": true
  },
  "feedback": {
    "enabled": true
  },
  "aiSearch": {
    "enabled": true
  },
  "ai": {
    "pageLinkSummaries": {
      "enabled": true
    }
  },
  "advancedCustomization": {
    "enabled": true
  },
  "git": {
    "showEditLink": true
  },
  "pagination": {
    "enabled": true
  },
  "trademark": {
    "enabled": true
  },
  "privacyPolicy": {
    "url": "https://example.com"
  },
  "socialPreview": {
    "url": "https://example.com"
  },
  "insights": {
    "trackingCookie": true
  }
}

OK

Removes the customization configuration for a site space.

delete
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

siteSpaceIdstringrequired

The unique id of the site-space relationship

Responses
curl -L \
  --request DELETE \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/customization' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No body

Site space customization removed

Override the customization configuration for a site space.

patch
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

siteSpaceIdstringrequired

The unique id of the site-space relationship

Body
titleone ofoptional

Title to use for the published site variant. If not defined, the title will not be changed. If set to null, the title will be unset and will fallback to the content title.

Title of the site

stylingobjectoptional

internationalizationobjectoptional

faviconone ofoptional

The favicon to use. Set to null to reset the override.

announcementobjectoptional

headerobjectoptional

footerobjectoptional

themesobjectoptional

pdfobjectoptional

feedbackobjectoptional

aiSearchobjectoptional

gitobjectoptional

paginationobjectoptional

trademarkobjectoptional

privacyPolicyobjectoptional

socialPreviewobjectoptional

Responses
curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/customization' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "text",
    "styling": {
      "theme": "clean",
      "primaryColor": {
        "light": "text",
        "dark": "text"
      },
      "infoColor": {
        "light": "text",
        "dark": "text"
      },
      "successColor": {
        "light": "text",
        "dark": "text"
      },
      "warningColor": {
        "light": "text",
        "dark": "text"
      },
      "dangerColor": {
        "light": "text",
        "dark": "text"
      },
      "tint": {
        "color": {
          "light": "text",
          "dark": "text"
        }
      },
      "corners": "straight",
      "links": "default",
      "font": "ABCFavorit",
      "icons": "regular",
      "sidebar": {
        "background": "default",
        "list": "default"
      },
      "search": "prominent",
      "background": "plain"
    },
    "internationalization": {
      "locale": "en"
    },
    "favicon": {
      "icon": {
        "light": "https://example.com",
        "dark": "https://example.com"
      }
    },
    "announcement": {
      "enabled": true,
      "message": "text",
      "link": {
        "title": "text",
        "to": {
          "kind": "file",
          "file": "text"
        }
      },
      "style": "info"
    },
    "header": {
      "preset": "default",
      "logo": {
        "light": "https://example.com",
        "dark": "https://example.com"
      },
      "backgroundColor": {
        "light": "text",
        "dark": "text"
      },
      "linkColor": {
        "light": "text",
        "dark": "text"
      },
      "links": [
        {
          "title": "text",
          "style": "link",
          "to": {
            "kind": "file",
            "file": "text"
          },
          "links": [
            {
              "title": "text",
              "to": {
                "kind": "file",
                "file": "text"
              }
            }
          ]
        }
      ]
    },
    "footer": {
      "logo": {
        "light": "https://example.com",
        "dark": "https://example.com"
      },
      "groups": [
        {
          "title": "text",
          "links": [
            {
              "title": "text",
              "to": {
                "kind": "file",
                "file": "text"
              }
            }
          ]
        }
      ],
      "copyright": "text"
    },
    "themes": {
      "default": "light",
      "toggeable": true
    },
    "pdf": {
      "enabled": true
    },
    "feedback": {
      "enabled": true
    },
    "aiSearch": {
      "enabled": true
    },
    "git": {
      "showEditLink": true
    },
    "pagination": {
      "enabled": true
    },
    "trademark": {
      "enabled": true
    },
    "privacyPolicy": {
      "url": "https://example.com"
    },
    "socialPreview": {
      "url": "https://example.com"
    }
  }'
{
  "title": "text",
  "styling": {
    "theme": "clean",
    "primaryColor": {
      "light": "text",
      "dark": "text"
    },
    "tint": {
      "color": {
        "light": "text",
        "dark": "text"
      }
    },
    "infoColor": {
      "light": "text",
      "dark": "text"
    },
    "successColor": {
      "light": "text",
      "dark": "text"
    },
    "warningColor": {
      "light": "text",
      "dark": "text"
    },
    "dangerColor": {
      "light": "text",
      "dark": "text"
    },
    "corners": "straight",
    "links": "default",
    "font": "ABCFavorit",
    "background": "plain",
    "icons": "regular",
    "sidebar": {
      "background": "default",
      "list": "default"
    },
    "search": "prominent"
  },
  "internationalization": {
    "locale": "en"
  },
  "favicon": {
    "icon": {
      "light": "https://example.com",
      "dark": "https://example.com"
    }
  },
  "header": {
    "preset": "default",
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "backgroundColor": {
      "light": "text",
      "dark": "text"
    },
    "linkColor": {
      "light": "text",
      "dark": "text"
    },
    "links": [
      {
        "title": "text",
        "style": "link",
        "to": {
          "kind": "file",
          "file": "text"
        },
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ]
  },
  "footer": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "groups": [
      {
        "title": "text",
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ],
    "copyright": "text"
  },
  "announcement": {
    "enabled": true,
    "message": "text",
    "link": {
      "title": "text",
      "to": {
        "kind": "file",
        "file": "text"
      }
    },
    "style": "info"
  },
  "themes": {
    "default": "light",
    "toggeable": true
  },
  "pdf": {
    "enabled": true
  },
  "feedback": {
    "enabled": true
  },
  "aiSearch": {
    "enabled": true
  },
  "ai": {
    "pageLinkSummaries": {
      "enabled": true
    }
  },
  "advancedCustomization": {
    "enabled": true
  },
  "git": {
    "showEditLink": true
  },
  "pagination": {
    "enabled": true
  },
  "trademark": {
    "enabled": true
  },
  "privacyPolicy": {
    "url": "https://example.com"
  },
  "socialPreview": {
    "url": "https://example.com"
  },
  "insights": {
    "trackingCookie": true
  }
}

OK

Move a site section group to a new position in the site.

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

siteSectionGroupIdstringrequired

The unique id of the site group

Body
positionobjectoptional

The position where to move the site section group. When not provided the site section group is moved at the end of the site.

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/section-groups/{siteSectionGroupId}/move' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "position": {
      "before": {
        "type": "site-section",
        "id": "text"
      },
      "after": {
        "type": "site-section",
        "id": "text"
      }
    }
  }'
{
  "object": "site-section-group",
  "id": "text",
  "title": "text",
  "sections": [
    {
      "object": "site-section",
      "id": "text",
      "title": "text",
      "description": "text",
      "default": true,
      "path": "text",
      "condition": "text",
      "sectionGroup": "text",
      "siteSpaces": [
        {
          "object": "site-space",
          "id": "text",
          "path": "text",
          "section": "text",
          "space": {
            "object": "space",
            "id": "text",
            "title": "text",
            "emoji": "🎉",
            "visibility": "public",
            "createdAt": "2025-04-03T19:42:46.828Z",
            "updatedAt": "2025-04-03T19:42:46.828Z",
            "deletedAt": "2025-04-03T19:42:46.828Z",
            "editMode": "live",
            "urls": {
              "location": "https://example.com",
              "app": "https://example.com",
              "published": "https://example.com",
              "public": "https://example.com",
              "icon": "https://example.com"
            },
            "organization": "text",
            "parent": "text",
            "gitSync": {
              "repoName": "text",
              "installationProvider": "github",
              "integration": "text",
              "url": "text",
              "updatedAt": "2025-04-03T19:42:46.828Z"
            },
            "visitorAuth": {
              "backend": "custom"
            },
            "revision": "text",
            "defaultLevel": "admin",
            "comments": 1,
            "changeRequests": 1,
            "changeRequestsOpen": 1,
            "changeRequestsDraft": 1,
            "permissions": {
              "access": true,
              "admin": true,
              "edit": true,
              "comment": true,
              "merge": true,
              "review": true
            }
          },
          "title": "text",
          "default": true,
          "condition": "text",
          "hasAdvancedCustomizationFeature": true,
          "urls": {
            "published": "https://example.com"
          }
        }
      ],
      "urls": {
        "published": "https://example.com"
      },
      "icon": "gear"
    }
  ],
  "icon": "gear"
}

Site section group moved

Move a site section to a new position in the site.

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

siteSectionIdstringrequired

The unique id of the section within a site

Body
positionobjectoptional

The position where to move the site section. When not provided the site section is moved at the end of the site.

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/sections/{siteSectionId}/move' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "position": {
      "before": {
        "type": "site-section",
        "siteSection": "text"
      },
      "after": {
        "type": "site-section",
        "siteSection": "text"
      }
    }
  }'
{
  "object": "site-section",
  "id": "text",
  "title": "text",
  "description": "text",
  "default": true,
  "path": "text",
  "condition": "text",
  "sectionGroup": "text",
  "siteSpaces": [
    {
      "object": "site-space",
      "id": "text",
      "path": "text",
      "section": "text",
      "space": {
        "object": "space",
        "id": "text",
        "title": "text",
        "emoji": "🎉",
        "visibility": "public",
        "createdAt": "2025-04-03T19:42:46.828Z",
        "updatedAt": "2025-04-03T19:42:46.828Z",
        "deletedAt": "2025-04-03T19:42:46.828Z",
        "editMode": "live",
        "urls": {
          "location": "https://example.com",
          "app": "https://example.com",
          "published": "https://example.com",
          "public": "https://example.com",
          "icon": "https://example.com"
        },
        "organization": "text",
        "parent": "text",
        "gitSync": {
          "repoName": "text",
          "installationProvider": "github",
          "integration": "text",
          "url": "text",
          "updatedAt": "2025-04-03T19:42:46.828Z"
        },
        "visitorAuth": {
          "backend": "custom"
        },
        "revision": "text",
        "defaultLevel": "admin",
        "comments": 1,
        "changeRequests": 1,
        "changeRequestsOpen": 1,
        "changeRequestsDraft": 1,
        "permissions": {
          "access": true,
          "admin": true,
          "edit": true,
          "comment": true,
          "merge": true,
          "review": true
        }
      },
      "title": "text",
      "default": true,
      "condition": "text",
      "hasAdvancedCustomizationFeature": true,
      "urls": {
        "published": "https://example.com"
      }
    }
  ],
  "urls": {
    "published": "https://example.com"
  },
  "icon": "gear"
}

Site section moved

Move a site space to a new position in the site.

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

siteSpaceIdstringrequired

The unique id of the site-space relationship

Body
positionobjectoptional

The position where to move the site space. When not provided the site space is moved at the end of the site.

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/move' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "position": {
      "before": {
        "type": "site-space",
        "siteSpace": "text"
      },
      "after": {
        "type": "site-space",
        "siteSpace": "text"
      }
    }
  }'
{
  "object": "site-space",
  "id": "text",
  "path": "text",
  "section": "text",
  "space": {
    "object": "space",
    "id": "text",
    "title": "text",
    "emoji": "🎉",
    "visibility": "public",
    "createdAt": "2025-04-03T19:42:46.828Z",
    "updatedAt": "2025-04-03T19:42:46.828Z",
    "deletedAt": "2025-04-03T19:42:46.828Z",
    "editMode": "live",
    "urls": {
      "location": "https://example.com",
      "app": "https://example.com",
      "published": "https://example.com",
      "public": "https://example.com",
      "icon": "https://example.com"
    },
    "organization": "text",
    "parent": "text",
    "gitSync": {
      "repoName": "text",
      "installationProvider": "github",
      "integration": "text",
      "url": "text",
      "updatedAt": "2025-04-03T19:42:46.828Z"
    },
    "visitorAuth": {
      "backend": "custom"
    },
    "revision": "text",
    "defaultLevel": "admin",
    "comments": 1,
    "changeRequests": 1,
    "changeRequestsOpen": 1,
    "changeRequestsDraft": 1,
    "permissions": {
      "access": true,
      "admin": true,
      "edit": true,
      "comment": true,
      "merge": true,
      "review": true
    }
  },
  "title": "text",
  "default": true,
  "condition": "text",
  "hasAdvancedCustomizationFeature": true,
  "urls": {
    "published": "https://example.com"
  }
}

Site space moved

Track events in a site.

post

Track events in a site.

Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Body
eventsone of[]required

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/insights/events' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "events": [
      {
        "session": {
          "visitorId": "text",
          "sessionId": "text",
          "cookies": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "ip": "text",
          "userAgent": "text",
          "language": "text",
          "referrer": null,
          "visitorAuthToken": "text",
          "visitorAuthClaims": {
            "ANY_ADDITIONAL_PROPERTY": "[Circular Reference]"
          }
        },
        "location": {
          "url": "https://example.com",
          "siteSection": "text",
          "siteSpace": "text",
          "siteShareKey": "text",
          "space": "text",
          "revision": "text",
          "page": "text"
        },
        "timestamp": "2025-04-03T19:42:46.828Z",
        "type": "page_view"
      }
    ]
  }'
No body

Events have been tracked.

Query and aggregate events in a site.

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Body
selectone of[]optional

whereall of[]optional

groupByone of[]optional

orderobjectoptional

rangestring · enumrequired
Available options:
limitinteger · min: 1 · max: 1000 · default: 1000optional
Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/insights/events/aggregate' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "select": [
      {
        "column": "datetime",
        "interval": "hour"
      }
    ],
    "where": [
      {
        "column": "datetime",
        "values": [
          "2025-04-03T19:42:46.828Z"
        ]
      },
      {
        "operator": "in"
      }
    ],
    "groupBy": [
      {
        "column": "datetime",
        "interval": "hour"
      }
    ],
    "order": {
      "by": {
        "column": "datetime",
        "interval": "hour"
      },
      "direction": "asc"
    },
    "range": "lastYear",
    "limit": 1
  }'
{
  "columns": [
    {
      "column": "datetime",
      "values": [
        "2025-04-03T19:42:46.828Z"
      ]
    }
  ]
}

Aggregated events in the site.

List visitor segments in a site.

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/insights/visitor-segments' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "title": "text",
      "claims": {
        "ANY_ADDITIONAL_PROPERTY": "[Circular Reference]"
      },
      "events": 1,
      "visitors": 1,
      "sessions": 1
    }
  ]
}

List of visitor segments in the site.

Enable, disable, or submit for review Ads on a site.

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Body
statusstring · enumoptional
Available options:
topicstring · enumoptional

Topic of the content

Available options:
Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/ads' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "in-review",
    "topic": "webdev"
  }'
No body

OK

List the redirects configured for a site.

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters
pagestringoptional

Identifier of the page results to fetch.

limitnumber · max: 1000optional

The number of results per page

Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/redirects' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "site-redirect",
      "id": "text",
      "source": "text",
      "destination": {
        "kind": "site-section",
        "siteSectionId": "text"
      }
    }
  ]
}

The list of redirects for the site.

Configure a redirect explicitly for a site.

post
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Body
sourcestring · max: 512required

The source path to redirect from.

Pattern: ^/[a-zA-Z0-9-_.\/]+[a-zA-Z0-9-_.]$
destinationone ofrequired

Responses
curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/redirects' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "source": "text",
    "destination": {
      "kind": "site-section",
      "siteSectionId": "text"
    }
  }'
{
  "object": "site-redirect",
  "id": "text",
  "source": "text",
  "destination": {
    "kind": "site-section",
    "siteSectionId": "text"
  }
}

The redirect was created successfully.

Delete a redirect for a site

delete
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

siteRedirectIdstringrequired

The unique id of the site redirect

Responses
curl -L \
  --request DELETE \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/redirects/{siteRedirectId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No body

Site redirect deleted

Update a redirect for a site

patch
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

siteRedirectIdstringrequired

The unique id of the site redirect

Body
sourcestring · max: 512optional

The source path to redirect from.

Pattern: ^/[a-zA-Z0-9-_.\/]+[a-zA-Z0-9-_.]$
destinationone ofoptional

Responses
curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/redirects/{siteRedirectId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "source": "text",
    "destination": {
      "kind": "site-section",
      "siteSectionId": "text"
    }
  }'
{
  "object": "site-redirect",
  "id": "text",
  "source": "text",
  "destination": {
    "kind": "site-section",
    "siteSectionId": "text"
  }
}

OK

Resolve a redirect in a site by its source path.

get
Authorizations
Path parameters
organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters
shareKeystringoptional

For sites published via share-links, the share key is useful to resolve published URLs.

sourcestring · max: 512required

The source path to redirect from.

Pattern: ^/[a-zA-Z0-9-_.\/]+[a-zA-Z0-9-_.]$
Responses
curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/redirect?source=text' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "redirect": {
    "object": "site-redirect",
    "id": "text",
    "source": "text",
    "destination": {
      "kind": "site-section",
      "siteSectionId": "text"
    }
  },
  "target": "text"
}

The redirect was resolved successfully.

Was this helpful?