Docs sites

Manage your published docs sites.

Remove a section from a section group

delete

/orgs/{organizationId}/sites/{siteId}/section-groups/{siteSectionGroupId}/sections/{siteSectionId}

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

application/json

cURL

JavaScript

Python

HTTP

cURL

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'

205

default

205

No body

Section has been removed from the section group

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

get

/orgs/{organizationId}/sites/{siteId}/published

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters

shareKeystring

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

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

404

default

200

{
  "site": {
    "id": "text",
    "type": "basic",
    "title": "text",
    "hostname": "text",
    "basename": "text",
    "proxy": "text",
    "visibility": "public",
    "published": true,
    "siteSpaces": 1,
    "createdAt": "2025-03-09T02:49:20.214Z",
    "adaptiveContent": {
      "enabled": true
    },
    "ads": {
      "submittable": true,
      "status": "pending"
    },
    "object": "site",
    "features": [
      {
        "plan": "basic",
        "frozen": true,
        "id": "sites-sections"
      }
    ],
    "urls": {
      "location": "https://example.com",
      "app": "https://example.com",
      "published": "https://example.com"
    }
  },
  "structure": {
    "type": "sections",
    "structure": [
      {
        "id": "text",
        "title": "text",
        "description": "text",
        "default": true,
        "path": "text",
        "condition": "text",
        "sectionGroup": "text",
        "icon": "gear",
        "object": "site-section",
        "siteSpaces": [
          {
            "id": "text",
            "path": "text",
            "section": "text",
            "space": {
              "id": "text",
              "title": "text",
              "emoji": "🎉",
              "visibility": "public",
              "createdAt": "2025-03-09T02:49:20.214Z",
              "updatedAt": "2025-03-09T02:49:20.214Z",
              "deletedAt": "2025-03-09T02:49:20.214Z",
              "editMode": "live",
              "organization": "text",
              "parent": "text",
              "gitSync": {
                "installationProvider": "github",
                "integration": "text",
                "url": "text",
                "updatedAt": "2025-03-09T02:49:20.214Z"
              },
              "visitorAuth": {
                "backend": "custom"
              },
              "revision": "text",
              "defaultLevel": "admin",
              "comments": 1,
              "changeRequests": 1,
              "changeRequestsOpen": 1,
              "changeRequestsDraft": 1,
              "object": "space",
              "urls": {
                "location": "https://example.com",
                "app": "https://example.com",
                "published": "https://example.com",
                "public": "https://example.com",
                "icon": "https://example.com"
              },
              "permissions": {
                "access": true,
                "admin": true,
                "edit": true,
                "comment": true,
                "merge": true,
                "review": true
              }
            },
            "title": "text",
            "default": true,
            "condition": "text",
            "hasAdvancedCustomizationFeature": true,
            "object": "site-space",
            "urls": {
              "published": "https://example.com"
            }
          }
        ],
        "urls": {
          "published": "https://example.com"
        }
      }
    ]
  },
  "object": "published-content-site",
  "scripts": [
    {
      "script": "https://example.com",
      "contentSecurityPolicy": "text",
      "cookies": true
    }
  ],
  "customizations": {
    "site": {
      "title": "text",
      "internationalization": {
        "locale": "en"
      },
      "themes": {
        "default": "light",
        "toggeable": true
      },
      "pdf": {
        "enabled": true
      },
      "feedback": {
        "enabled": true
      },
      "aiSearch": {
        "enabled": true
      },
      "advancedCustomization": {
        "enabled": true
      },
      "git": {
        "showEditLink": true
      },
      "pagination": {
        "enabled": true
      },
      "trademark": {
        "enabled": true
      },
      "privacyPolicy": {
        "url": "https://example.com"
      },
      "socialPreview": {
        "url": "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",
            "links": [
              {
                "title": "text",
                "to": {
                  "file": "text",
                  "kind": "file"
                }
              }
            ],
            "to": {
              "file": "text",
              "kind": "file"
            }
          }
        ]
      },
      "footer": {
        "logo": {
          "light": "https://example.com",
          "dark": "https://example.com"
        },
        "copyright": "text",
        "groups": [
          {
            "title": "text",
            "links": [
              {
                "title": "text",
                "to": {
                  "file": "text",
                  "kind": "file"
                }
              }
            ]
          }
        ]
      },
      "favicon": {
        "icon": {
          "light": "https://example.com",
          "dark": "https://example.com"
        }
      },
      "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"
        }
      }
    },
    "siteSpaces": {
      "ANY_ADDITIONAL_PROPERTY": {
        "title": "text",
        "internationalization": {
          "locale": "en"
        },
        "themes": {
          "default": "light",
          "toggeable": true
        },
        "pdf": {
          "enabled": true
        },
        "feedback": {
          "enabled": true
        },
        "aiSearch": {
          "enabled": true
        },
        "advancedCustomization": {
          "enabled": true
        },
        "git": {
          "showEditLink": true
        },
        "pagination": {
          "enabled": true
        },
        "trademark": {
          "enabled": true
        },
        "privacyPolicy": {
          "url": "https://example.com"
        },
        "socialPreview": {
          "url": "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",
              "links": [
                {
                  "title": "text",
                  "to": {
                    "file": "text",
                    "kind": "file"
                  }
                }
              ],
              "to": {
                "file": "text",
                "kind": "file"
              }
            }
          ]
        },
        "footer": {
          "logo": {
            "light": "https://example.com",
            "dark": "https://example.com"
          },
          "copyright": "text",
          "groups": [
            {
              "title": "text",
              "links": [
                {
                  "title": "text",
                  "to": {
                    "file": "text",
                    "kind": "file"
                  }
                }
              ]
            }
          ]
        },
        "favicon": {
          "icon": {
            "light": "https://example.com",
            "dark": "https://example.com"
          }
        },
        "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"
          }
        }
      }
    }
  }
}

OK

Unpublishes the site.

post

/orgs/{organizationId}/sites/{siteId}/unpublish

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

default

200

{
  "id": "text",
  "type": "basic",
  "title": "text",
  "hostname": "text",
  "basename": "text",
  "proxy": "text",
  "visibility": "public",
  "published": true,
  "siteSpaces": 1,
  "createdAt": "2025-03-09T02:49:20.214Z",
  "adaptiveContent": {
    "enabled": true
  },
  "ads": {
    "submittable": true,
    "status": "pending"
  },
  "object": "site",
  "features": [
    {
      "plan": "basic",
      "frozen": true,
      "id": "sites-sections"
    }
  ],
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com"
  }
}

Site unpublished successfully

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

get

/orgs/{organizationId}/sites/{siteId}/structure

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters

shareKeystring

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

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

404

default

200

