URLs

Configure where and how your GitBook content can be accessed.

Manage official endpoints, direct deep links, or short links for your content. This allows you to keep track of multiple custom URLs or vanity links under one system.

Resolve a URL to a content (space, collection, page)

get

Authorizations

user

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

urlstringRequired

URL to resolve

Responses

200

OK

application/json

Responseone of

or

get

/urls/content

HTTPcURLJavaScriptPython

GET /v1/urls/content?url=text HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "collection": {
    "object": "collection",
    "id": "text",
    "title": "text",
    "description": "text",
    "organization": "text",
    "parent": "text",
    "defaultLevel": "admin",
    "urls": {
      "location": "https://example.com",
      "app": "https://example.com"
    },
    "permissions": {
      "view": true,
      "admin": true,
      "viewInviteLinks": true,
      "create": true
    }
  }
}

Resolve a URL to an embed

get

Authorizations

useruser-internaluser-staffuser-internal-or-staffintegrationintegration-installation

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

urlstringRequired

URL to resolve

Responses

200

OK

application/json

Responseall of

and

anyOptional

or

or

get

/urls/embed

HTTPcURLJavaScriptPython

GET /v1/urls/embed?url=text HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "title": "text",
  "site": "text",
  "icon": "text",
  "type": "link"
}

Deprecated

Resolve a URL of a published content.

get

Authorizations

useruser-internaluser-staffuser-internal-or-staffintegrationintegration-installation

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

urlstring · uri · max: 2048Required

URL to resolve

visitorAuthTokenstringOptional

JWT token generated for a authenticated access session

redirectOnErrorbooleanOptional

When true redirects the user to the authentication/fallback URL if the access token is invalid

Default: false

Responses

200

OK

application/json

Responseone of

or

404

No content found for the URL.

application/json

get

/urls/published

HTTPcURLJavaScriptPython

GET /v1/urls/published?url=https%3A%2F%2Fexample.com HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "target": "application",
  "redirect": "https://example.com"
}

Resolve a URL of a published content.

post

Authorizations

useruser-internaluser-staffuser-internal-or-staffintegrationintegration-installation

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

urlstring · uri · max: 2048Required

URL to resolve

redirectOnErrorbooleanOptional

When true redirects the user to the authentication/fallback URL if the access token is invalid

Default: false

Responses

200

OK

application/json

Responseone of

or

404

No content found for the URL.

application/json

post

/urls/published

HTTPcURLJavaScriptPython

POST /v1/urls/published HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 179

{
  "url": "https://example.com",
  "redirectOnError": false,
  "visitor": {
    "jwtToken": "text",
    "unsignedClaims": {
      "ANY_ADDITIONAL_PROPERTY": {
        "ANY_ADDITIONAL_PROPERTY": "[Circular Reference]"
      }
    }
  }
}

{
  "target": "application",
  "redirect": "https://example.com"
}