Sites

List all the sites created in an organization

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

spacestringOptional

Identifier of the space to filter the sites by

titlestringOptional

Filter sites by their title

publishedbooleanOptional

Filter sites by their published status

Responses

200

OK

application/json

default

Unexpected Error

application/json

get

/orgs/{organizationId}/sites

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/sites HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "site",
      "id": "text",
      "type": "basic",
      "title": "text",
      "hostname": "text",
      "basename": "text",
      "proxy": "text",
      "visibility": "public",
      "published": true,
      "siteSpaces": 1,
      "createdAt": "2026-01-25T23:20:04.240Z",
      "adaptiveContent": {
        "enabled": true
      },
      "ads": {
        "status": "pending",
        "submittable": true
      },
      "urls": {
        "location": "https://example.com",
        "app": "https://example.com",
        "published": "https://example.com"
      }
    }
  ]
}

Create a site in an organization

post

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

Body

application/json

typestring · enumOptional

The type of the site, defaults to Basic

Possible values:

titlestring · min: 2 · max: 128Optional

Title of the site

visibilitystring · enumOptional

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

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

Possible values:

spacesone ofOptional

string[]Optional

ID of spaces to be added to the site

or

string · enumOptional

Create a new space associated to the site

Possible values:

Responses

201

Site created

application/json

default

Unexpected Error

application/json

post

/orgs/{organizationId}/sites

HTTPcURLJavaScriptPython

POST /v1/orgs/{organizationId}/sites HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 71

{
  "type": "basic",
  "title": "text",
  "visibility": "public",
  "spaces": [
    "text"
  ]
}

{
  "object": "site",
  "id": "text",
  "type": "basic",
  "title": "text",
  "hostname": "text",
  "basename": "text",
  "proxy": "text",
  "visibility": "public",
  "published": true,
  "siteSpaces": 1,
  "createdAt": "2026-01-25T23:20:04.240Z",
  "adaptiveContent": {
    "enabled": true
  },
  "ads": {
    "status": "pending",
    "submittable": true
  },
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com"
  }
}

Preview checkout information upon publishing a site in the organization.

get

Authorizations

user-internal

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

Query parameters

planstring · enumRequired

The type of the site

Possible values:

Responses

200

OK

application/json

Responseone of

A response to a request to preview a paid operation or action. A user might preview an operation before executing it to see which billing steps would be required (if any). This schema defines the response of that preview request.

or

or

or

or

default

Unexpected Error

application/json

get

/orgs/{organizationId}/sites/publishing/checkout

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/sites/publishing/checkout?plan=basic HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "type": "go-ahead"
}

Get an organization site by its ID

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Responses

200

OK

application/json

404

No matching site found

application/json

default

Unexpected Error

application/json

get

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

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/sites/{siteId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "object": "site",
  "id": "text",
  "type": "basic",
  "title": "text",
  "hostname": "text",
  "basename": "text",
  "proxy": "text",
  "visibility": "public",
  "published": true,
  "siteSpaces": 1,
  "createdAt": "2026-01-25T23:20:04.240Z",
  "adaptiveContent": {
    "enabled": true
  },
  "ads": {
    "status": "pending",
    "submittable": true
  },
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com"
  }
}

Delete a site in an organization

delete

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Responses

205

Site has been deleted

default

Unexpected Error

application/json

delete

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

HTTPcURLJavaScriptPython

