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

Query parameters

urlstringrequired

URL to resolve

Responses

application/json

one ofoptional

URL resolved to a collection

URL resolved to the content of a space

get

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

200

{
  "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

Query parameters

urlstringrequired

URL to resolve

Responses

application/json

all ofoptional

get

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

200

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

Deprecated

Resolve a URL of a published content.

get

Authorizations

Query parameters

urlstring · uri · max: 2048required

URL to resolve

visitorAuthTokenstringoptional

JWT token generated for a visitor auth session

redirectOnErrorbooleanoptional

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

Default: false

Responses

application/json

one ofoptional

application/json

get

GET /v1/urls/published 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

Body

urlstring · uri · max: 2048required

URL to resolve

redirectOnErrorbooleanoptional

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

Default: false

visitorobjectoptional

An object that describes the payload of site visitor info. It can include a jwt token with signed claims and/or a record of its unsigned claims.

Responses

application/json

one ofoptional

application/json

post

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

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

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

Was this helpful?