Hostnames and certificates

A zone serves on its default hostname and on any you add. Five calls manage the hostnames and three more the certificate on one of them; the hostname object says whether SSL is on, whether HTTP is redirected, and which certificate is in place.

The hostname object

Field	Type	Meaning
ID	Integer	The hostname id, used in the paths below
HOSTNAME	String	The name, lower case
STATUS	String	`ACTIVE` or `DISABLED`. The default hostname can be disabled if the zone has at least one custom hostname; custom hostnames are always ACTIVE
ENABLED	Integer	1 when active (serving traffic), 0 when disabled
SSL_ENABLED	Integer	1 when the name is served over HTTPS. The default hostname is created with it on and it cannot be switched off there
FORCE_SSL	Integer	1 when HTTP is redirected to HTTPS with a 301 and a Strict-Transport-Security header
DEFAULT	Integer	1 for the zone's default hostname, `{ZONE_NAME}.zone.cg-cdn.com`
SSL_CERTIFICATE	String	`LETSENCRYPT` or `CUSTOM`. LETSENCRYPT with CERTIFICATE_EXPIRES 0 means no certificate has been issued yet
CERTIFICATE_EXPIRES	Integer	When the certificate in place expires, Unix seconds; 0 when there is none
TIMESTAMP	Integer	When the hostname was added

List hostnames

GET https://api.cachegenie.com/v1/cdn/{ZONE_ID}/hostnames

Every hostname on the zone as DATA.CDN_HOSTNAMES, oldest first, with MESSAGE Data returned for all CDN Hostnames for this CDN Zone.

{
  "CODE": 200,
  "MESSAGE": "Data returned for all CDN Hostnames for this CDN Zone.",
  "DATA": {
    "CDN_HOSTNAMES": [
      {
        "ID": 4021,
        "HOSTNAME": "video.zone.cg-cdn.com",
        "STATUS": "ACTIVE",
        "ENABLED": 1,
        "SSL_ENABLED": 1,
        "FORCE_SSL": 0,
        "DEFAULT": 1,
        "SSL_CERTIFICATE": "LETSENCRYPT",
        "CERTIFICATE_EXPIRES": 1796976000,
        "TIMESTAMP": 1789200000
      },
      {
        "ID": 4022,
        "HOSTNAME": "cdn.example.com",
        "SSL_ENABLED": 1,
        "FORCE_SSL": 1,
        "DEFAULT": 0,
        "SSL_CERTIFICATE": "LETSENCRYPT",
        "CERTIFICATE_EXPIRES": 1797062400,
        "TIMESTAMP": 1789203600
      }
    ]
  }
}

Add a hostname

POST https://api.cachegenie.com/v1/cdn/{ZONE_ID}/hostnames

HOSTNAME (String, required): a subdomain of at least three labels (or four for two-part ccTLDs such as .co.uk), letters, digits and hyphens, up to 253 characters. Must be a subdomain (e.g. cdn.example.com or www.example.com); root and apex domains (e.g. example.com) are not permitted because CNAME flattening bypasses Latency Based Routing (GeoDNS). No wildcard, no port, no IP address, no name containing cachegenie.com or cg-cdn.com, and not a name already on any zone.

curl -X POST https://api.cachegenie.com/v1/cdn/AB12CD34E/hostnames \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"HOSTNAME": "cdn.example.com"}'

The answer is the new hostname object with MESSAGE CDN Hostname Created.. It is created with SSL off, so that the DNS can be pointed at the zone first; switch SSL on afterwards and a certificate is issued. See Hostnames and certificates. Refusals, each a 400: Missing HOSTNAME in JSON Body., Invalid CDN Hostname., Apex and root domains cannot be used as CDN hostnames because CNAME flattening and ALIAS records bypass Latency Based Routing (GeoDNS). Use a subdomain such as www.{HOSTNAME} or cdn.{HOSTNAME} instead. See https://docs.cachegenie.com/zones/hostnames-and-certificates#root-and-apex-domains for details., This CDN Hostname already exists, please try again.; a write that did not go through is 500 Unable to create CDN Hostname - Internal Server Error, please try again.

View a hostname

GET https://api.cachegenie.com/v1/cdn/{ZONE_ID}/hostnames/{HOSTNAME_ID}

One hostname object, MESSAGE CDN Hostname Data Returned.. A hostname that is not on this zone answers 404 CDN Hostname not found.

Update a hostname

POST https://api.cachegenie.com/v1/cdn/{ZONE_ID}/hostnames/{HOSTNAME_ID}

STATUS (String, optional): ACTIVE or DISABLED. Only the default hostname can be disabled, and only when at least one custom hostname exists on the zone. Disabling stops the default hostname from serving CDN traffic while preserving it as a CNAME target.
ENABLED (Integer, optional): 1 for active, 0 for disabled. An alternative to STATUS.
SSL_ENABLED (Integer, optional): 1 for on, any other value for off; left out or null, unchanged. The default hostname's SSL cannot be switched off; a request to do so is ignored. Switching SSL off switches FORCE_SSL off with it.
FORCE_SSL (Integer, optional): 1 for on, any other value for off; left out or null, unchanged. On needs SSL on and a certificate that has not expired.