DELETE /v1/orgs/{organizationId}/sites/{siteId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update a site in an organization

patch

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Body

application/json

titlestring · min: 2 · max: 128Optional

Title of the site

visibilitystring · enumOptional

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

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

Possible values:

basenamestring · min: 1 · max: 100Optional

Basename for the site. For e.g. api

defaultSiteSpacestringOptional

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

defaultSiteSectionstringOptional

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

proxyone ofOptional

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

string · max: 512Optional

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

Pattern: ^([\w-]+\.)*[\w-]+\.[a-zA-Z]{2,}(\/[\w-]+)+$

or

string · enum | nullableOptionalPossible values:

Responses

200

OK

application/json

default

Unexpected Error

application/json

patch

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

HTTPcURLJavaScriptPython

PATCH /v1/orgs/{organizationId}/sites/{siteId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 160

{
  "title": "text",
  "visibility": "public",
  "basename": "text",
  "adaptiveContent": {
    "enabled": true
  },
  "defaultSiteSpace": "text",
  "defaultSiteSection": "text",
  "proxy": "text"
}

{
  "object": "site",
  "id": "text",
  "type": "basic",
  "title": "text",
  "hostname": "text",
  "basename": "text",
  "proxy": "text",
  "visibility": "public",
  "published": true,
  "siteSpaces": 1,
  "createdAt": "2026-01-25T23:20:04.240Z",
  "adaptiveContent": {
    "enabled": true
  },
  "ads": {
    "status": "pending",
    "submittable": true
  },
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com"
  }
}

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

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Query parameters

shareKeystringOptional

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

Responses

200

OK

application/json

404

No matching site found

application/json

default

Unexpected Error

application/json

get

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

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/sites/{siteId}/published HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "object": "published-content-site",
  "site": {
    "object": "site",
    "id": "text",
    "type": "basic",
    "title": "text",
    "hostname": "text",
    "basename": "text",
    "proxy": "text",
    "visibility": "public",
    "published": true,
    "siteSpaces": 1,
    "createdAt": "2026-01-25T23:20:04.240Z",
    "adaptiveContent": {
      "enabled": true
    },
    "ads": {
      "status": "pending",
      "submittable": true
    },
    "urls": {
      "location": "https://example.com",
      "app": "https://example.com",
      "published": "https://example.com"
    }
  },
  "structure": {
    "type": "sections",
    "structure": [
      {
        "object": "site-section",
        "id": "text",
        "title": "text",
        "default": true,
        "path": "text",
        "condition": "text",
        "sectionGroup": "text",
        "siteSpaces": [
          {
            "object": "site-space",
            "id": "text",
            "path": "text",
            "section": "text",
            "space": {
              "object": "space",
              "id": "text",
              "title": "text",
              "emoji": "🎉",
              "visibility": "public",
              "createdAt": "2026-01-25T23:20:04.240Z",
              "updatedAt": "2026-01-25T23:20:04.240Z",
              "deletedAt": "2026-01-25T23:20:04.240Z",
              "editMode": "live",
              "urls": {
                "location": "https://example.com",
                "app": "https://example.com",
                "published": "https://example.com",
                "public": "https://example.com",
                "icon": "https://example.com"
              },
              "organization": "text",
              "parent": "text",
              "gitSync": {
                "installationProvider": "github",
                "integration": "text",
                "url": "text",
                "updatedAt": "2026-01-25T23:20:04.240Z"
              },
              "visitorAuth": {
                "backend": "custom"
              },
              "revision": "text",
              "defaultLevel": "admin",
              "comments": 1,
              "changeRequests": 1,
              "changeRequestsOpen": 1,
              "changeRequestsDraft": 1,
              "permissions": {
                "access": true,
                "admin": true,
                "edit": true,
                "comment": true,
                "merge": true,
                "review": true
              }
            },
            "title": "text",
            "default": true,
            "condition": "text",
            "hasAdvancedCustomizationFeature": true,
            "urls": {
              "published": "https://example.com"
            }
          }
        ],
        "urls": {
          "published": "https://example.com"
        },
        "icon": "gear"
      }
    ]
  },
  "customizations": {
    "site": {
      "title": "text",
      "styling": {
        "primaryColor": {
          "light": "text",
          "dark": "text"
        },
        "tint": {
          "color": {
            "light": "text",
            "dark": "text"
          }
        },
        "corners": "straight",
        "font": "ABCFavorit",
        "icons": "regular",
        "sidebar": {
          "background": "default",
          "list": "default"
        }
      },
      "internationalization": {
        "locale": "en"
      },
      "favicon": {
        "icon": {
          "light": "https://example.com",
          "dark": "https://example.com"
        }
      },
      "header": {
        "preset": "default",
        "logo": {
          "light": "https://example.com",
          "dark": "https://example.com"
        },
        "backgroundColor": {
          "light": "text",
          "dark": "text"
        },
        "linkColor": {
          "light": "text",
          "dark": "text"
        },
        "links": [
          {
            "title": "text",
            "style": "link",
            "to": {
              "kind": "file",
              "file": "text"
            },
            "links": [
              {
                "title": "text",
                "to": {
                  "kind": "file",
                  "file": "text"
                }
              }
            ]
          }
        ]
      },
      "footer": {
        "logo": {
          "light": "https://example.com",
          "dark": "https://example.com"
        },
        "groups": [
          {
            "title": "text",
            "links": [
              {
                "title": "text",
                "to": {
                  "kind": "file",
                  "file": "text"
                }
              }
            ]
          }
        ],
        "copyright": "text"
      },
      "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"
      }
    },
    "siteSpaces": {
      "ANY_ADDITIONAL_PROPERTY": {
        "title": "text",
        "styling": {
          "primaryColor": {
            "light": "text",
            "dark": "text"
          },
          "tint": {
            "color": {
              "light": "text",
              "dark": "text"
            }
          },
          "corners": "straight",
          "font": "ABCFavorit",
          "icons": "regular",
          "sidebar": {
            "background": "default",
            "list": "default"
          }
        },
        "internationalization": {
          "locale": "en"
        },
        "favicon": {
          "icon": {
            "light": "https://example.com",
            "dark": "https://example.com"
          }
        },
        "header": {
          "preset": "default",
          "logo": {
            "light": "https://example.com",
            "dark": "https://example.com"
          },
          "backgroundColor": {
            "light": "text",
            "dark": "text"
          },
          "linkColor": {
            "light": "text",
            "dark": "text"
          },
          "links": [
            {
              "title": "text",
              "style": "link",
              "to": {
                "kind": "file",
                "file": "text"
              },
              "links": [
                {
                  "title": "text",
                  "to": {
                    "kind": "file",
                    "file": "text"
                  }
                }
              ]
            }
          ]
        },
        "footer": {
          "logo": {
            "light": "https://example.com",
            "dark": "https://example.com"
          },
          "groups": [
            {
              "title": "text",
              "links": [
                {
                  "title": "text",
                  "to": {
                    "kind": "file",
                    "file": "text"
                  }
                }
              ]
            }
          ],
          "copyright": "text"
        },
        "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"
        }
      }
    }
  },
  "scripts": [
    {
      "script": "https://example.com",
      "contentSecurityPolicy": "text",
      "cookies": true
    }
  ]
}

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