{
  "type": "sections",
  "structure": [
    {
      "id": "text",
      "title": "text",
      "description": "text",
      "default": true,
      "path": "text",
      "condition": "text",
      "sectionGroup": "text",
      "icon": "gear",
      "object": "site-section",
      "siteSpaces": [
        {
          "id": "text",
          "path": "text",
          "section": "text",
          "space": {
            "id": "text",
            "title": "text",
            "emoji": "🎉",
            "visibility": "public",
            "createdAt": "2025-03-09T02:49:20.214Z",
            "updatedAt": "2025-03-09T02:49:20.214Z",
            "deletedAt": "2025-03-09T02:49:20.214Z",
            "editMode": "live",
            "organization": "text",
            "parent": "text",
            "gitSync": {
              "installationProvider": "github",
              "integration": "text",
              "url": "text",
              "updatedAt": "2025-03-09T02:49:20.214Z"
            },
            "visitorAuth": {
              "backend": "custom"
            },
            "revision": "text",
            "defaultLevel": "admin",
            "comments": 1,
            "changeRequests": 1,
            "changeRequestsOpen": 1,
            "changeRequestsDraft": 1,
            "object": "space",
            "urls": {
              "location": "https://example.com",
              "app": "https://example.com",
              "published": "https://example.com",
              "public": "https://example.com",
              "icon": "https://example.com"
            },
            "permissions": {
              "access": true,
              "admin": true,
              "edit": true,
              "comment": true,
              "merge": true,
              "review": true
            }
          },
          "title": "text",
          "default": true,
          "condition": "text",
          "hasAdvancedCustomizationFeature": true,
          "object": "site-space",
          "urls": {
            "published": "https://example.com"
          }
        }
      ],
      "urls": {
        "published": "https://example.com"
      }
    }
  ]
}

OK

Get the publishing authentication settings for a site.

get

/orgs/{organizationId}/sites/{siteId}/publishing/auth

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

400

default

200

{
  "backend": "custom",
  "privateKey": "text",
  "fallbackURL": "https://example.com",
  "integration": "text",
  "object": "publishing-auth"
}

OK

Update the publishing authentication settings for a site.

patch

/orgs/{organizationId}/sites/{siteId}/publishing/auth

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Body

all of

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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"
  }'

200

400

default

200

{
  "backend": "custom",
  "privateKey": "text",
  "fallbackURL": "https://example.com",
  "integration": "text",
  "object": "publishing-auth"
}

OK

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

post

/orgs/{organizationId}/sites/{siteId}/publishing/auth/regenerate

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/publishing/auth/regenerate' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

400

default

200

{
  "backend": "custom",
  "privateKey": "text",
  "fallbackURL": "https://example.com",
  "integration": "text",
  "object": "publishing-auth"
}

OK

Get the customization configuration for a site.

get

/orgs/{organizationId}/sites/{siteId}/customization

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters

unmaskedboolean · default: falseDeprecated

(Deprecated) Use the getRawCustomizationSettingsById internal endpoint.

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

400

default

200

{
  "title": "text",
  "internationalization": {
    "locale": "en"
  },
  "themes": {
    "default": "light",
    "toggeable": true
  },
  "pdf": {
    "enabled": true
  },
  "feedback": {
    "enabled": true
  },
  "aiSearch": {
    "enabled": true
  },
  "advancedCustomization": {
    "enabled": true
  },
  "git": {
    "showEditLink": true
  },
  "pagination": {
    "enabled": true
  },
  "trademark": {
    "enabled": true
  },
  "privacyPolicy": {
    "url": "https://example.com"
  },
  "socialPreview": {
    "url": "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",
        "links": [
          {
            "title": "text",
            "to": {
              "file": "text",
              "kind": "file"
            }
          }
        ],
        "to": {
          "file": "text",
          "kind": "file"
        }
      }
    ]
  },
  "footer": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "copyright": "text",
    "groups": [
      {
        "title": "text",
        "links": [
          {
            "title": "text",
            "to": {
              "file": "text",
              "kind": "file"
            }
          }
        ]
      }
    ]
  },
  "favicon": {
    "icon": {
      "light": "https://example.com",
      "dark": "https://example.com"
    }
  },
  "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"
    }
  }
}

OK

Update the customization configuration for a site.

put

/orgs/{organizationId}/sites/{siteId}/customization

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Body

titlestring · min: 2 · max: 128

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

internationalizationobjectrequired

themesobjectrequired

Customization options for the dark/light theme modes.

pdfobjectrequired

feedbackobjectrequired

aiSearchobjectrequired

advancedCustomizationobjectrequired

gitobjectrequired

paginationobjectrequired

trademarkobjectrequired

privacyPolicyobjectrequired

socialPreviewobjectrequired

headerobjectrequired

footerobjectrequired

faviconone ofrequired

stylingobjectrequired

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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",
    "internationalization": {
      "locale": "en"
    },
    "themes": {
      "default": "light",
      "toggeable": true
    },
    "pdf": {
      "enabled": true
    },
    "feedback": {
      "enabled": true
    },
    "aiSearch": {
      "enabled": true
    },
    "advancedCustomization": {
      "enabled": true
    },
    "git": {
      "showEditLink": true
    },
    "pagination": {
      "enabled": true
    },
    "trademark": {
      "enabled": true
    },
    "privacyPolicy": {
      "url": "https://example.com"
    },
    "socialPreview": {
      "url": "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",
          "links": [
            {
              "title": "text",
              "to": {
                "file": "text",
                "kind": "file"
              }
            }
          ],
          "to": {
            "file": "text",
            "kind": "file"
          }
        }
      ]
    },
    "footer": {
      "logo": {
        "light": "https://example.com",
        "dark": "https://example.com"
      },
      "copyright": "text",
      "groups": [
        {
          "title": "text",
          "links": [
            {
              "title": "text",
              "to": {
                "file": "text",
                "kind": "file"
              }
            }
          ]
        }
      ]
    },
    "favicon": {
      "icon": {
        "light": "https://example.com",
        "dark": "https://example.com"
      }
    },
    "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"
      }
    }
  }'

200

400

default

200

{
  "title": "text",
  "internationalization": {
    "locale": "en"
  },
  "themes": {
    "default": "light",
    "toggeable": true
  },
  "pdf": {
    "enabled": true
  },
  "feedback": {
    "enabled": true
  },
  "aiSearch": {
    "enabled": true
  },
  "advancedCustomization": {
    "enabled": true
  },
  "git": {
    "showEditLink": true
  },
  "pagination": {
    "enabled": true
  },
  "trademark": {
    "enabled": true
  },
  "privacyPolicy": {
    "url": "https://example.com"
  },
  "socialPreview": {
    "url": "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",
        "links": [
          {
            "title": "text",
            "to": {
              "file": "text",
              "kind": "file"
            }
          }
        ],
        "to": {
          "file": "text",
          "kind": "file"
        }
      }
    ]
  },
  "footer": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "copyright": "text",
    "groups": [
      {
        "title": "text",
        "links": [
          {
            "title": "text",
            "to": {
              "file": "text",
              "kind": "file"
            }
          }
        ]
      }
    ]
  },
  "favicon": {
    "icon": {
      "light": "https://example.com",
      "dark": "https://example.com"
    }
  },
  "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"
    }
  }
}

