Add a new navigation section to a site backed by a space

Creates a new top-level navigation section in the site by linking a space as its primary content source. The section appears as a tab or sidebar entry in the site navigation.

Available in MCP

post

Authorizations

useroauth

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

application/json

spaceIdstringRequired

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

titlestring · min: 2 · max: 128 · nullableOptional

Title of the site section

iconstring · icon · max: 50 · nullableOptional

Name of the icon

Example: gear

draftbooleanOptional

Whether the section should be created in draft mode.

siteSectionGroupIdstringOptional

ID of the section group to create the section in

Responses

201

Section added to the site

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

{
  "spaceId": "text",
  "title": "text",
  "icon": "gear",
  "draft": true,
  "siteSectionGroupId": "text"
}

201

Section added to the site

{
  "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-07-21T22:35:43.338Z",
        "updatedAt": "2026-07-21T22:35:43.338Z",
        "deletedAt": "2026-07-21T22:35:43.338Z",
        "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",
          "url": "text",
          "operation": {
            "state": "running"
          },
          "updatedAt": "2026-07-21T22:35:43.338Z"
        },
        "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",
      "draft": true,
      "hasAdvancedCustomizationFeature": true,
      "urls": {
        "published": "https://example.com"
      },
      "hidden": true
    }
  ],
  "urls": {
    "published": "https://example.com"
  },
  "icon": "gear"
}