Custom Domains

A CustomDomain object represents an additional customer-owned domain that routes to a Files.com site.

List Custom Domains

Endpoint

GET/custom_domains

Return Object

CustomDomain[]

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Additional Arguments

Example Request

curl https://app.files.com/api/rest/v1/custom_domains.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

[
  {
    "id": 1,
    "domain": "files.example.com",
    "destination": "site_alias",
    "dns_status": "correct",
    "ssl_certificate_id": 1,
    "brick_managed": true,
    "folder_behavior_id": 1,
    "created_at": "2000-01-01T01:00:00Z",
    "updated_at": "2000-01-01T01:00:00Z"
  }
]

Show Custom Domain

Endpoint

GET/custom_domains/{id}

Return Object

CustomDomain

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

ParameterDescription
id
int64
Required		Custom Domain ID.

Example Request

curl https://app.files.com/api/rest/v1/custom_domains/{id}.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

{
  "id": 1,
  "domain": "files.example.com",
  "destination": "site_alias",
  "dns_status": "correct",
  "ssl_certificate_id": 1,
  "brick_managed": true,
  "folder_behavior_id": 1,
  "created_at": "2000-01-01T01:00:00Z",
  "updated_at": "2000-01-01T01:00:00Z"
}

Create Custom Domain

Endpoint

POST/custom_domains

Return Object

CustomDomain

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

ParameterDefaultDescription
destination
string		"site_alias"Where this custom domain routes. Can be site_alias, public_hosting, s3_endpoint, or unassigned (not routing traffic). Set to unassigned automatically when a bound public_hosting folder behavior is deleted, and can be set manually via the API for any reason.
Possible values: site_alias, public_hosting, s3_endpoint, unassigned
folder_behavior_id
int64		Public Hosting behavior ID when this domain routes to a specific Public Hosting behavior. Preserved as historical context when destination becomes unassigned.
ssl_certificate_id
int64		Current SSL certificate ID.
domain
string
Required		Customer-owned domain name.

Example Request

curl https://app.files.com/api/rest/v1/custom_domains.json \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"destination":"site_alias","folder_behavior_id":1,"ssl_certificate_id":1,"domain":"files.example.com"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

{
  "id": 1,
  "domain": "files.example.com",
  "destination": "site_alias",
  "dns_status": "correct",
  "ssl_certificate_id": 1,
  "brick_managed": true,
  "folder_behavior_id": 1,
  "created_at": "2000-01-01T01:00:00Z",
  "updated_at": "2000-01-01T01:00:00Z"
}

Update Custom Domain

Endpoint

PATCH/custom_domains/{id}

Return Object

CustomDomain

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

ParameterDescription
id
int64
Required		Custom Domain ID.
destination
string		Where this custom domain routes. Can be site_alias, public_hosting, s3_endpoint, or unassigned (not routing traffic). Set to unassigned automatically when a bound public_hosting folder behavior is deleted, and can be set manually via the API for any reason.
Possible values: site_alias, public_hosting, s3_endpoint, unassigned
folder_behavior_id
int64		Public Hosting behavior ID when this domain routes to a specific Public Hosting behavior. Preserved as historical context when destination becomes unassigned.
ssl_certificate_id
int64		Current SSL certificate ID.
domain
string		Customer-owned domain name.

Example Request

curl https://app.files.com/api/rest/v1/custom_domains/{id}.json \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -d '{"destination":"site_alias","folder_behavior_id":1,"ssl_certificate_id":1,"domain":"files.example.com"}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

{
  "id": 1,
  "domain": "files.example.com",
  "destination": "site_alias",
  "dns_status": "correct",
  "ssl_certificate_id": 1,
  "brick_managed": true,
  "folder_behavior_id": 1,
  "created_at": "2000-01-01T01:00:00Z",
  "updated_at": "2000-01-01T01:00:00Z"
}

Delete Custom Domain

Endpoint

DELETE/custom_domains/{id}

Return Object

No return value.

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Site Admin permissions.

Request Parameters

ParameterDescription
id
int64
Required		Custom Domain ID.

Example Request

curl https://app.files.com/api/rest/v1/custom_domains/{id}.json \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

The CustomDomain Object

Some of the endpoints above return a CustomDomain object. The attributes of this object are listed below.

AttributeDescription
id
int64		Custom Domain ID.
domain
string		Customer-owned domain name.
destination
string		Where this custom domain routes. Can be site_alias, public_hosting, s3_endpoint, or unassigned (not routing traffic). Set to unassigned automatically when a bound public_hosting folder behavior is deleted, and can be set manually via the API for any reason.
Possible values: site_alias, public_hosting, s3_endpoint, unassigned
dns_status
string		Current DNS verification status.
Possible values: disabled, correct, no_records, cname_wrong, a_record, caa_conflict
ssl_certificate_id
int64		Current SSL certificate ID.
brick_managed
boolean		Is this domain's SSL certificate automatically managed and renewed by Files.com?
folder_behavior_id
int64		Public Hosting behavior ID when this domain routes to a specific Public Hosting behavior. Preserved as historical context when destination becomes unassigned.
created_at
date-time		When this Custom Domain was created.
updated_at
date-time		When this Custom Domain was last updated.

Example CustomDomain Object

{
  "id": 1,
  "domain": "files.example.com",
  "destination": "site_alias",
  "dns_status": "correct",
  "ssl_certificate_id": 1,
  "brick_managed": true,
  "folder_behavior_id": 1,
  "created_at": "2000-01-01T01:00:00Z",
  "updated_at": "2000-01-01T01:00:00Z"
}