# 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

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"components":{"schemas":{"CustomHostname":{"type":"object","properties":{"object":{"type":"string","enum":["custom-hostname"]},"hostname":{"$ref":"#/components/schemas/SiteHostname"},"target":{"oneOf":[{"$ref":"#/components/schemas/OrganizationPointer"},{"$ref":"#/components/schemas/SitePointer"}]},"isActive":{"type":"boolean"},"status":{"$ref":"#/components/schemas/CustomHostnameStatus"},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"type":"string","description":"URL of the custom hostname in the API","format":"uri"}},"required":["location"]}},"required":["object","hostname","target","isActive","urls"]},"SiteHostname":{"type":"string","description":"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]$","maxLength":512},"OrganizationPointer":{"type":"object","properties":{"type":{"type":"string","enum":["organization"]},"organization":{"type":"string","description":"Unique identifier for the organization"}},"required":["type","organization"]},"SitePointer":{"type":"object","properties":{"type":{"type":"string","enum":["site"]},"site":{"type":"string","description":"Unique identifier for the site"}},"required":["type","site"]},"CustomHostnameStatus":{"type":"string","oneOf":[{"$ref":"#/components/schemas/CustomHostnameDnsStatus"},{"$ref":"#/components/schemas/CustomHostnameSslStatus"},{"$ref":"#/components/schemas/CustomHostnameErrorStatus"}]},"CustomHostnameDnsStatus":{"type":"string","enum":["dns_passed","dns_wrong_cname","dns_no_cname","dns_cloudflare_proxied","dns_wrong_caa"]},"CustomHostnameSslStatus":{"type":"string","enum":["live","ssl_unknown","ssl_pending","ssl_failed","ssl_retry_expired"]},"CustomHostnameErrorStatus":{"type":"string","enum":["invalid_domain","internal_error"]}}}}
```

## GET /custom-hostnames/{hostname}

> Get a custom hostname

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"custom-hostnames","description":"Extend your brand identity by mapping personalized domain names to your docs. This can help unify your documentation site with your existing company properties.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"CustomHostname\" grouped=\"false\" %}\n    The CustomHostname object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user-internal-or-staff":[]}],"components":{"securitySchemes":{"user-internal-or-staff":{"type":"http","scheme":"bearer"}},"parameters":{"hostname":{"name":"hostname","in":"path","required":true,"description":"The custom hostname, for example \"docs.gitbook.com\"","schema":{"type":"string"}}},"schemas":{"CustomHostname":{"type":"object","properties":{"object":{"type":"string","enum":["custom-hostname"]},"hostname":{"$ref":"#/components/schemas/SiteHostname"},"target":{"oneOf":[{"$ref":"#/components/schemas/OrganizationPointer"},{"$ref":"#/components/schemas/SitePointer"}]},"isActive":{"type":"boolean"},"status":{"$ref":"#/components/schemas/CustomHostnameStatus"},"urls":{"type":"object","description":"URLs associated with the object","properties":{"location":{"type":"string","description":"URL of the custom hostname in the API","format":"uri"}},"required":["location"]}},"required":["object","hostname","target","isActive","urls"]},"SiteHostname":{"type":"string","description":"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]$","maxLength":512},"OrganizationPointer":{"type":"object","properties":{"type":{"type":"string","enum":["organization"]},"organization":{"type":"string","description":"Unique identifier for the organization"}},"required":["type","organization"]},"SitePointer":{"type":"object","properties":{"type":{"type":"string","enum":["site"]},"site":{"type":"string","description":"Unique identifier for the site"}},"required":["type","site"]},"CustomHostnameStatus":{"type":"string","oneOf":[{"$ref":"#/components/schemas/CustomHostnameDnsStatus"},{"$ref":"#/components/schemas/CustomHostnameSslStatus"},{"$ref":"#/components/schemas/CustomHostnameErrorStatus"}]},"CustomHostnameDnsStatus":{"type":"string","enum":["dns_passed","dns_wrong_cname","dns_no_cname","dns_cloudflare_proxied","dns_wrong_caa"]},"CustomHostnameSslStatus":{"type":"string","enum":["live","ssl_unknown","ssl_pending","ssl_failed","ssl_retry_expired"]},"CustomHostnameErrorStatus":{"type":"string","enum":["invalid_domain","internal_error"]}}},"paths":{"/custom-hostnames/{hostname}":{"get":{"operationId":"getCustomHostname","summary":"Get a custom hostname","tags":["custom-hostnames"],"parameters":[{"$ref":"#/components/parameters/hostname"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomHostname"}}}}}}}}}
```

## Remove a custom hostname

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

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"custom-hostnames","description":"Extend your brand identity by mapping personalized domain names to your docs. This can help unify your documentation site with your existing company properties.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"CustomHostname\" grouped=\"false\" %}\n    The CustomHostname object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user-internal":[]}],"components":{"securitySchemes":{"user-internal":{"type":"http","scheme":"bearer"}},"parameters":{"hostname":{"name":"hostname","in":"path","required":true,"description":"The custom hostname, for example \"docs.gitbook.com\"","schema":{"type":"string"}}}},"paths":{"/custom-hostnames/{hostname}":{"delete":{"operationId":"removeCustomHostname","summary":"Remove a custom hostname","description":"The custom hostname will continue to point to the content or organization unless it is used for another one.","tags":["custom-hostnames"],"parameters":[{"$ref":"#/components/parameters/hostname"}],"responses":{"204":{"description":"Custom hostname did not exist"},"205":{"description":"Custom hostname has been removed"}}}}}}
```

## Revalidate a custom hostname DNS

> Revalidate DNS records and status.

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[{"name":"custom-hostnames","description":"Extend your brand identity by mapping personalized domain names to your docs. This can help unify your documentation site with your existing company properties.\n\n{% openapi-schemas spec=\"gitbook\" schemas=\"CustomHostname\" grouped=\"false\" %}\n    The CustomHostname object\n{% endopenapi-schemas %}\n"}],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user-internal":[]}],"components":{"securitySchemes":{"user-internal":{"type":"http","scheme":"bearer"}},"parameters":{"hostname":{"name":"hostname","in":"path","required":true,"description":"The custom hostname, for example \"docs.gitbook.com\"","schema":{"type":"string"}}},"responses":{"ConflictError":{"description":"Conflict","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[409]},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"paths":{"/custom-hostnames/{hostname}":{"patch":{"operationId":"dnsRevalidateCustomHostname","summary":"Revalidate a custom hostname DNS","description":"Revalidate DNS records and status.","tags":["custom-hostnames"],"parameters":[{"$ref":"#/components/parameters/hostname"}],"responses":{"204":{"description":"DNS validation has been retriggered"},"400":{"description":"The current custom hostname is inactive and cannot be revalidated","$ref":"#/components/responses/ConflictError"},"409":{"description":"The current custom hostname status does not allow DNS revalidation","$ref":"#/components/responses/ConflictError"}}}}}}
```