OK

Query and aggregate events in a site.

post

/orgs/{organizationId}/sites/{siteId}/insights/events/aggregate

Authorizations

useruser-internaluser-staffintegrationintegration-installation

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Body

rangestring · enumrequired

Options: lastYear, last3Months, last30Days, last7Days, last24Hours

limitinteger · min: 1 · max: 1000 · default: 1000

selectone of[]

whereall of[]

groupByone of[]

orderobject

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

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 '{
    "range": "lastYear",
    "limit": 1000,
    "select": [
      {
        "column": "datetime",
        "interval": "hour"
      }
    ],
    "where": [
      {
        "column": "datetime",
        "values": [
          "2025-03-09T02:49:20.214Z"
        ]
      },
      {
        "operator": "in"
      }
    ],
    "groupBy": [
      {
        "column": "datetime",
        "interval": "hour"
      }
    ],
    "order": {
      "by": {
        "column": "datetime",
        "interval": "hour"
      },
      "direction": "asc"
    }
  }'

200

200

{
  "columns": [
    {
      "column": "datetime",
      "values": [
        "2025-03-09T02:49:20.214Z"
      ]
    }
  ]
}

Aggregated events in the site.

Deletes a site share link

delete

/orgs/{organizationId}/sites/{siteId}/share-links/{shareLinkId}

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

application/json

cURL

JavaScript

Python

HTTP

cURL

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

205

default

205

No body

Site share link has been deleted

Update the details of a site share link

patch

/orgs/{organizationId}/sites/{siteId}/share-links/{shareLinkId}

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

activeboolean

namestring · max: 50

Name of the share link

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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"
  }'

200

default

200

{
  "id": "text",
  "createdAt": "2025-03-09T02:49:20.214Z",
  "name": "text",
  "active": true,
  "object": "share-link",
  "urls": {
    "published": "https://example.com"
  }
}

The site share link has been updated

Add a section to a section group

post

/orgs/{organizationId}/sites/{siteId}/section-groups/{siteSectionGroupId}/sections

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

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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"
  }'

201

default

201

{
  "id": "text",
  "title": "text",
  "icon": "gear",
  "object": "site-section-group",
  "sections": [
    {
      "id": "text",
      "title": "text",
      "description": "text",
      "default": true,
      "path": "text",
      "condition": "text",
      "sectionGroup": "text",
      "icon": "gear",
      "object": "site-section",
      "siteSpaces": [
        {
          "id": "text",
          "path": "text",
          "section": "text",
          "space": {
            "id": "text",
            "title": "text",
            "emoji": "🎉",
            "visibility": "public",
            "createdAt": "2025-03-09T02:49:20.214Z",
            "updatedAt": "2025-03-09T02:49:20.214Z",
            "deletedAt": "2025-03-09T02:49:20.214Z",
            "editMode": "live",
            "organization": "text",
            "parent": "text",
            "gitSync": {
              "installationProvider": "github",
              "integration": "text",
              "url": "text",
              "updatedAt": "2025-03-09T02:49:20.214Z"
            },
            "visitorAuth": {
              "backend": "custom"
            },
            "revision": "text",
            "defaultLevel": "admin",
            "comments": 1,
            "changeRequests": 1,
            "changeRequestsOpen": 1,
            "changeRequestsDraft": 1,
            "object": "space",
            "urls": {
              "location": "https://example.com",
              "app": "https://example.com",
              "published": "https://example.com",
              "public": "https://example.com",
              "icon": "https://example.com"
            },
            "permissions": {
              "access": true,
              "admin": true,
              "edit": true,
              "comment": true,
              "merge": true,
              "review": true
            }
          },
          "title": "text",
          "default": true,
          "condition": "text",
          "hasAdvancedCustomizationFeature": true,
          "object": "site-space",
          "urls": {
            "published": "https://example.com"
          }
        }
      ],
      "urls": {
        "published": "https://example.com"
      }
    }
  ]
}

Section added to the section group

Create a page feedback by a visitor on a site.

put

/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/insights/pages/{pageId}/feedbacks/{visitorId}

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

pageIdstringrequired

The unique id of the page

visitorIdstringrequired

The id of the visitor

Body

ratingstring · enumrequired

Options: bad, ok, good

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/insights/pages/{pageId}/feedbacks/{visitorId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "rating": "bad"
  }'

200

201

default

200

{
  "visitorId": "text",
  "rating": "bad",
  "createdAt": "2025-03-09T02:49:20.214Z",
  "revision": "text",
  "object": "page-feedback",
  "urls": {
    "location": "https://example.com"
  }
}

Feedback updated

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

post

/orgs/{organizationId}/sites/{siteId}/section-groups/{siteSectionGroupId}/move

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

positionobject

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

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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": {
        "id": "text",
        "type": "site-section"
      },
      "after": {
        "id": "text",
        "type": "site-section"
      }
    }
  }'

200

400

404

default

200

{
  "id": "text",
  "title": "text",
  "icon": "gear",
  "object": "site-section-group",
  "sections": [
    {
      "id": "text",
      "title": "text",
      "description": "text",
      "default": true,
      "path": "text",
      "condition": "text",
      "sectionGroup": "text",
      "icon": "gear",
      "object": "site-section",
      "siteSpaces": [
        {
          "id": "text",
          "path": "text",
          "section": "text",
          "space": {
            "id": "text",
            "title": "text",
            "emoji": "🎉",
            "visibility": "public",
            "createdAt": "2025-03-09T02:49:20.214Z",
            "updatedAt": "2025-03-09T02:49:20.214Z",
            "deletedAt": "2025-03-09T02:49:20.214Z",
            "editMode": "live",
            "organization": "text",
            "parent": "text",
            "gitSync": {
              "installationProvider": "github",
              "integration": "text",
              "url": "text",
              "updatedAt": "2025-03-09T02:49:20.214Z"
            },
            "visitorAuth": {
              "backend": "custom"
            },
            "revision": "text",
            "defaultLevel": "admin",
            "comments": 1,
            "changeRequests": 1,
            "changeRequestsOpen": 1,
            "changeRequestsDraft": 1,
            "object": "space",
            "urls": {
              "location": "https://example.com",
              "app": "https://example.com",
              "published": "https://example.com",
              "public": "https://example.com",
              "icon": "https://example.com"
            },
            "permissions": {
              "access": true,
              "admin": true,
              "edit": true,
              "comment": true,
              "merge": true,
              "review": true
            }
          },
          "title": "text",
          "default": true,
          "condition": "text",
          "hasAdvancedCustomizationFeature": true,
          "object": "site-space",
          "urls": {
            "published": "https://example.com"
          }
        }
      ],
      "urls": {
        "published": "https://example.com"
      }
    }
  ]
}

Site section group moved

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

post

/orgs/{organizationId}/sites/{siteId}/sections/{siteSectionId}/move

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