post

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Responses

200

Site published successfully

application/json

Responseone of

or

default

Unexpected Error

application/json

post

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

HTTPcURLJavaScriptPython

POST /v1/orgs/{organizationId}/sites/{siteId}/publish HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "object": "site",
  "id": "text",
  "type": "basic",
  "title": "text",
  "hostname": "text",
  "basename": "text",
  "proxy": "text",
  "visibility": "public",
  "published": true,
  "siteSpaces": 1,
  "createdAt": "2026-01-25T23:20:04.240Z",
  "adaptiveContent": {
    "enabled": true
  },
  "ads": {
    "status": "pending",
    "submittable": true
  },
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com"
  }
}

Unpublishes the site.

post

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Responses

200

Site unpublished successfully

application/json

default

Unexpected Error

application/json

post

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

HTTPcURLJavaScriptPython

POST /v1/orgs/{organizationId}/sites/{siteId}/unpublish HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "object": "site",
  "id": "text",
  "type": "basic",
  "title": "text",
  "hostname": "text",
  "basename": "text",
  "proxy": "text",
  "visibility": "public",
  "published": true,
  "siteSpaces": 1,
  "createdAt": "2026-01-25T23:20:04.240Z",
  "adaptiveContent": {
    "enabled": true
  },
  "ads": {
    "status": "pending",
    "submittable": true
  },
  "urls": {
    "location": "https://example.com",
    "app": "https://example.com",
    "published": "https://example.com"
  }
}

List all the share links created in a site

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

Responses

200

OK

application/json

default

Unexpected Error

application/json

get

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

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/sites/{siteId}/share-links HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "share-link",
      "id": "text",
      "createdAt": "2026-01-25T23:20:04.240Z",
      "name": "text",
      "active": true,
      "urls": {
        "published": "https://example.com"
      }
    }
  ]
}

Create a share link in a site

post

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Body

application/json

namestring · max: 50Required

Name of the share link

Responses

201

The share link has been created

application/json

default

Unexpected Error

application/json

post

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

HTTPcURLJavaScriptPython

POST /v1/orgs/{organizationId}/sites/{siteId}/share-links HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 15

{
  "name": "text"
}

{
  "object": "share-link",
  "id": "text",
  "createdAt": "2026-01-25T23:20:04.240Z",
  "name": "text",
  "active": true,
  "urls": {
    "published": "https://example.com"
  }
}

Deletes a site share link

delete

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

205

Site share link has been deleted

default

Unexpected Error

application/json

delete

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

HTTPcURLJavaScriptPython