curl -X POST https://api.cachegenie.com/v1/cdn/AB12CD34E/hostnames/4022 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"SSL_ENABLED": 1, "FORCE_SSL": 1}'

The answer is the updated object with MESSAGE CDN Hostname Updated.. Asking for Force SSL before a certificate exists is 400 FORCE_SSL needs SSL_ENABLED and a certificate for the hostname (Let's Encrypt once issued, or an uploaded one); see SSL_CERTIFICATE and CERTIFICATE_EXPIRES on the hostname.: switch SSL on, wait for CERTIFICATE_EXPIRES to show a date in the future, then send FORCE_SSL. Refusals for status updates include 400 STATUS must be either ACTIVE or DISABLED., Only the default hostname can be disabled., and The default hostname can only be disabled if at least one custom hostname exists on this zone.

Delete a hostname

DELETE https://api.cachegenie.com/v1/cdn/{ZONE_ID}/hostnames/{HOSTNAME_ID}

Removes the hostname and every certificate it had, at once. MESSAGE CDN Hostname Deleted. with an empty DATA. The default hostname cannot be deleted: 400 Unable to delete the Default CDN Hostname. While the default hostname is disabled, if only one custom hostname remains on the zone, that custom hostname cannot be deleted until the default hostname is re-enabled: 400 Cannot delete the only custom hostname while the default hostname is disabled. Re-enable the default hostname first.

View the certificate

GET https://api.cachegenie.com/v1/cdn/{ZONE_ID}/hostnames/{HOSTNAME_ID}/certificate

MESSAGE CDN Hostname Certificate Returned. and four fields: TYPE (LETSENCRYPT or CUSTOM), ISSUER (the issuer's name; Let's Encrypt for ours), EXPIRES (Unix seconds, 0 when none is in place yet) and UPLOADED (when a custom certificate was uploaded, 0 for Let's Encrypt).

Upload your own certificate

POST https://api.cachegenie.com/v1/cdn/{ZONE_ID}/hostnames/{HOSTNAME_ID}/certificate

CERTIFICATE (String, required): the certificate in PEM form, leaf first, intermediates after it. Up to 64 KB.
PRIVATE_KEY (String, required): the matching key in PEM form, unencrypted. RSA of 2048 bits or more, or EC on P-256, P-384 or P-521 with a named curve. Up to 16 KB.

curl -X POST \
  https://api.cachegenie.com/v1/cdn/AB12CD34E/hostnames/4022/certificate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile c fullchain.pem --rawfile k privkey.pem \
        '{CERTIFICATE: $c, PRIVATE_KEY: $k}')"

The certificate has to cover the hostname (common name or a subject alternative name; a wildcard covers one label), be unexpired and not start more than a day in the future. Saving replaces any certificate the hostname had, the Let's Encrypt one included, switches SSL on, and puts it on every location within seconds. The answer is MESSAGE CDN Hostname Certificate Saved. with the certificate object above as DATA. A write that did not go through is 500 Unable to save the certificate - Internal Server Error, please try again. Refusals, each a 400 with the same sentence the NOC's upload popup shows:

CERTIFICATE and PRIVATE_KEY (both PEM text) are required.
The default hostname always uses Let's Encrypt; own certificates are for hostnames you added.
Paste both the certificate and its private key.
The certificate or key is larger than expected. Paste the PEM text only.
The certificate must be PEM text starting with -----BEGIN CERTIFICATE-----.
The certificate could not be read. Paste the PEM certificate exactly as it was issued.
The private key is encrypted. Remove the passphrase and paste the unencrypted PEM key.
The private key could not be read. It must be an unencrypted PEM key (RSA or EC).
The private key does not belong to this certificate.
RSA keys must be 2048 bits or longer.
EC keys must use a named curve (P-256, P-384 or P-521) rather than explicit curve parameters. Export the key with named-curve parameters and try again.
Only RSA and EC keys are supported.
This certificate expired on {date}. Upload a current one.
This certificate is not valid until {date}.
This certificate is not issued for {hostname}. It covers {names}.

Remove your own certificate

DELETE https://api.cachegenie.com/v1/cdn/{ZONE_ID}/hostnames/{HOSTNAME_ID}/certificate

Deletes an uploaded certificate, switches FORCE_SSL off, and starts a Let's Encrypt issuance for the name. MESSAGE CDN Hostname Certificate Removed.. A hostname that has no uploaded certificate answers 404 This hostname has no own certificate; it uses Let's Encrypt., so a delete never silently switches Force SSL off on a Let's Encrypt hostname.

Was this helpful?