Create a URL redirect rule for a site

Creates a new redirect rule mapping a source path to a destination URL or content reference. Creating a live redirect also resolves open broken-link findings for the same source path. Use the bulk upsert endpoint instead when creating many redirects at once.

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

siteFindingIdstringOptional

The broken-link finding that prompted this redirect. Must belong to this site. Used to attribute redirect creation, including drafts, to the finding.

sourcestring · max: 512Required

The source path to redirect from.

Pattern: ^\/(?!\*)(?!.*\*.+)(?:[A-Za-z0-9\-._~+]|%[0-9A-Fa-f]{2})+(?:\/(?:[A-Za-z0-9\-._~+]|%[0-9A-Fa-f]{2})+)*(?:\/\*|\*)?$

captureWildcardbooleanOptional

Capture and append the wildcard-matched suffix to the destination URL.

Default: false

draftbooleanOptional

Whether the redirect is draft and not live.

Default: false

permanentbooleanOptional

Whether the redirect is permanent for public live traffic.

Default: false

destinationone ofRequired

or

or

or

or

Responses

201

The redirect was created successfully.

application/json

objectstring · enumRequiredPossible values:

idstringRequired

The unique identifier for the redirect.

sourcestring · max: 512Required

The source path to redirect from.

Pattern: ^\/(?!\*)(?!.*\*.+)(?:[A-Za-z0-9\-._~+]|%[0-9A-Fa-f]{2})+(?:\/(?:[A-Za-z0-9\-._~+]|%[0-9A-Fa-f]{2})+)*(?:\/\*|\*)?$

draftbooleanRequired

Whether the redirect is draft and not live.

captureWildcardbooleanRequired

Capture and append the wildcard-matched suffix to the destination URL.

permanentbooleanRequired

Whether the redirect is configured as permanent. Permanent redirects are served as HTTP 308 for public live traffic and HTTP 307 in non-public contexts.

destinationone ofRequired

or

or

or

createdAtstring · date-timeRequired

When the redirect was created.

updatedAtstring · date-timeOptional

When the redirect was last updated. Absent if never updated since creation.

post/orgs/{organizationId}/sites/{siteId}/redirects

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

{
  "siteFindingId": "text",
  "source": "text",
  "captureWildcard": false,
  "draft": false,
  "permanent": false,
  "destination": {
    "kind": "site-section",
    "siteSectionId": "text"
  }
}

201

The redirect was created successfully.

{
  "object": "site-redirect",
  "id": "text",
  "source": "text",
  "draft": true,
  "captureWildcard": true,
  "permanent": true,
  "destination": {
    "kind": "site-section",
    "siteSectionId": "text"
  },
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}