DELETE /v1/orgs/{organizationId}/sites/{siteId}/share-links/{shareLinkId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update the details of a site share link

patch

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

application/json

activebooleanOptional

namestring · max: 50Optional

Name of the share link

Responses

200

The site share link has been updated

application/json

default

Unexpected Error

application/json

patch

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

HTTPcURLJavaScriptPython

PATCH /v1/orgs/{organizationId}/sites/{siteId}/share-links/{shareLinkId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 29

{
  "active": true,
  "name": "text"
}

{
  "object": "share-link",
  "id": "text",
  "createdAt": "2026-01-25T23:20:04.240Z",
  "name": "text",
  "active": true,
  "urls": {
    "published": "https://example.com"
  }
}

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

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Query parameters

shareKeystringOptional

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

Responses

200

OK

application/json

Responseone of

or

404

No matching site found

application/json

default

Unexpected Error

application/json

get

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

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/sites/{siteId}/structure HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Preview an upgrade to a site plan, returning checkout information.

get

Authorizations

user-internal

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Query parameters

planstring · enumRequired

The type of the site

Possible values:

Responses

200

OK

application/json

Responseone of

A response to a request to preview a paid operation or action. A user might preview an operation before executing it to see which billing steps would be required (if any). This schema defines the response of that preview request.

or

or

or

or

404

No matching site found

application/json

default

Unexpected Error

application/json

get

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

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/sites/{siteId}/plan?plan=basic HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "type": "go-ahead"
}

Update the site plan.

post

Authorizations

user-internal

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Query parameters

successReturnURLstringOptional

The app screen URL to bring the user back to after a successful checkout.

cancelReturnURLstringOptional

The app screen URL to bring the user back to after a canceled checkout.

Body

application/json

planstring · enumRequired

The type of the site

Possible values:

intervalstring · enumOptional

Desired interval for new subscriptions. Defaults to the existing billing interval.

Possible values:

reasonstringOptional

Reason that triggered the billing upgrade

Responses

200

OK

application/json

Responseone of

or

or

default

Unexpected Error

application/json

post

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

HTTPcURLJavaScriptPython

POST /v1/orgs/{organizationId}/sites/{siteId}/plan HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 53

{
  "plan": "basic",
  "interval": "monthly",
  "reason": "text"
}

{
  "type": "checkout",
  "sessionId": "text"
}

Get the publishing authentication settings for a site.

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Responses

200

OK

application/json

400

Bad Request

application/json

default

Unexpected Error

application/json

get

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

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/sites/{siteId}/publishing/auth HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Update the publishing authentication settings for a site.

patch

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Body

application/json

anyOptional

or

and

Responses

200

OK

application/json

400

Bad Request

application/json

default

Unexpected Error

application/json

patch

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

HTTPcURLJavaScriptPython

PATCH /v1/orgs/{organizationId}/sites/{siteId}/publishing/auth HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 56

{
  "backend": "custom",
  "fallbackURL": "https://example.com"
}

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

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

post

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Responses

200

OK

application/json

400

Bad Request

application/json

default

Unexpected Error

application/json

post

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

HTTPcURLJavaScriptPython

POST /v1/orgs/{organizationId}/sites/{siteId}/publishing/auth/regenerate HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

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

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Query parameters

siteSpacestringOptional

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

claimsstringOptional

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

Responses

200

OK

application/json

400

Bad Request

application/json

default

Unexpected Error

application/json

get

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

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/sites/{siteId}/publishing/preview HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Get the customization configuration for a site.

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Query parameters

unmaskedbooleanOptionalDeprecated

(Deprecated) Use the getRawCustomizationSettingsById internal endpoint.

Default: false

Responses

200

OK

application/json

400

Bad Request

application/json

default

Unexpected Error

application/json

get

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

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/sites/{siteId}/customization HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "title": "text",
  "styling": {
    "primaryColor": {
      "light": "text",
      "dark": "text"
    },
    "tint": {
      "color": {
        "light": "text",
        "dark": "text"
      }
    },
    "corners": "straight",
    "font": "ABCFavorit",
    "icons": "regular",
    "sidebar": {
      "background": "default",
      "list": "default"
    }
  },
  "internationalization": {
    "locale": "en"
  },
  "favicon": {
    "icon": {
      "light": "https://example.com",
      "dark": "https://example.com"
    }
  },
  "header": {
    "preset": "default",
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "backgroundColor": {
      "light": "text",
      "dark": "text"
    },
    "linkColor": {
      "light": "text",
      "dark": "text"
    },
    "links": [
      {
        "title": "text",
        "style": "link",
        "to": {
          "kind": "file",
          "file": "text"
        },
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ]
  },
  "footer": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "groups": [
      {
        "title": "text",
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ],
    "copyright": "text"
  },
  "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"
  }
}

Update the customization configuration for a site.

put

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Body

application/json

titlestring · min: 2 · max: 128Optional

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

faviconone ofRequired

or

or

objectOptional

Responses

200

OK

application/json

400

Bad Request

application/json

default

Unexpected Error

application/json

put

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

HTTPcURLJavaScriptPython

PUT /v1/orgs/{organizationId}/sites/{siteId}/customization HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1214

