Update an external link in a site's navigation

Updates an external navigation link. Set parent to a section group ID to move the link into that group, or null to move it to the site root; links cannot be placed inside a section. A changed destination must remain an absolute HTTP or HTTPS URL. Draft and adaptive-condition fields control visibility. Use the generic structure sort operation after changing the parent to adjust the link's sibling order.

Available in MCP

patch

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

siteExternalLinkIdstringRequired

The unique ID of the site external link

Header parameters

preferstring · enumOptional

Control whether a successful response includes the updated resource representation.

Possible values:

Body

titlestring · min: 2 · max: 128Optional

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: 2048Optional

Absolute HTTP or HTTPS destination URL

parentstring · nullableOptional

ID of the section group to move the link into. Set to null to move it to the site root.

draftbooleanOptional

Whether the external link should be kept in draft mode

conditionstring · max: 1024 · nullableOptional

Adaptive condition controlling whether visitors see the link

Responses

200

External link updated

application/json

objectstring · enumRequired

The object type, which is always "site-external-link"

Possible values:

idstringRequired

Unique identifier of the external link

titlestring · min: 2 · max: 128Required

Title of the site section

descriptionstring · max: 256Optional

Description of the site section

iconstring · icon · max: 50Optional

Name of the icon

Example: gear

urlstring · uri · max: 2048Required

Absolute HTTP or HTTPS URL opened by the external link

sectionGroupstringOptional

ID of the section group the external link belongs to. Omitted for a root link.

draftbooleanRequired

Whether the external link is draft and not live

conditionstring · max: 1024Optional

Conditional expression used to evaluate whether the external link should be shown to the site's visitor

204

External link updated without returning its representation

400

The parent group or destination URL is invalid

application/json

404

Site or external link not found

application/json

default

Unexpected Error

application/json

patch/orgs/{organizationId}/sites/{siteId}/external-links/{siteExternalLinkId}

PATCH /v1/orgs/{organizationId}/sites/{siteId}/external-links/{siteExternalLinkId} 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"
}