Add a section group to a site's navigation structure

Creates a new section group to organize multiple sections under a shared navigation label. Section groups can be nested by providing a parent group ID. Existing sections can be assigned to the group at creation time via their IDs. Create the group in draft mode to stage it before publishing.

Available in MCP

post

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

organizationIdstringRequired

A unique entity identifier

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

siteIdstringRequired

The unique id of the site

Body

titlestring · min: 1 · max: 100Required

Title of the site section group

conditionstring · max: 1024Optional

Conditional expression used to evaluate whether the site section group should be shown to the site's visitor (should evaluate to a boolean).

iconstring · icon · max: 50 · nullableOptional

Name of the icon

Example: gear

sectionsstring[]Optional

IDs of the sections to be added to the section group

parentstringOptional

ID of the parent section group to nest this group under. If not provided, the section group will be added at the root of the site.

draftbooleanOptional

Whether the section group should be created in draft mode.

Responses

201

Section group added to the site

application/json

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

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

{
  "title": "text",
  "condition": "text",
  "icon": "gear",
  "sections": [
    "text"
  ],
  "parent": "text",
  "draft": true
}

201

Section group added to the site

{
  "object": "site-section-group",
  "id": "text",
  "title": "text",
  "localizedTitle": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "condition": "text",
  "sectionGroup": "text",
  "draft": true,
  "children": [
    {
      "object": "site-section",
      "id": "text",
      "title": "text",
      "localizedTitle": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "description": "text",
      "localizedDescription": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "default": true,
      "draft": 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-01T00:00:00.000Z",
            "updatedAt": "2026-01-01T00:00:00.000Z",
            "deletedAt": "2026-01-01T00:00:00.000Z",
            "editMode": "live",
            "type": "styleguide",
            "mergeRules": {
              "type": "inherit"
            },
            "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",
              "installationStatus": "unauthenticated",
              "installationProvider": "github",
              "installationId": "text",
              "parentInstallationId": "text",
              "url": "text",
              "installationProjectDirectory": "text",
              "operation": {
                "state": "running",
                "direction": "export",
                "startedAt": "2026-01-01T00:00:00.000Z",
                "endedAt": "2026-01-01T00:00:00.000Z",
                "error": "text",
                "errorAction": {
                  "label": "text",
                  "url": "https://example.com"
                }
              },
              "operationTimeout": 1,
              "updatedAt": "2026-01-01T00:00:00.000Z"
            },
            "previousGitSync": {
              "url": "text"
            },
            "imports": [
              {
                "object": "import-run",
                "id": "text",
                "startedAt": "2026-01-01T00:00:00.000Z",
                "completedAt": "2026-01-01T00:00:00.000Z",
                "createdAt": "2026-01-01T00:00:00.000Z",
                "updatedAt": "2026-01-01T00:00:00.000Z",
                "status": "pending",
                "reason": "text",
                "source": {
                  "type": "website",
                  "url": "https://example.com"
                },
                "target": {
                  "space": "text",
                  "changeRequest": "text",
                  "page": "text"
                },
                "site": "text",
                "createdBy": "text",
                "urls": {
                  "location": "https://example.com"
                },
                "pages": [
                  {
                    "id": "text",
                    "sourceURL": "text",
                    "type": "page",
                    "status": "complete"
                  }
                ]
              }
            ],
            "visitorAuth": {
              "backend": "custom"
            },
            "revision": "text",
            "defaultLevel": "admin",
            "comments": 1,
            "changeRequests": 1,
            "changeRequestsOpen": 1,
            "changeRequestsDraft": 1,
            "internal_poweredByV2": true,
            "internal_singleWebsocket": true,
            "permissions": {
              "view": true,
              "access": true,
              "admin": true,
              "viewInviteLinks": true,
              "edit": true,
              "triggerGitSync": true,
              "comment": true,
              "merge": true,
              "review": true,
              "installIntegration": true
            }
          },
          "title": "text",
          "localizedTitle": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "default": true,
          "condition": "text",
          "pageId": "text",
          "draft": true,
          "hasAdvancedCustomizationFeature": true,
          "urls": {
            "published": "https://example.com"
          },
          "hidden": true
        }
      ],
      "urls": {
        "published": "https://example.com"
      },
      "icon": "gear"
    }
  ],
  "icon": "gear",
  "subscriptionNotice": {
    "type": "trial_started",
    "context": "trial_started",
    "commercialStatus": "trial",
    "message": "text",
    "trial": {
      "status": "notapplicable",
      "endDate": "2026-01-01T00:00:00.000Z",
      "daysRemaining": 1
    },
    "canManageBilling": true,
    "upgradeUrl": "https://example.com",
    "pricingUrl": "https://example.com"
  }
}