{
  "title": "text",
  "styling": {
    "primaryColor": {
      "light": "text",
      "dark": "text"
    },
    "tint": {
      "color": {
        "light": "text",
        "dark": "text"
      }
    },
    "corners": "straight",
    "font": "ABCFavorit",
    "icons": "regular",
    "sidebar": {
      "background": "default",
      "list": "default"
    }
  },
  "internationalization": {
    "locale": "en"
  },
  "favicon": {
    "icon": {
      "light": "https://example.com",
      "dark": "https://example.com"
    }
  },
  "header": {
    "preset": "default",
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "backgroundColor": {
      "light": "text",
      "dark": "text"
    },
    "linkColor": {
      "light": "text",
      "dark": "text"
    },
    "links": [
      {
        "title": "text",
        "style": "link",
        "to": {
          "kind": "file",
          "file": "text"
        },
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ]
  },
  "footer": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "groups": [
      {
        "title": "text",
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ],
    "copyright": "text"
  },
  "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"
  }
}

{
  "title": "text",
  "styling": {
    "primaryColor": {
      "light": "text",
      "dark": "text"
    },
    "tint": {
      "color": {
        "light": "text",
        "dark": "text"
      }
    },
    "corners": "straight",
    "font": "ABCFavorit",
    "icons": "regular",
    "sidebar": {
      "background": "default",
      "list": "default"
    }
  },
  "internationalization": {
    "locale": "en"
  },
  "favicon": {
    "icon": {
      "light": "https://example.com",
      "dark": "https://example.com"
    }
  },
  "header": {
    "preset": "default",
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "backgroundColor": {
      "light": "text",
      "dark": "text"
    },
    "linkColor": {
      "light": "text",
      "dark": "text"
    },
    "links": [
      {
        "title": "text",
        "style": "link",
        "to": {
          "kind": "file",
          "file": "text"
        },
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ]
  },
  "footer": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "groups": [
      {
        "title": "text",
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ],
    "copyright": "text"
  },
  "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"
  }
}

Get the raw customization settings of a site.

get

Authorizations

user-internal

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Responses

200

OK

application/json

400

Bad Request

application/json

default

Unexpected Error

application/json

get

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

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/sites/{siteId}/customization/raw HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "title": "text",
  "styling": {
    "primaryColor": {
      "light": "text",
      "dark": "text"
    },
    "tint": {
      "color": {
        "light": "text",
        "dark": "text"
      }
    },
    "corners": "straight",
    "font": "ABCFavorit",
    "icons": "regular",
    "sidebar": {
      "background": "default",
      "list": "default"
    }
  },
  "internationalization": {
    "locale": "en"
  },
  "favicon": {
    "icon": {
      "light": "https://example.com",
      "dark": "https://example.com"
    }
  },
  "header": {
    "preset": "default",
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "backgroundColor": {
      "light": "text",
      "dark": "text"
    },
    "linkColor": {
      "light": "text",
      "dark": "text"
    },
    "links": [
      {
        "title": "text",
        "style": "link",
        "to": {
          "kind": "file",
          "file": "text"
        },
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ]
  },
  "footer": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "groups": [
      {
        "title": "text",
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ],
    "copyright": "text"
  },
  "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"
  }
}

List all the site spaces under a site in an organization

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Query parameters

shareKeystringOptional

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

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

defaultbooleanOptional

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

Responses

200

OK

application/json

default

Unexpected Error

application/json

get

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

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/sites/{siteId}/site-spaces HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Add a space to a site in an organization

post

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Body

application/json

spaceIdstringRequired

ID of the space

sectionIdstringOptional

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

Responses

201

Space added to the site

application/json

default

Unexpected Error

application/json

post

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

HTTPcURLJavaScriptPython

POST /v1/orgs/{organizationId}/sites/{siteId}/site-spaces HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 37

{
  "spaceId": "text",
  "sectionId": "text"
}

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

Add a section group to a site in an organization

post

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Body

application/json

titlestring · min: 1 · max: 100Required

Title of the site section group

sectionsstring[]Optional

IDs of the sections to be added to the section group

Responses

201

Section group added to the site

application/json

default

Unexpected Error

application/json

post

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

HTTPcURLJavaScriptPython

POST /v1/orgs/{organizationId}/sites/{siteId}/section-groups HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 36

{
  "title": "text",
  "sections": [
    "text"
  ]
}

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

Delete a section group on a site in an organization

delete

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

205

Site section group has been deleted

default

Unexpected Error

application/json

delete

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

HTTPcURLJavaScriptPython