positionobject

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

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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": {
        "siteSection": "text",
        "type": "site-section"
      },
      "after": {
        "siteSection": "text",
        "type": "site-section"
      }
    }
  }'

200

400

404

default

200

{
  "id": "text",
  "title": "text",
  "description": "text",
  "default": true,
  "path": "text",
  "condition": "text",
  "sectionGroup": "text",
  "icon": "gear",
  "object": "site-section",
  "siteSpaces": [
    {
      "id": "text",
      "path": "text",
      "section": "text",
      "space": {
        "id": "text",
        "title": "text",
        "emoji": "🎉",
        "visibility": "public",
        "createdAt": "2025-03-09T02:49:20.214Z",
        "updatedAt": "2025-03-09T02:49:20.214Z",
        "deletedAt": "2025-03-09T02:49:20.214Z",
        "editMode": "live",
        "organization": "text",
        "parent": "text",
        "gitSync": {
          "installationProvider": "github",
          "integration": "text",
          "url": "text",
          "updatedAt": "2025-03-09T02:49:20.214Z"
        },
        "visitorAuth": {
          "backend": "custom"
        },
        "revision": "text",
        "defaultLevel": "admin",
        "comments": 1,
        "changeRequests": 1,
        "changeRequestsOpen": 1,
        "changeRequestsDraft": 1,
        "object": "space",
        "urls": {
          "location": "https://example.com",
          "app": "https://example.com",
          "published": "https://example.com",
          "public": "https://example.com",
          "icon": "https://example.com"
        },
        "permissions": {
          "access": true,
          "admin": true,
          "edit": true,
          "comment": true,
          "merge": true,
          "review": true
        }
      },
      "title": "text",
      "default": true,
      "condition": "text",
      "hasAdvancedCustomizationFeature": true,
      "object": "site-space",
      "urls": {
        "published": "https://example.com"
      }
    }
  ],
  "urls": {
    "published": "https://example.com"
  }
}

Site section moved

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

post

/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/move

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

positionobject

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

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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": {
        "siteSpace": "text",
        "type": "site-space"
      },
      "after": {
        "siteSpace": "text",
        "type": "site-space"
      }
    }
  }'

200

400

404

default

200

{
  "id": "text",
  "path": "text",
  "section": "text",
  "space": {
    "id": "text",
    "title": "text",
    "emoji": "🎉",
    "visibility": "public",
    "createdAt": "2025-03-09T02:49:20.214Z",
    "updatedAt": "2025-03-09T02:49:20.214Z",
    "deletedAt": "2025-03-09T02:49:20.214Z",
    "editMode": "live",
    "organization": "text",
    "parent": "text",
    "gitSync": {
      "installationProvider": "github",
      "integration": "text",
      "url": "text",
      "updatedAt": "2025-03-09T02:49:20.214Z"
    },
    "visitorAuth": {
      "backend": "custom"
    },
    "revision": "text",
    "defaultLevel": "admin",
    "comments": 1,
    "changeRequests": 1,
    "changeRequestsOpen": 1,
    "changeRequestsDraft": 1,
    "object": "space",
    "urls": {
      "location": "https://example.com",
      "app": "https://example.com",
      "published": "https://example.com",
      "public": "https://example.com",
      "icon": "https://example.com"
    },
    "permissions": {
      "access": true,
      "admin": true,
      "edit": true,
      "comment": true,
      "merge": true,
      "review": true
    }
  },
  "title": "text",
  "default": true,
  "condition": "text",
  "hasAdvancedCustomizationFeature": true,
  "object": "site-space",
  "urls": {
    "published": "https://example.com"
  }
}

Site space moved

Delete a redirect for a site

delete

/orgs/{organizationId}/sites/{siteId}/redirects/{siteRedirectId}

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

application/json

cURL

JavaScript

Python

HTTP

cURL

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

205

default

205

No body

Site redirect deleted

Update a redirect for a site

patch

/orgs/{organizationId}/sites/{siteId}/redirects/{siteRedirectId}

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: 512

The source path to redirect from.

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

destinationone of

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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": {
      "siteSectionId": "text",
      "kind": "site-section"
    }
  }'

200

default

200

{
  "id": "text",
  "source": "text",
  "destination": {
    "siteSectionId": "text",
    "kind": "site-section"
  },
  "object": "site-redirect"
}

OK

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

post

/orgs/{organizationId}/sites/{siteId}/ads

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Body

topicstring · enum

Topic of the content

Options: webdev, crypto

statusstring · enum

Options: in-review, disabled

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

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 '{
    "topic": "webdev",
    "status": "in-review"
  }'

204

default

204

No body

OK

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

get

/orgs/{organizationId}/sites/{siteId}/publishing/preview

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters

siteSpacestring

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

claimsstring

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

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

400

default

200

{
  "url": "https://example.com"
}

OK

Resolve a redirect in a site by its source path.

get

/orgs/{organizationId}/sites/{siteId}/redirect

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters

shareKeystring

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

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/redirect?source=text' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

404

default

200

{
  "redirect": {
    "id": "text",
    "source": "text",
    "destination": {
      "siteSectionId": "text",
      "kind": "site-section"
    },
    "object": "site-redirect"
  },
  "target": "text"
}

The redirect was resolved successfully.

Get an organization site by its ID

get

/orgs/{organizationId}/sites/{siteId}

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

404

default

200

{
  "id": "text",
  "type": "basic",
  "title": "text",
  "hostname": "text",
  "basename": "text",
  "proxy": "text",
  "visibility": "public",
  "published": true,
  "siteSpaces": 1,
  "createdAt": "2025-03-09T02:49:20.214Z",
  "adaptiveContent": {
    "enabled": true
  },
  "ads": {
    "submittable": true,
    "status": "pending"
  },
  "object": "site",
  "features": [
    {
      "plan": "basic",
      "frozen": true,
      "id": "sites-sections"
    }
  ],
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com"
  }
}

OK

Delete a site in an organization

delete

/orgs/{organizationId}/sites/{siteId}

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

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

205

default

205

No body

Site has been deleted

Update a site in an organization

patch

/orgs/{organizationId}/sites/{siteId}

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Body

titlestring · min: 2 · max: 128

Title of the site

visibilitystring · enum

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.

Options: public, unlisted, share-link, visitor-auth

basenamestring · min: 1 · max: 100

Basename for the site. For e.g. api

adaptiveContentobject

defaultSiteSpacestring

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.

defaultSiteSectionstring

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

proxyone of

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

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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"
  }'

200

default

200

{
  "id": "text",
  "type": "basic",
  "title": "text",
  "hostname": "text",
  "basename": "text",
  "proxy": "text",
  "visibility": "public",
  "published": true,
  "siteSpaces": 1,
  "createdAt": "2025-03-09T02:49:20.214Z",
  "adaptiveContent": {
    "enabled": true
  },
  "ads": {
    "submittable": true,
    "status": "pending"
  },
  "object": "site",
  "features": [
    {
      "plan": "basic",
      "frozen": true,
      "id": "sites-sections"
    }
  ],
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com"
  }
}

