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"

Available options:

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

siteSpacesobject[]required

urlsobjectrequired

URLs associated with the object

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-04-12T21:04:01.285Z",
        "updatedAt": "2025-04-12T21:04:01.285Z",
        "deletedAt": "2025-04-12T21:04:01.285Z",
        "editMode": "live",
        "urls": {
          "location": "https://example.com",
          "app": "https://example.com",
          "published": "https://example.com",
          "public": "https://example.com",
          "icon": "https://example.com"
        },
        "organization": "text",
        "parent": "text",
        "gitSync": {
          "repoName": "text",
          "installationProvider": "github",
          "integration": "text",
          "url": "text",
          "updatedAt": "2025-04-12T21:04:01.285Z"
        },
        "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"
}

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

application/json

cURL

JavaScript

Python

HTTP

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

200

{
  "next": {
    "page": "text"
  },
  "count": 1,
  "items": [
    {
      "object": "site-section",
      "id": "text",
      "title": "text",
      "description": "text",
      "default": true,
      "path": "text",
      "condition": "text",
      "sectionGroup": "text",
      "siteSpaces": [
        {
          "object": "site-space",
          "id": "text",
          "path": "text",
          "section": "text",
          "space": {
            "object": "space",
            "id": "text",
            "title": "text",
            "emoji": "🎉",
            "visibility": "public",
            "createdAt": "2025-04-12T21:04:01.285Z",
            "updatedAt": "2025-04-12T21:04:01.285Z",
            "deletedAt": "2025-04-12T21:04:01.285Z",
            "editMode": "live",
            "urls": {
              "location": "https://example.com",
              "app": "https://example.com",
              "published": "https://example.com",
              "public": "https://example.com",
              "icon": "https://example.com"
            },
            "organization": "text",
            "parent": "text",
            "gitSync": {
              "repoName": "text",
              "installationProvider": "github",
              "integration": "text",
              "url": "text",
              "updatedAt": "2025-04-12T21:04:01.285Z"
            },
            "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

post

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

Body

spaceIdstringrequired

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

titlestring · max: 64optional

Title of the section

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/sections' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "spaceId": "text",
    "title": "text"
  }'

201

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

Section added to the site

Delete a 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

cURL

JavaScript

Python

HTTP

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

205

No Content

Site section has been deleted

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.

iconone ofoptional

Name of the icon

descriptionone ofoptional

Description of the site section

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/sections/{siteSectionId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "text",
    "path": "text",
    "defaultSiteSpace": "text",
    "condition": "text",
    "icon": "gear",
    "description": "text"
  }'

200

{
  "object": "site-section",
  "id": "text",
  "title": "text",
  "description": "text",
  "default": true,
  "path": "text",
  "condition": "text",
  "sectionGroup": "text",
  "siteSpaces": [
    {
      "object": "site-space",
      "id": "text",
      "path": "text",
      "section": "text",
      "space": {
        "object": "space",
        "id": "text",
        "title": "text",
        "emoji": "🎉",
        "visibility": "public",
        "createdAt": "2025-04-12T21:04:01.285Z",
        "updatedAt": "2025-04-12T21:04:01.285Z",
        "deletedAt": "2025-04-12T21:04:01.285Z",
        "editMode": "live",
        "urls": {
          "location": "https://example.com",
          "app": "https://example.com",
          "published": "https://example.com",
          "public": "https://example.com",
          "icon": "https://example.com"
        },
        "organization": "text",
        "parent": "text",
        "gitSync": {
          "repoName": "text",
          "installationProvider": "github",
          "integration": "text",
          "url": "text",
          "updatedAt": "2025-04-12T21:04:01.285Z"
        },
        "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 section to a new position

post

Authorizations

Path parameters

organizationIdstringrequired

The unique id of the organization

siteIdstringrequired

The unique id of the site

siteSectionIdstringrequired

The unique id of the section within a site

Body

positionobjectoptional

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

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/sections/{siteSectionId}/move' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "position": {
      "before": {
        "type": "site-section",
        "siteSection": "text"
      },
      "after": {
        "type": "site-section",
        "siteSection": "text"
      }
    }
  }'

200

400

404

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

Site section moved

Was this helpful?

The SiteSection object

Show child attributes

Show child attributes

The SiteSection object

List all site sections

Add a section to a site

Delete a site section

Update a site section

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Show child attributes

Move a site section to a new position

Show child attributes