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

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-16T04:38:06.187Z",
        "updatedAt": "2025-04-16T04:38:06.187Z",
        "deletedAt": "2025-04-16T04:38:06.187Z",
        "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-16T04:38:06.187Z"
        },
        "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
all ofoptional
get
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-04-16T04:38:06.187Z",
            "updatedAt": "2025-04-16T04:38:06.187Z",
            "deletedAt": "2025-04-16T04:38:06.187Z",
            "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-16T04:38:06.187Z"
            },
            "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
objectoptional
post
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"
}
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-04-16T04:38:06.187Z",
        "updatedAt": "2025-04-16T04:38:06.187Z",
        "deletedAt": "2025-04-16T04:38:06.187Z",
        "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-16T04:38:06.187Z"
        },
        "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 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
delete
DELETE /v1/orgs/{organizationId}/sites/{siteId}/sections/{siteSectionId} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
205

Site section has been deleted

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.

iconone ofoptional

Name of the icon

descriptionone ofoptional

Description of the site section

Responses
application/json
objectoptional
patch
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-04-16T04:38:06.187Z",
        "updatedAt": "2025-04-16T04:38:06.187Z",
        "deletedAt": "2025-04-16T04:38:06.187Z",
        "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-16T04:38:06.187Z"
        },
        "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
objectoptional
post
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-04-16T04:38:06.187Z",
        "updatedAt": "2025-04-16T04:38:06.187Z",
        "deletedAt": "2025-04-16T04:38:06.187Z",
        "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-16T04:38:06.187Z"
        },
        "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"
}

Was this helpful?