OK

Delete a section group on a site in an organization

delete

/orgs/{organizationId}/sites/{siteId}/section-groups/{siteSectionGroupId}

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

application/json

cURL

JavaScript

Python

HTTP

cURL

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

205

default

205

No body

Site section group has been deleted

Update a section group on a site in an organization

patch

/orgs/{organizationId}/sites/{siteId}/section-groups/{siteSectionGroupId}

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: 100

Title of the site section group

iconone of

Name of the icon

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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"
  }'

200

default

200

{
  "id": "text",
  "title": "text",
  "icon": "gear",
  "object": "site-section-group",
  "sections": [
    {
      "id": "text",
      "title": "text",
      "description": "text",
      "default": true,
      "path": "text",
      "condition": "text",
      "sectionGroup": "text",
      "icon": "gear",
      "object": "site-section",
      "siteSpaces": [
        {
          "id": "text",
          "path": "text",
          "section": "text",
          "space": {
            "id": "text",
            "title": "text",
            "emoji": "🎉",
            "visibility": "public",
            "createdAt": "2025-03-09T02:49:20.214Z",
            "updatedAt": "2025-03-09T02:49:20.214Z",
            "deletedAt": "2025-03-09T02:49:20.214Z",
            "editMode": "live",
            "organization": "text",
            "parent": "text",
            "gitSync": {
              "installationProvider": "github",
              "integration": "text",
              "url": "text",
              "updatedAt": "2025-03-09T02:49:20.214Z"
            },
            "visitorAuth": {
              "backend": "custom"
            },
            "revision": "text",
            "defaultLevel": "admin",
            "comments": 1,
            "changeRequests": 1,
            "changeRequestsOpen": 1,
            "changeRequestsDraft": 1,
            "object": "space",
            "urls": {
              "location": "https://example.com",
              "app": "https://example.com",
              "published": "https://example.com",
              "public": "https://example.com",
              "icon": "https://example.com"
            },
            "permissions": {
              "access": true,
              "admin": true,
              "edit": true,
              "comment": true,
              "merge": true,
              "review": true
            }
          },
          "title": "text",
          "default": true,
          "condition": "text",
          "hasAdvancedCustomizationFeature": true,
          "object": "site-space",
          "urls": {
            "published": "https://example.com"
          }
        }
      ],
      "urls": {
        "published": "https://example.com"
      }
    }
  ]
}

OK

Delete a section on a site in an organization

delete

/orgs/{organizationId}/sites/{siteId}/sections/{siteSectionId}

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

application/json

cURL

JavaScript

Python

HTTP

cURL

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

205

default

205

No body

Site section has been deleted

Update a section on a site in an organization

patch

/orgs/{organizationId}/sites/{siteId}/sections/{siteSectionId}

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: 128

Title of the site section

pathstring · min: 1 · max: 100

Path to the section on the site

defaultSiteSpacestring

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

conditionone of

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 of

Name of the icon

descriptionone of

Description of the site section

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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"
  }'

200

default

200

{
  "id": "text",
  "title": "text",
  "description": "text",
  "default": true,
  "path": "text",
  "condition": "text",
  "sectionGroup": "text",
  "icon": "gear",
  "object": "site-section",
  "siteSpaces": [
    {
      "id": "text",
      "path": "text",
      "section": "text",
      "space": {
        "id": "text",
        "title": "text",
        "emoji": "🎉",
        "visibility": "public",
        "createdAt": "2025-03-09T02:49:20.214Z",
        "updatedAt": "2025-03-09T02:49:20.214Z",
        "deletedAt": "2025-03-09T02:49:20.214Z",
        "editMode": "live",
        "organization": "text",
        "parent": "text",
        "gitSync": {
          "installationProvider": "github",
          "integration": "text",
          "url": "text",
          "updatedAt": "2025-03-09T02:49:20.214Z"
        },
        "visitorAuth": {
          "backend": "custom"
        },
        "revision": "text",
        "defaultLevel": "admin",
        "comments": 1,
        "changeRequests": 1,
        "changeRequestsOpen": 1,
        "changeRequestsDraft": 1,
        "object": "space",
        "urls": {
          "location": "https://example.com",
          "app": "https://example.com",
          "published": "https://example.com",
          "public": "https://example.com",
          "icon": "https://example.com"
        },
        "permissions": {
          "access": true,
          "admin": true,
          "edit": true,
          "comment": true,
          "merge": true,
          "review": true
        }
      },
      "title": "text",
      "default": true,
      "condition": "text",
      "hasAdvancedCustomizationFeature": true,
      "object": "site-space",
      "urls": {
        "published": "https://example.com"
      }
    }
  ],
  "urls": {
    "published": "https://example.com"
  }
}

OK

Delete a space on a site in an organization

delete

/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}

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

application/json

cURL

JavaScript

Python

HTTP

cURL

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

205

default

205

No body

Site space has been deleted

Update a space on a site in an organization

patch

/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}

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: 100

Path to the space on the site

conditionone of

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

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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"
  }'

200

default

200

{
  "id": "text",
  "path": "text",
  "section": "text",
  "space": {
    "id": "text",
    "title": "text",
    "emoji": "🎉",
    "visibility": "public",
    "createdAt": "2025-03-09T02:49:20.214Z",
    "updatedAt": "2025-03-09T02:49:20.214Z",
    "deletedAt": "2025-03-09T02:49:20.214Z",
    "editMode": "live",
    "organization": "text",
    "parent": "text",
    "gitSync": {
      "installationProvider": "github",
      "integration": "text",
      "url": "text",
      "updatedAt": "2025-03-09T02:49:20.214Z"
    },
    "visitorAuth": {
      "backend": "custom"
    },
    "revision": "text",
    "defaultLevel": "admin",
    "comments": 1,
    "changeRequests": 1,
    "changeRequestsOpen": 1,
    "changeRequestsDraft": 1,
    "object": "space",
    "urls": {
      "location": "https://example.com",
      "app": "https://example.com",
      "published": "https://example.com",
      "public": "https://example.com",
      "icon": "https://example.com"
    },
    "permissions": {
      "access": true,
      "admin": true,
      "edit": true,
      "comment": true,
      "merge": true,
      "review": true
    }
  },
  "title": "text",
  "default": true,
  "condition": "text",
  "hasAdvancedCustomizationFeature": true,
  "object": "site-space",
  "urls": {
    "published": "https://example.com"
  }
}

OK

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

post

/orgs/{organizationId}/sites/{siteId}/publish

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

default

200

{
  "id": "text",
  "type": "basic",
  "title": "text",
  "hostname": "text",
  "basename": "text",
  "proxy": "text",
  "visibility": "public",
  "published": true,
  "siteSpaces": 1,
  "createdAt": "2025-03-09T02:49:20.214Z",
  "adaptiveContent": {
    "enabled": true
  },
  "ads": {
    "submittable": true,
    "status": "pending"
  },
  "object": "site",
  "features": [
    {
      "plan": "basic",
      "frozen": true,
      "id": "sites-sections"
    }
  ],
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com"
  }
}

