Add an external link to a site's navigation

Creates an external navigation link at the site root or in a section group. On a site with root variants and no sections, creating the first external link enables sections and moves those variants into a default section. Links cannot be placed inside a section. The destination must be an absolute HTTP or HTTPS URL. Draft links and links whose adaptive condition does not match are omitted from published structure responses. Use the generic structure sort operation after creation to change sibling order.

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: 2 · max: 128Required

Title of the site section

descriptionstring · max: 256 · nullableOptional

Description of the site section

iconstring · icon · max: 50 · nullableOptional

Name of the icon

Example: gear

urlstring · uri · max: 2048Required

Absolute HTTP or HTTPS destination URL

parentstringOptional

ID of the section group to create the link in. Omit to place it at the site root.

draftbooleanOptional

Whether the external link should be created in draft mode

conditionstring · max: 1024 · nullableOptional

Adaptive condition controlling whether visitors see the link

Responses

201

External link added to the site

application/json

400

The parent group is invalid, or the site has no sections or root variants

application/json

default

Unexpected Error

application/json

post/orgs/{organizationId}/sites/{siteId}/external-links

POST /v1/orgs/{organizationId}/sites/{siteId}/external-links HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 237

{
  "title": "text",
  "localizedTitle": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "description": "text",
  "localizedDescription": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "icon": "gear",
  "url": "https://example.com",
  "parent": "text",
  "draft": true,
  "condition": "text"
}

{
  "object": "site-external-link",
  "id": "text",
  "title": "text",
  "localizedTitle": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "description": "text",
  "localizedDescription": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "icon": "gear",
  "url": "https://example.com",
  "sectionGroup": "text",
  "draft": true,
  "condition": "text"
}