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

Creates a new top-level navigation section in the site. The section appears as a tab or sidebar entry in the site navigation. Pass an existing space ID to link it as the section's primary content source, or pass null to create and link a new space. New spaces are blank unless a template is provided.

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

spaceIdstring · nullableRequired

Pass the ID of an existing space or pass null to create a new space. The space will be added to the section as a site space variant.

titlestring · min: 2 · max: 128 · nullableOptional

Section title. Also used as the space title when spaceId is null and no template is provided.

iconstring · icon · max: 50 · nullableOptional

Name of the icon

Example: gear

draftbooleanOptional

Whether the section should be created in draft mode. Defaults to false. Editors can set this to true to create draft content after sections are enabled. Creating live content requires Creator permission; enabling sections requires Admin permission.

Default: false

pageIdstringOptional

Custom home page within an existing space, rendered at the section's path root instead of the space's default landing page. Providing it when spaceId is null returns a 400 error.

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

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

{
  "spaceId": "text",
  "template": {
    "id": "text",
    "params": {
      "contentRefs": {
        "ANY_ADDITIONAL_PROPERTY": {
          "kind": "file",
          "file": "text",
          "space": "text"
        }
      }
    }
  },
  "title": "text",
  "icon": "gear",
  "draft": false,
  "pageId": "text",
  "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-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",
          "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"
        },
        "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"
}