Site published successfully

List all the sites created in an organization

get

/orgs/{organizationId}/sites

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

spacestring

Identifier of the space to filter the sites by

titlestring

Filter sites by their title

publishedboolean

Filter sites by their published status

typestring · enum[]

The type of the site

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

default

200

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "id": "text",
      "type": "basic",
      "title": "text",
      "hostname": "text",
      "basename": "text",
      "proxy": "text",
      "visibility": "public",
      "published": true,
      "siteSpaces": 1,
      "createdAt": "2025-03-09T02:49:20.214Z",
      "adaptiveContent": {
        "enabled": true
      },
      "ads": {
        "submittable": true,
        "status": "pending"
      },
      "object": "site",
      "features": [
        {
          "plan": "basic",
          "frozen": true,
          "id": "sites-sections"
        }
      ],
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com",
        "published": "https://example.com"
      }
    }
  ]
}

OK

Create a site in an organization

post

/orgs/{organizationId}/sites

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

Body

typestring · enum

The type of the site, defaults to Basic

Options: basic, premium, ultimate, sponsored, legacy-basic, legacy-premium

titlestring · min: 2 · max: 128

Title of the site

visibilitystring · enum

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.

Options: public, unlisted, share-link, visitor-auth

spacesone of

ID of spaces to be added to the site

Create a new space associated to the site

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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"
    ]
  }'

201

default

201

{
  "id": "text",
  "type": "basic",
  "title": "text",
  "hostname": "text",
  "basename": "text",
  "proxy": "text",
  "visibility": "public",
  "published": true,
  "siteSpaces": 1,
  "createdAt": "2025-03-09T02:49:20.214Z",
  "adaptiveContent": {
    "enabled": true
  },
  "ads": {
    "submittable": true,
    "status": "pending"
  },
  "object": "site",
  "features": [
    {
      "plan": "basic",
      "frozen": true,
      "id": "sites-sections"
    }
  ],
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com"
  }
}

Site created

List all the share links created in a site

get

/orgs/{organizationId}/sites/{siteId}/share-links

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

default

200

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "id": "text",
      "createdAt": "2025-03-09T02:49:20.214Z",
      "name": "text",
      "active": true,
      "object": "share-link",
      "urls": {
        "published": "https://example.com"
      }
    }
  ]
}

OK

Create a share link in a site

post

/orgs/{organizationId}/sites/{siteId}/share-links

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

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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"
  }'

201

default

201

{
  "id": "text",
  "createdAt": "2025-03-09T02:49:20.214Z",
  "name": "text",
  "active": true,
  "object": "share-link",
  "urls": {
    "published": "https://example.com"
  }
}

The share link has been created

List all the site spaces under a site in an organization

get

/orgs/{organizationId}/sites/{siteId}/site-spaces

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters

shareKeystring

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

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

defaultboolean

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

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

default

200

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "id": "text",
      "path": "text",
      "section": "text",
      "space": {
        "id": "text",
        "title": "text",
        "emoji": "🎉",
        "visibility": "public",
        "createdAt": "2025-03-09T02:49:20.214Z",
        "updatedAt": "2025-03-09T02:49:20.214Z",
        "deletedAt": "2025-03-09T02:49:20.214Z",
        "editMode": "live",
        "organization": "text",
        "parent": "text",
        "gitSync": {
          "installationProvider": "github",
          "integration": "text",
          "url": "text",
          "updatedAt": "2025-03-09T02:49:20.214Z"
        },
        "visitorAuth": {
          "backend": "custom"
        },
        "revision": "text",
        "defaultLevel": "admin",
        "comments": 1,
        "changeRequests": 1,
        "changeRequestsOpen": 1,
        "changeRequestsDraft": 1,
        "object": "space",
        "urls": {
          "location": "https://example.com",
          "app": "https://example.com",
          "published": "https://example.com",
          "public": "https://example.com",
          "icon": "https://example.com"
        },
        "permissions": {
          "access": true,
          "admin": true,
          "edit": true,
          "comment": true,
          "merge": true,
          "review": true
        }
      },
      "title": "text",
      "default": true,
      "condition": "text",
      "hasAdvancedCustomizationFeature": true,
      "object": "site-space",
      "urls": {
        "published": "https://example.com"
      }
    }
  ]
}

OK

Add a space to a site in an organization

post

/orgs/{organizationId}/sites/{siteId}/site-spaces

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Body

spaceIdstringrequired

ID of the space

sectionIdstring

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

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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"
  }'

201

default

201

{
  "id": "text",
  "path": "text",
  "section": "text",
  "space": {
    "id": "text",
    "title": "text",
    "emoji": "🎉",
    "visibility": "public",
    "createdAt": "2025-03-09T02:49:20.214Z",
    "updatedAt": "2025-03-09T02:49:20.214Z",
    "deletedAt": "2025-03-09T02:49:20.214Z",
    "editMode": "live",
    "organization": "text",
    "parent": "text",
    "gitSync": {
      "installationProvider": "github",
      "integration": "text",
      "url": "text",
      "updatedAt": "2025-03-09T02:49:20.214Z"
    },
    "visitorAuth": {
      "backend": "custom"
    },
    "revision": "text",
    "defaultLevel": "admin",
    "comments": 1,
    "changeRequests": 1,
    "changeRequestsOpen": 1,
    "changeRequestsDraft": 1,
    "object": "space",
    "urls": {
      "location": "https://example.com",
      "app": "https://example.com",
      "published": "https://example.com",
      "public": "https://example.com",
      "icon": "https://example.com"
    },
    "permissions": {
      "access": true,
      "admin": true,
      "edit": true,
      "comment": true,
      "merge": true,
      "review": true
    }
  },
  "title": "text",
  "default": true,
  "condition": "text",
  "hasAdvancedCustomizationFeature": true,
  "object": "site-space",
  "urls": {
    "published": "https://example.com"
  }
}

Space added to the site

List all the section groups under a site in an organization

get

/orgs/{organizationId}/sites/{siteId}/section-groups

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

default

