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 · enumRequiredPossible values:

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

or

isActivebooleanRequired

statusone ofOptional

string · enumOptionalPossible values:

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

user-internal-or-staff

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

hostnamestringRequired

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

Responses

200

OK

application/json

get

/custom-hostnames/{hostname}

HTTPcURLJavaScriptPython

GET /v1/custom-hostnames/{hostname} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

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

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

user-internal

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

hostnamestringRequired

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

Responses

204

Custom hostname did not exist

205

Custom hostname has been removed

delete

/custom-hostnames/{hostname}

HTTPcURLJavaScriptPython

DELETE /v1/custom-hostnames/{hostname} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Revalidate a custom hostname DNS

patch

Revalidate DNS records and status.

Authorizations

user-internal

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

hostnamestringRequired

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

Responses

204

DNS validation has been retriggered

400

The current custom hostname is inactive and cannot be revalidated

application/json

409

The current custom hostname status does not allow DNS revalidation

application/json

patch

/custom-hostnames/{hostname}

HTTPcURLJavaScriptPython

PATCH /v1/custom-hostnames/{hostname} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content