Site sections

Create and organize high-level sections for your docs site.

Sections help partition your site's content at the top level. They can be modified, deleted, or reorganized to reflect your site's changing structure.

The SiteSection object

Attributes

objectstring · enumRequired

The object type, which is always "site-section"

Possible values:

idstringRequired

Unique identifier of the site section

titlestring · min: 2 · max: 128Required

Title of the site section

descriptionstring · max: 256Optional

Description of the site section

defaultbooleanOptional

Whether this is the default section for the site

pathstring · min: 1 · max: 100Required

Path to the section on the site

conditionstring · min: 1 · max: 1024Optional

Conditional expression used to evaluate whether the site section should be shown to the site's visitor.

sectionGroupstringOptional

ID of the section group the section belongs to in the site

iconstring · icon · max: 50Optional

Name of the icon

Example: gear

The SiteSection object

{
  "object": "site-section",
  "id": "text",
  "title": "text",
  "description": "text",
  "default": true,
  "path": "text",
  "condition": "text",
  "sectionGroup": "text",
  "siteSpaces": [
    {
      "object": "site-space",
      "id": "text",
      "path": "text",
      "section": "text",
      "space": {
        "object": "space",
        "id": "text",
        "title": "text",
        "emoji": "🎉",
        "visibility": "public",
        "createdAt": "2025-08-26T22:07:16.661Z",
        "updatedAt": "2025-08-26T22:07:16.661Z",
        "deletedAt": "2025-08-26T22:07:16.661Z",
        "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",
        "language": "en",
        "gitSync": {
          "repoName": "text",
          "installationProvider": "github",
          "integration": "text",
          "url": "text",
          "updatedAt": "2025-08-26T22:07:16.661Z"
        },
        "visitorAuth": {
          "backend": "custom"
        },
        "revision": "text",
        "defaultLevel": "admin",
        "comments": 1,
        "changeRequests": 1,
        "changeRequestsOpen": 1,
        "changeRequestsDraft": 1,
        "permissions": {
          "view": true,
          "access": true,
          "admin": true,
          "viewInviteLinks": true,
          "edit": true,
          "triggerGitSync": true,
          "comment": true,
          "merge": true,
          "review": true,
          "installIntegration": true
        }
      },
      "title": "text",
      "default": true,
      "condition": "text",
      "hasAdvancedCustomizationFeature": true,
      "urls": {
        "published": "https://example.com"
      }
    }
  ],
  "urls": {
    "published": "https://example.com"
  },
  "icon": "gear"
}

List all site sections

get

Authorizations

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Query parameters

shareKeystringOptional

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

pagestringOptional

Identifier of the page results to fetch.

limitnumber · max: 1000Optional

The number of results per page

Responses

200

OK

application/json

Responseall of

get

HTTPcURLJavaScriptPython

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

200