200

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "id": "text",
      "title": "text",
      "icon": "gear",
      "object": "site-section-group",
      "sections": [
        {
          "id": "text",
          "title": "text",
          "description": "text",
          "default": true,
          "path": "text",
          "condition": "text",
          "sectionGroup": "text",
          "icon": "gear",
          "object": "site-section",
          "siteSpaces": [
            {
              "id": "text",
              "path": "text",
              "section": "text",
              "space": {
                "id": "text",
                "title": "text",
                "emoji": "🎉",
                "visibility": "public",
                "createdAt": "2025-03-09T02:49:20.214Z",
                "updatedAt": "2025-03-09T02:49:20.214Z",
                "deletedAt": "2025-03-09T02:49:20.214Z",
                "editMode": "live",
                "organization": "text",
                "parent": "text",
                "gitSync": {
                  "installationProvider": "github",
                  "integration": "text",
                  "url": "text",
                  "updatedAt": "2025-03-09T02:49:20.214Z"
                },
                "visitorAuth": {
                  "backend": "custom"
                },
                "revision": "text",
                "defaultLevel": "admin",
                "comments": 1,
                "changeRequests": 1,
                "changeRequestsOpen": 1,
                "changeRequestsDraft": 1,
                "object": "space",
                "urls": {
                  "location": "https://example.com",
                  "app": "https://example.com",
                  "published": "https://example.com",
                  "public": "https://example.com",
                  "icon": "https://example.com"
                },
                "permissions": {
                  "access": true,
                  "admin": true,
                  "edit": true,
                  "comment": true,
                  "merge": true,
                  "review": true
                }
              },
              "title": "text",
              "default": true,
              "condition": "text",
              "hasAdvancedCustomizationFeature": true,
              "object": "site-space",
              "urls": {
                "published": "https://example.com"
              }
            }
          ],
          "urls": {
            "published": "https://example.com"
          }
        }
      ]
    }
  ]
}

OK

Add a section group to a site in an organization

post

/orgs/{organizationId}/sites/{siteId}/section-groups

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

sectionsstring[]

IDs of the sections to be added to the section group

iconone of

Name of the icon

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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",
    "sections": [
      "text"
    ],
    "icon": "gear"
  }'

201

default

201

{
  "id": "text",
  "title": "text",
  "icon": "gear",
  "object": "site-section-group",
  "sections": [
    {
      "id": "text",
      "title": "text",
      "description": "text",
      "default": true,
      "path": "text",
      "condition": "text",
      "sectionGroup": "text",
      "icon": "gear",
      "object": "site-section",
      "siteSpaces": [
        {
          "id": "text",
          "path": "text",
          "section": "text",
          "space": {
            "id": "text",
            "title": "text",
            "emoji": "🎉",
            "visibility": "public",
            "createdAt": "2025-03-09T02:49:20.214Z",
            "updatedAt": "2025-03-09T02:49:20.214Z",
            "deletedAt": "2025-03-09T02:49:20.214Z",
            "editMode": "live",
            "organization": "text",
            "parent": "text",
            "gitSync": {
              "installationProvider": "github",
              "integration": "text",
              "url": "text",
              "updatedAt": "2025-03-09T02:49:20.214Z"
            },
            "visitorAuth": {
              "backend": "custom"
            },
            "revision": "text",
            "defaultLevel": "admin",
            "comments": 1,
            "changeRequests": 1,
            "changeRequestsOpen": 1,
            "changeRequestsDraft": 1,
            "object": "space",
            "urls": {
              "location": "https://example.com",
              "app": "https://example.com",
              "published": "https://example.com",
              "public": "https://example.com",
              "icon": "https://example.com"
            },
            "permissions": {
              "access": true,
              "admin": true,
              "edit": true,
              "comment": true,
              "merge": true,
              "review": true
            }
          },
          "title": "text",
          "default": true,
          "condition": "text",
          "hasAdvancedCustomizationFeature": true,
          "object": "site-space",
          "urls": {
            "published": "https://example.com"
          }
        }
      ],
      "urls": {
        "published": "https://example.com"
      }
    }
  ]
}

Section group added to the site

List all the site sections under a site in an organization

get

/orgs/{organizationId}/sites/{siteId}/sections

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters

shareKeystring

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

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

default

200

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "id": "text",
      "title": "text",
      "description": "text",
      "default": true,
      "path": "text",
      "condition": "text",
      "sectionGroup": "text",
      "icon": "gear",
      "object": "site-section",
      "siteSpaces": [
        {
          "id": "text",
          "path": "text",
          "section": "text",
          "space": {
            "id": "text",
            "title": "text",
            "emoji": "🎉",
            "visibility": "public",
            "createdAt": "2025-03-09T02:49:20.214Z",
            "updatedAt": "2025-03-09T02:49:20.214Z",
            "deletedAt": "2025-03-09T02:49:20.214Z",
            "editMode": "live",
            "organization": "text",
            "parent": "text",
            "gitSync": {
              "installationProvider": "github",
              "integration": "text",
              "url": "text",
              "updatedAt": "2025-03-09T02:49:20.214Z"
            },
            "visitorAuth": {
              "backend": "custom"
            },
            "revision": "text",
            "defaultLevel": "admin",
            "comments": 1,
            "changeRequests": 1,
            "changeRequestsOpen": 1,
            "changeRequestsDraft": 1,
            "object": "space",
            "urls": {
              "location": "https://example.com",
              "app": "https://example.com",
              "published": "https://example.com",
              "public": "https://example.com",
              "icon": "https://example.com"
            },
            "permissions": {
              "access": true,
              "admin": true,
              "edit": true,
              "comment": true,
              "merge": true,
              "review": true
            }
          },
          "title": "text",
          "default": true,
          "condition": "text",
          "hasAdvancedCustomizationFeature": true,
          "object": "site-space",
          "urls": {
            "published": "https://example.com"
          }
        }
      ],
      "urls": {
        "published": "https://example.com"
      }
    }
  ]
}

OK

Add a section to a site in an organization

post

/orgs/{organizationId}/sites/{siteId}/sections

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: 64

Title of the section

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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"
  }'

201

default

201

{
  "id": "text",
  "title": "text",
  "description": "text",
  "default": true,
  "path": "text",
  "condition": "text",
  "sectionGroup": "text",
  "icon": "gear",
  "object": "site-section",
  "siteSpaces": [
    {
      "id": "text",
      "path": "text",
      "section": "text",
      "space": {
        "id": "text",
        "title": "text",
        "emoji": "🎉",
        "visibility": "public",
        "createdAt": "2025-03-09T02:49:20.214Z",
        "updatedAt": "2025-03-09T02:49:20.214Z",
        "deletedAt": "2025-03-09T02:49:20.214Z",
        "editMode": "live",
        "organization": "text",
        "parent": "text",
        "gitSync": {
          "installationProvider": "github",
          "integration": "text",
          "url": "text",
          "updatedAt": "2025-03-09T02:49:20.214Z"
        },
        "visitorAuth": {
          "backend": "custom"
        },
        "revision": "text",
        "defaultLevel": "admin",
        "comments": 1,
        "changeRequests": 1,
        "changeRequestsOpen": 1,
        "changeRequestsDraft": 1,
        "object": "space",
        "urls": {
          "location": "https://example.com",
          "app": "https://example.com",
          "published": "https://example.com",
          "public": "https://example.com",
          "icon": "https://example.com"
        },
        "permissions": {
          "access": true,
          "admin": true,
          "edit": true,
          "comment": true,
          "merge": true,
          "review": true
        }
      },
      "title": "text",
      "default": true,
      "condition": "text",
      "hasAdvancedCustomizationFeature": true,
      "object": "site-space",
      "urls": {
        "published": "https://example.com"
      }
    }
  ],
  "urls": {
    "published": "https://example.com"
  }
}

