Custom Hostnames

Get the details about a custom hostname.

get

Authorizations

user-internal

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

default

Unexpected Error

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: */*

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

Setup a custom hostname on a site or an organization. Any previously set custom hostname will continue pointing to the target but marked as available for use with another target.

post

Authorizations

user-internal

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

hostnamestringRequired

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

Body

application/json

targetone ofRequired

or

Responses

201

Custom hostname created

application/json

400

Selected custom hostname target does not exist

application/json

409

Custom hostname is already in use on the target

application/json

default

Unexpected Error

application/json

post

/custom-hostnames/{hostname}

HTTPcURLJavaScriptPython

POST /v1/custom-hostnames/{hostname} HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 56

{
  "target": {
    "type": "organization",
    "organization": "text"
  }
}

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

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

delete

Authorizations

user-internal

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

hostnamestringRequired

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

Responses

205

Custom hostname has been removed

default

Unexpected Error

application/json

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's DNS records and status.

patch

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

default

Unexpected Error

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

Test if a custom hostname can be used for a site or organization.

post

Authorizations

user-internal

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

hostnamestringRequired

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

Body

application/json

targetone ofRequired

or

Responses

204

The custom hostname is available and valid.

400

The custom hostname is invalid.

application/json

409

The custom hostname is already configured for this target or a different one.

application/json

default

Unexpected Error

application/json

post

/custom-hostnames/{hostname}/test

HTTPcURLJavaScriptPython

POST /v1/custom-hostnames/{hostname}/test HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 56

{
  "target": {
    "type": "organization",
    "organization": "text"
  }
}

No content