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 start with a blank page unless a template is provided or empty is true, which creates the space with no page at all (use it when you are about to add the pages yourself).

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.

emptybooleanOptional

Create the new space without any content, not even a blank page. Useful when the content is about to be populated, for example by an import. Only valid when spaceId is null and no template is provided.

Default: false

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

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