Section added to the site

List visitor segments in a site.

get

/orgs/{organizationId}/sites/{siteId}/insights/visitor-segments

Authorizations

useruser-internaluser-staffintegrationintegration-installation

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/insights/visitor-segments' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

200

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    "[Circular Reference]"
  ]
}

List of visitor segments in the site.

List the redirects configured for a site.

get

/orgs/{organizationId}/sites/{siteId}/redirects

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

default

200

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "items": [
    {
      "id": "text",
      "source": "text",
      "destination": {
        "siteSectionId": "text",
        "kind": "site-section"
      },
      "object": "site-redirect"
    }
  ]
}

The list of redirects for the site.

Configure a redirect explicitly for a site.

post

/orgs/{organizationId}/sites/{siteId}/redirects

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

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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": {
      "siteSectionId": "text",
      "kind": "site-section"
    }
  }'

201

default

201

{
  "id": "text",
  "source": "text",
  "destination": {
    "siteSectionId": "text",
    "kind": "site-section"
  },
  "object": "site-redirect"
}

The redirect was created successfully.

Search content in a site

post

/orgs/{organizationId}/sites/{siteId}/search

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Query parameters

pagestring

Identifier of the page results to fetch.

limitnumber · max: 1000

The number of results per page

Body

all of

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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"
      ]
    }
  }'

200

default

200

{
  "count": 1,
  "next": {
    "page": "text"
  },
  "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

Get the customization configuration for a site space.

get

/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/customization

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: falseDeprecated

(Deprecated) Use the getRawCustomizationSettingsById internal endpoint.

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

400

default

200

{
  "title": "text",
  "internationalization": {
    "locale": "en"
  },
  "themes": {
    "default": "light",
    "toggeable": true
  },
  "pdf": {
    "enabled": true
  },
  "feedback": {
    "enabled": true
  },
  "aiSearch": {
    "enabled": true
  },
  "advancedCustomization": {
    "enabled": true
  },
  "git": {
    "showEditLink": true
  },
  "pagination": {
    "enabled": true
  },
  "trademark": {
    "enabled": true
  },
  "privacyPolicy": {
    "url": "https://example.com"
  },
  "socialPreview": {
    "url": "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",
        "links": [
          {
            "title": "text",
            "to": {
              "file": "text",
              "kind": "file"
            }
          }
        ],
        "to": {
          "file": "text",
          "kind": "file"
        }
      }
    ]
  },
  "footer": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "copyright": "text",
    "groups": [
      {
        "title": "text",
        "links": [
          {
            "title": "text",
            "to": {
              "file": "text",
              "kind": "file"
            }
          }
        ]
      }
    ]
  },
  "favicon": {
    "icon": {
      "light": "https://example.com",
      "dark": "https://example.com"
    }
  },
  "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"
    }
  }
}

OK

Removes the customization configuration for a site space.

delete

/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/customization

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

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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

205

400

default

205

No body

Site space customization removed

Override the customization configuration for a site space.

patch

/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/customization

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 of

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

pdfobject

feedbackobject

aiSearchobject

gitobject

paginationobject

trademarkobject

faviconone of

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

internationalizationobject

headerobject

footerobject

themesobject

privacyPolicyobject

socialPreviewobject

stylingobject

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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",
    "pdf": {
      "enabled": true
    },
    "feedback": {
      "enabled": true
    },
    "aiSearch": {
      "enabled": true
    },
    "git": {
      "showEditLink": true
    },
    "pagination": {
      "enabled": true
    },
    "trademark": {
      "enabled": true
    },
    "favicon": {
      "icon": {
        "light": "https://example.com",
        "dark": "https://example.com"
      }
    },
    "internationalization": {
      "locale": "en"
    },
    "header": {
      "links": [
        {
          "title": "text",
          "style": "link",
          "links": [
            {
              "title": "text",
              "to": {
                "file": "text",
                "kind": "file"
              }
            }
          ],
          "to": {
            "file": "text",
            "kind": "file"
          }
        }
      ],
      "preset": "default",
      "logo": {
        "light": "https://example.com",
        "dark": "https://example.com"
      },
      "backgroundColor": {
        "light": "text",
        "dark": "text"
      },
      "linkColor": {
        "light": "text",
        "dark": "text"
      }
    },
    "footer": {
      "copyright": "text",
      "groups": [
        {
          "title": "text",
          "links": [
            {
              "title": "text",
              "to": {
                "file": "text",
                "kind": "file"
              }
            }
          ]
        }
      ],
      "logo": {
        "light": "https://example.com",
        "dark": "https://example.com"
      }
    },
    "themes": {
      "toggeable": true,
      "default": "light"
    },
    "privacyPolicy": {
      "url": "https://example.com"
    },
    "socialPreview": {
      "url": "https://example.com"
    },
    "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",
      "background": "plain",
      "sidebar": {
        "background": "default",
        "list": "default"
      }
    }
  }'

200

400

default

200

{
  "title": "text",
  "internationalization": {
    "locale": "en"
  },
  "themes": {
    "default": "light",
    "toggeable": true
  },
  "pdf": {
    "enabled": true
  },
  "feedback": {
    "enabled": true
  },
  "aiSearch": {
    "enabled": true
  },
  "advancedCustomization": {
    "enabled": true
  },
  "git": {
    "showEditLink": true
  },
  "pagination": {
    "enabled": true
  },
  "trademark": {
    "enabled": true
  },
  "privacyPolicy": {
    "url": "https://example.com"
  },
  "socialPreview": {
    "url": "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",
        "links": [
          {
            "title": "text",
            "to": {
              "file": "text",
              "kind": "file"
            }
          }
        ],
        "to": {
          "file": "text",
          "kind": "file"
        }
      }
    ]
  },
  "footer": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "copyright": "text",
    "groups": [
      {
        "title": "text",
        "links": [
          {
            "title": "text",
            "to": {
              "file": "text",
              "kind": "file"
            }
          }
        ]
      }
    ]
  },
  "favicon": {
    "icon": {
      "light": "https://example.com",
      "dark": "https://example.com"
    }
  },
  "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"
    }
  }
}

OK

Track events in a site.

Track events in a site.

post

/orgs/{organizationId}/sites/{siteId}/insights/events

Authorizations

useruser-internaluser-staffintegrationintegration-installation

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Body

eventsone of[]required

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

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",
          "ip": "text",
          "userAgent": "text",
          "language": "text",
          "visitorAuthToken": "text",
          "cookies": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "referrer": null
        },
        "location": {
          "url": "https://example.com",
          "siteSection": "text",
          "siteSpace": "text",
          "siteShareKey": "text",
          "space": "text",
          "revision": "text",
          "page": "text"
        },
        "timestamp": "2025-03-09T02:49:20.214Z",
        "type": "page_view"
      }
    ]
  }'

204

default

204

No body

Events have been tracked.