OK

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "site-section",
      "id": "text",
      "title": "text",
      "description": "text",
      "default": true,
      "path": "text",
      "condition": "text",
      "sectionGroup": "text",
      "siteSpaces": [
        {
          "object": "site-space",
          "id": "text",
          "path": "text",
          "section": "text",
          "space": {
            "object": "space",
            "id": "text",
            "title": "text",
            "emoji": "🎉",
            "visibility": "public",
            "createdAt": "2025-08-26T22:07:16.661Z",
            "updatedAt": "2025-08-26T22:07:16.661Z",
            "deletedAt": "2025-08-26T22:07:16.661Z",
            "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",
            "language": "en",
            "gitSync": {
              "repoName": "text",
              "installationProvider": "github",
              "integration": "text",
              "url": "text",
              "updatedAt": "2025-08-26T22:07:16.661Z"
            },
            "visitorAuth": {
              "backend": "custom"
            },
            "revision": "text",
            "defaultLevel": "admin",
            "comments": 1,
            "changeRequests": 1,
            "changeRequestsOpen": 1,
            "changeRequestsDraft": 1,
            "permissions": {
              "view": true,
              "access": true,
              "admin": true,
              "viewInviteLinks": true,
              "edit": true,
              "triggerGitSync": true,
              "comment": true,
              "merge": true,
              "review": true,
              "installIntegration": 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

post

Authorizations

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

Body

spaceIdstringRequired

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

titleone ofOptional

string · min: 2 · max: 128Optional

Title of the site section

or

string · enum | nullableOptionalPossible values:

iconone ofOptional

string · icon · max: 50Optional

Name of the icon

Example: gear

or

string · enum | nullableOptionalPossible values:

Responses

201

Section added to the site

application/json

post

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

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

201

Section added to the site

{
  "object": "site-section",
  "id": "text",
  "title": "text",
  "description": "text",
  "default": true,
  "path": "text",
  "condition": "text",
  "sectionGroup": "text",
  "siteSpaces": [
    {
      "object": "site-space",
      "id": "text",
      "path": "text",
      "section": "text",
      "space": {
        "object": "space",
        "id": "text",
        "title": "text",
        "emoji": "🎉",
        "visibility": "public",
        "createdAt": "2025-08-26T22:07:16.661Z",
        "updatedAt": "2025-08-26T22:07:16.661Z",
        "deletedAt": "2025-08-26T22:07:16.661Z",
        "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",
        "language": "en",
        "gitSync": {
          "repoName": "text",
          "installationProvider": "github",
          "integration": "text",
          "url": "text",
          "updatedAt": "2025-08-26T22:07:16.661Z"
        },
        "visitorAuth": {
          "backend": "custom"
        },
        "revision": "text",
        "defaultLevel": "admin",
        "comments": 1,
        "changeRequests": 1,
        "changeRequestsOpen": 1,
        "changeRequestsDraft": 1,
        "permissions": {
          "view": true,
          "access": true,
          "admin": true,
          "viewInviteLinks": true,
          "edit": true,
          "triggerGitSync": true,
          "comment": true,
          "merge": true,
          "review": true,
          "installIntegration": true
        }
      },
      "title": "text",
      "default": true,
      "condition": "text",
      "hasAdvancedCustomizationFeature": true,
      "urls": {
        "published": "https://example.com"
      }
    }
  ],
  "urls": {
    "published": "https://example.com"
  },
  "icon": "gear"
}

Delete a site section

delete

Authorizations

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

siteSectionIdstringRequired

The unique id of the section within a site

Responses

204

Site section did not exist

205

Site section has been deleted

delete

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 site section

patch

Authorizations

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

siteSectionIdstringRequired

The unique id of the section within a site

Body

titlestring · min: 2 · max: 128Optional

Title of the site section

pathstring · min: 1 · max: 100Optional

Path to the section on the site

defaultSiteSpacestringOptional

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

conditionone ofOptional

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

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:

descriptionone ofOptional

string · max: 256Optional

Description of the site section

or

string · enum | nullableOptionalPossible values:

Responses

200

OK

application/json

patch

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

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

200

OK

{
  "object": "site-section",
  "id": "text",
  "title": "text",
  "description": "text",
  "default": true,
  "path": "text",
  "condition": "text",
  "sectionGroup": "text",
  "siteSpaces": [
    {
      "object": "site-space",
      "id": "text",
      "path": "text",
      "section": "text",
      "space": {
        "object": "space",
        "id": "text",
        "title": "text",
        "emoji": "🎉",
        "visibility": "public",
        "createdAt": "2025-08-26T22:07:16.661Z",
        "updatedAt": "2025-08-26T22:07:16.661Z",
        "deletedAt": "2025-08-26T22:07:16.661Z",
        "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",
        "language": "en",
        "gitSync": {
          "repoName": "text",
          "installationProvider": "github",
          "integration": "text",
          "url": "text",
          "updatedAt": "2025-08-26T22:07:16.661Z"
        },
        "visitorAuth": {
          "backend": "custom"
        },
        "revision": "text",
        "defaultLevel": "admin",
        "comments": 1,
        "changeRequests": 1,
        "changeRequestsOpen": 1,
        "changeRequestsDraft": 1,
        "permissions": {
          "view": true,
          "access": true,
          "admin": true,
          "viewInviteLinks": true,
          "edit": true,
          "triggerGitSync": true,
          "comment": true,
          "merge": true,
          "review": true,
          "installIntegration": true
        }
      },
      "title": "text",
      "default": true,
      "condition": "text",
      "hasAdvancedCustomizationFeature": true,
      "urls": {
        "published": "https://example.com"
      }
    }
  ],
  "urls": {
    "published": "https://example.com"
  },
  "icon": "gear"
}

Deprecated

Move a site section to a new position. (Deprecated) use sortSiteStructure instead.

post

Authorizations

Path parameters

organizationIdstringRequired

The unique id of the organization

siteIdstringRequired

The unique id of the site

siteSectionIdstringRequired

The unique id of the section within a site

Body

Responses

200

Site section moved

application/json

400

Invalid move site section position provided

application/json

404

No matching Site section found

application/json

post

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",
  "description": "text",
  "default": true,
  "path": "text",
  "condition": "text",
  "sectionGroup": "text",
  "siteSpaces": [
    {
      "object": "site-space",
      "id": "text",
      "path": "text",
      "section": "text",
      "space": {
        "object": "space",
        "id": "text",
        "title": "text",
        "emoji": "🎉",
        "visibility": "public",
        "createdAt": "2025-08-26T22:07:16.661Z",
        "updatedAt": "2025-08-26T22:07:16.661Z",
        "deletedAt": "2025-08-26T22:07:16.661Z",
        "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",
        "language": "en",
        "gitSync": {
          "repoName": "text",
          "installationProvider": "github",
          "integration": "text",
          "url": "text",
          "updatedAt": "2025-08-26T22:07:16.661Z"
        },
        "visitorAuth": {
          "backend": "custom"
        },
        "revision": "text",
        "defaultLevel": "admin",
        "comments": 1,
        "changeRequests": 1,
        "changeRequestsOpen": 1,
        "changeRequestsDraft": 1,
        "permissions": {
          "view": true,
          "access": true,
          "admin": true,
          "viewInviteLinks": true,
          "edit": true,
          "triggerGitSync": true,
          "comment": true,
          "merge": true,
          "review": true,
          "installIntegration": true
        }
      },
      "title": "text",
      "default": true,
      "condition": "text",
      "hasAdvancedCustomizationFeature": true,
      "urls": {
        "published": "https://example.com"
      }
    }
  ],
  "urls": {
    "published": "https://example.com"
  },
  "icon": "gear"
}