DELETE /v1/orgs/{organizationId}/sites/{siteId}/section-groups/{siteSectionGroupId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update a section group on a site in an organization

patch

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

application/json

titlestring · min: 1 · max: 100Optional

Title of the site section group

iconone ofOptional

string · icon · max: 50Optional

Name of the icon

Example: gear

or

string · enum | nullableOptionalPossible values:

Responses

200

OK

application/json

default

Unexpected Error

application/json

patch

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

HTTPcURLJavaScriptPython

PATCH /v1/orgs/{organizationId}/sites/{siteId}/section-groups/{siteSectionGroupId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 30

{
  "title": "text",
  "icon": "gear"
}

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

List all the site sections under a site in an organization

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Query parameters

shareKeystringOptional

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

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

Responses

200

OK

application/json

default

Unexpected Error

application/json

get

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

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/sites/{siteId}/sections HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Add a section to a site in an organization

post

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Body

application/json

spaceIdstringRequired

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

titlestring · max: 64Optional

Title of the section

Responses

201

Section added to the site

application/json

default

Unexpected Error

application/json

post

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

HTTPcURLJavaScriptPython

POST /v1/orgs/{organizationId}/sites/{siteId}/sections HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 33

{
  "spaceId": "text",
  "title": "text"
}

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

Delete a section on a site in an organization

delete

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

205

Site section has been deleted

default

Unexpected Error

application/json

delete

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

HTTPcURLJavaScriptPython

DELETE /v1/orgs/{organizationId}/sites/{siteId}/sections/{siteSectionId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update a section on a site in an organization

patch

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

application/json

titlestring · min: 2 · max: 128Optional

Title of the site section

pathstring · min: 1 · max: 100Optional

Path to the section on the site

defaultSiteSpacestringOptional

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

conditionone ofOptional

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

string · min: 1 · max: 1024Optional

or

string · enum | nullableOptionalPossible values:

iconone ofOptional

string · icon · max: 50Optional

Name of the icon

Example: gear

or

string · enum | nullableOptionalPossible values:

Responses

200

OK

application/json

default

Unexpected Error

application/json

patch

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

HTTPcURLJavaScriptPython

PATCH /v1/orgs/{organizationId}/sites/{siteId}/sections/{siteSectionId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 89

{
  "title": "text",
  "path": "text",
  "defaultSiteSpace": "text",
  "condition": "text",
  "icon": "gear"
}

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

Delete a space on a site in an organization

delete

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

205

Site space has been deleted

default

Unexpected Error

application/json

delete

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

HTTPcURLJavaScriptPython

DELETE /v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update a space on a site in an organization

patch

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

application/json

pathstring · min: 1 · max: 100Optional

Path to the space on the site

conditionone ofOptional

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

string · min: 1 · max: 1024Optional

or

string · enum | nullableOptionalPossible values:

Responses

200

OK

application/json

default

Unexpected Error

application/json

patch

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

HTTPcURLJavaScriptPython

PATCH /v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 34

{
  "path": "text",
  "condition": "text"
}

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

Get the customization configuration for a site space.

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

unmaskedbooleanOptionalDeprecated

(Deprecated) Use the getRawCustomizationSettingsById internal endpoint.

Default: false

Responses

200

OK

application/json

400

Bad Request

application/json

default

Unexpected Error

application/json

get

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

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/customization HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "title": "text",
  "styling": {
    "primaryColor": {
      "light": "text",
      "dark": "text"
    },
    "tint": {
      "color": {
        "light": "text",
        "dark": "text"
      }
    },
    "corners": "straight",
    "font": "ABCFavorit",
    "icons": "regular",
    "sidebar": {
      "background": "default",
      "list": "default"
    }
  },
  "internationalization": {
    "locale": "en"
  },
  "favicon": {
    "icon": {
      "light": "https://example.com",
      "dark": "https://example.com"
    }
  },
  "header": {
    "preset": "default",
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "backgroundColor": {
      "light": "text",
      "dark": "text"
    },
    "linkColor": {
      "light": "text",
      "dark": "text"
    },
    "links": [
      {
        "title": "text",
        "style": "link",
        "to": {
          "kind": "file",
          "file": "text"
        },
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ]
  },
  "footer": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "groups": [
      {
        "title": "text",
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ],
    "copyright": "text"
  },
  "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"
  }
}

Removes the customization configuration for a site space.

delete

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

205

Site space customization removed

400

Bad Request

application/json

default

Unexpected Error

application/json

delete

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

HTTPcURLJavaScriptPython

DELETE /v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/customization HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Override the customization configuration for a site space.

patch

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

application/json

The settings that overrides the site customization settings.

titleone ofOptional

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

string · min: 2 · max: 128Optional

Title of the site

or

string · enum | nullableOptionalPossible values:

faviconone ofOptional

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

or

or

object | nullableOptional

Responses

200

OK

application/json

400

Bad Request

application/json

default

Unexpected Error

application/json

patch

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

HTTPcURLJavaScriptPython

PATCH /v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/customization HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1173

{
  "title": "text",
  "styling": {
    "primaryColor": {
      "light": "text",
      "dark": "text"
    },
    "tint": {
      "color": {
        "light": "text",
        "dark": "text"
      }
    },
    "corners": "straight",
    "font": "ABCFavorit",
    "icons": "regular",
    "sidebar": {
      "background": "default",
      "list": "default"
    }
  },
  "internationalization": {
    "locale": "en"
  },
  "favicon": {
    "icon": {
      "light": "https://example.com",
      "dark": "https://example.com"
    }
  },
  "header": {
    "preset": "default",
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "backgroundColor": {
      "light": "text",
      "dark": "text"
    },
    "linkColor": {
      "light": "text",
      "dark": "text"
    },
    "links": [
      {
        "title": "text",
        "style": "link",
        "to": {
          "kind": "file",
          "file": "text"
        },
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ]
  },
  "footer": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "groups": [
      {
        "title": "text",
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ],
    "copyright": "text"
  },
  "themes": {
    "default": "light",
    "toggeable": true
  },
  "pdf": {
    "enabled": true
  },
  "feedback": {
    "enabled": true
  },
  "aiSearch": {
    "enabled": true
  },
  "git": {
    "showEditLink": true
  },
  "pagination": {
    "enabled": true
  },
  "trademark": {
    "enabled": true
  },
  "privacyPolicy": {
    "url": "https://example.com"
  },
  "socialPreview": {
    "url": "https://example.com"
  }
}

{
  "title": "text",
  "styling": {
    "primaryColor": {
      "light": "text",
      "dark": "text"
    },
    "tint": {
      "color": {
        "light": "text",
        "dark": "text"
      }
    },
    "corners": "straight",
    "font": "ABCFavorit",
    "icons": "regular",
    "sidebar": {
      "background": "default",
      "list": "default"
    }
  },
  "internationalization": {
    "locale": "en"
  },
  "favicon": {
    "icon": {
      "light": "https://example.com",
      "dark": "https://example.com"
    }
  },
  "header": {
    "preset": "default",
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "backgroundColor": {
      "light": "text",
      "dark": "text"
    },
    "linkColor": {
      "light": "text",
      "dark": "text"
    },
    "links": [
      {
        "title": "text",
        "style": "link",
        "to": {
          "kind": "file",
          "file": "text"
        },
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ]
  },
  "footer": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "groups": [
      {
        "title": "text",
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ],
    "copyright": "text"
  },
  "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"
  }
}

Get the raw customization settings of a site space.

get

Authorizations

user-internal

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

200

OK

application/json

400

Bad Request

application/json

default

Unexpected Error

application/json

get

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

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/customization/raw HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "title": "text",
  "styling": {
    "primaryColor": {
      "light": "text",
      "dark": "text"
    },
    "tint": {
      "color": {
        "light": "text",
        "dark": "text"
      }
    },
    "corners": "straight",
    "font": "ABCFavorit",
    "icons": "regular",
    "sidebar": {
      "background": "default",
      "list": "default"
    }
  },
  "internationalization": {
    "locale": "en"
  },
  "favicon": {
    "icon": {
      "light": "https://example.com",
      "dark": "https://example.com"
    }
  },
  "header": {
    "preset": "default",
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "backgroundColor": {
      "light": "text",
      "dark": "text"
    },
    "linkColor": {
      "light": "text",
      "dark": "text"
    },
    "links": [
      {
        "title": "text",
        "style": "link",
        "to": {
          "kind": "file",
          "file": "text"
        },
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ]
  },
  "footer": {
    "logo": {
      "light": "https://example.com",
      "dark": "https://example.com"
    },
    "groups": [
      {
        "title": "text",
        "links": [
          {
            "title": "text",
            "to": {
              "kind": "file",
              "file": "text"
            }
          }
        ]
      }
    ],
    "copyright": "text"
  },
  "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"
  },
  "hasOverrides": true
}

Create a page feedback by a visitor on a site.

put

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

application/json

ratingstring · enumRequiredPossible values:

Responses

200

Feedback updated

application/json

201

Feedback created

application/json

default

Unexpected Error

application/json

put

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

HTTPcURLJavaScriptPython

PUT /v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/insights/pages/{pageId}/feedbacks/{visitorId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "rating": "bad"
}

{
  "object": "page-feedback",
  "visitorId": "text",
  "rating": "bad",
  "createdAt": "2026-01-25T23:20:04.240Z",
  "revision": "text",
  "urls": {
    "location": "https://example.com"
  }
}

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

post

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

application/json

Responses

200

Site section moved

application/json

400

Invalid move site section position provided

application/json

404

No matching Site section found

application/json

default

Unexpected Error

application/json

post

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

HTTPcURLJavaScriptPython

POST /v1/orgs/{organizationId}/sites/{siteId}/sections/{siteSectionId}/move HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 121

{
  "position": {
    "before": {
      "type": "site-section",
      "siteSection": "text"
    },
    "after": {
      "type": "site-section",
      "siteSection": "text"
    }
  }
}

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

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

post

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

application/json

Responses

200

Site space moved

application/json

400

Invalid move site space position provided

application/json

404

No matching Site space found

application/json

default

Unexpected Error

application/json

post

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

HTTPcURLJavaScriptPython

POST /v1/orgs/{organizationId}/sites/{siteId}/site-spaces/{siteSpaceId}/move HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 113

{
  "position": {
    "before": {
      "type": "site-space",
      "siteSpace": "text"
    },
    "after": {
      "type": "site-space",
      "siteSpace": "text"
    }
  }
}

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

Track events in a site.

post

Track events in a site.

Authorizations

useruser-internaluser-staffintegrationintegration-installation

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Body

application/json

Responses

204

Events have been tracked.

default

Unexpected Error

application/json

post

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

HTTPcURLJavaScriptPython

POST /v1/orgs/{organizationId}/sites/{siteId}/insights/events HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 408

{
  "events": [
    {
      "session": {
        "visitorId": "text",
        "sessionId": "text",
        "cookies": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "ip": "text",
        "userAgent": "text",
        "language": "text",
        "referrer": null,
        "visitorAuthToken": "text"
      },
      "location": {
        "url": "https://example.com",
        "siteSection": "text",
        "siteSpace": "text",
        "siteShareKey": "text",
        "space": "text",
        "revision": "text",
        "page": "text"
      },
      "timestamp": "2026-01-25T23:20:04.240Z",
      "type": "page_view"
    }
  ]
}

No content

Query and aggregate events in a site.

post

Authorizations

useruser-internaluser-staffintegrationintegration-installation

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Body

application/json

rangestring · enumRequiredPossible values:

Responses

200

Aggregated events in the site.

application/json

post

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

HTTPcURLJavaScriptPython

POST /v1/orgs/{organizationId}/sites/{siteId}/insights/events/aggregate HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 233

{
  "where": [
    {
      "column": "datetime",
      "values": [
        "2026-01-25T23:20:04.240Z"
      ]
    },
    {
      "operator": "in"
    }
  ],
  "groupBy": [
    {
      "column": "datetime",
      "interval": "hour"
    }
  ],
  "order": {
    "by": {
      "column": "datetime",
      "interval": "hour"
    },
    "direction": "asc"
  },
  "range": "lastYear"
}

200

Aggregated events in the site.

{
  "columns": [
    {
      "column": "datetime",
      "values": [
        "2026-01-25T23:20:04.240Z"
      ]
    }
  ]
}

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

post

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Body

application/json

statusstring · enumOptionalPossible values:

topicstring · enumOptional

Topic of the content

Possible values:

Responses

204

OK

default

Unexpected Error

application/json

post

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

HTTPcURLJavaScriptPython

POST /v1/orgs/{organizationId}/sites/{siteId}/ads HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 39

{
  "status": "in-review",
  "topic": "webdev"
}

No content

List the redirects configured for a site.

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Query parameters

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

Responses

200

The list of redirects for the site.

application/json

default

Unexpected Error

application/json

get

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

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/sites/{siteId}/redirects HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Configure a redirect explicitly for a site.

post

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Body

application/json

sourcestring · max: 512Required

The source path to redirect from.

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

destinationone ofRequired

or

or

Responses

201

The redirect was created successfully.

application/json

default

Unexpected Error

application/json

post

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

HTTPcURLJavaScriptPython

POST /v1/orgs/{organizationId}/sites/{siteId}/redirects HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 78

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

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

Delete a redirect for a site

delete

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

205

Site redirect deleted

default

Unexpected Error

application/json

delete

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

HTTPcURLJavaScriptPython

DELETE /v1/orgs/{organizationId}/sites/{siteId}/redirects/{siteRedirectId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update a redirect for a site

patch

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

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

application/json

sourcestring · max: 512Optional

The source path to redirect from.

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

destinationone ofOptional

or

or

Responses

200

OK

application/json

default

Unexpected Error

application/json

patch

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

HTTPcURLJavaScriptPython

PATCH /v1/orgs/{organizationId}/sites/{siteId}/redirects/{siteRedirectId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 78

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

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

Resolve a redirect in a site by its source path.

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Query parameters

shareKeystringOptional

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

sourcestring · max: 512Required

The source path to redirect from.

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

Responses

200

The redirect was resolved successfully.

application/json

404

Not Found

application/json

default

Unexpected Error

application/json

get

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

HTTPcURLJavaScriptPython

GET /v1/orgs/{organizationId}/sites/{siteId}/redirect?source=text HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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