Custom hostnames

Serve your GitBook content from fully branded, custom hostnames.

Extend your brand identity by mapping personalized domain names to your docs. This can help unify your documentation site with your existing company properties.

The CustomHostname object

Attributes

objectstring · enumrequiredAvailable options:

hostnamestring · max: 512required

Custom hostname for the site, for e.g. docs.mycompany.com

Pattern: ^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?[.]){2,}[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$

targetone ofrequired

isActivebooleanrequired

statusone ofoptional

urlsobjectrequired

URLs associated with the object

The CustomHostname object

{
  "object": "custom-hostname",
  "hostname": "text",
  "target": {
    "type": "organization",
    "organization": "text"
  },
  "isActive": true,
  "status": "text",
  "urls": {
    "location": "https://example.com"
  }
}

Get a custom hostname

get

Authorizations

Path parameters

hostnamestringrequired

The custom hostname, for example "docs.gitbook.com"

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.gitbook.com/v1/custom-hostnames/{hostname}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

200

{
  "object": "custom-hostname",
  "hostname": "text",
  "target": {
    "type": "organization",
    "organization": "text"
  },
  "isActive": true,
  "status": "text",
  "urls": {
    "location": "https://example.com"
  }
}

OK

Remove a custom hostname

delete

The custom hostname will continue to point to the content or organization unless it is used for another one.

Authorizations

Path parameters

hostnamestringrequired

The custom hostname, for example "docs.gitbook.com"

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url 'https://api.gitbook.com/v1/custom-hostnames/{hostname}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

205

205

No Content

Custom hostname has been removed

Revalidate a custom hostname DNS

patch

Revalidate DNS records and status.

Authorizations

Path parameters

hostnamestringrequired

The custom hostname, for example "docs.gitbook.com"

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PATCH \
  --url 'https://api.gitbook.com/v1/custom-hostnames/{hostname}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

204

400

409

204

No Content

DNS validation has been retriggered