Automatically get a free SSL certificate with our Let's Encrypt integration.

API Documentation RESTful

Overview

The KeyCDN API allows you to manage your zones, zonealiases, zonereferrers or generate reports. This documentation provides you the required information to successfully make use of the API. The KeyCDN API is organized around REST.

Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, such as HTTP authentication and HTTP terminology, which can be understood by off-the-shelf HTTP clients.

JSON will be returned in all responses from the API, including errors.

Support

  • Check our API Libraries on GitHub. They allow you a quick and simple integration into your current solution.
  • Please contact us directly if you got any questions: Support
  • Please submit a request for enhancement (RFE) if you need more functionality.

Changelog

  • 2016-07-22 Changed Edit Zone to not require name field anymore.
  • 2016-03-05 Added Let's Encrypt support to the API.
  • 2015-11-20 Changed the API base URL to api.keycdn.com.
  • 2015-09-22 Purge simplification.
  • 2015-02-17 Change API Key Authentication.
  • 2015-01-26 Added Origin Shield feature.
  • 2014-09-10 Added Force SSL feature.
  • 2014-08-25 Including Zones, Zonealiases and Zonereferrers into the API.
  • 2014-08-10 Introduction of rate limiting.
  • 2014-07-29 Including reporting into the API.
  • 2013-10-10 Added Purge URL feature.
  • 2013-08-01 Released Beta Version of the KeyCDN API.

Authentication

You authenticate to the KeyCDN API by providing your API key in the request. Keep your credentials secret. Authentication to the API occurs via HTTP Basic Auth.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

CURL uses the -u flag to pass basic auth credentials (adding a colon after your API key will prevent it from asking you for a password).

Errors

KeyCDN uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing or invalid, etc.), and codes in the 5xx range indicate an error with KeyCDN's servers.

Not all errors map cleanly onto HTTP response codes.

HTTP Status Code Summary

200 OK - Everything worked as expected.

400 Bad Request - Often missing a required parameter.

401 Unauthorized - No valid credentials provided.

403 Forbidden - Rate limit exceeded or access denied.

404 Not Found - The requested item doesn't exist.

500, 502, 503, 504 Server errors - something went wrong on KeyCDN's end.

Response Parameters

Parameter Description
status Status code of the current API call (e.g. success or error).
description Description of an API call.
data The response data of the API call.

Example Response

{
    "status": "success",
    "description": "Data successfully received.",
    "data": {
	...
    }
}

Rate Limiting

API request will be rate limited at 20 queries per 60 seconds window for the time being. Ensure that you inspect these HTTP headers, as they provide pertinent data on where your utilization is at for the given rate limit.

X-Rate-Limit-Limit: the rate limit ceiling for that given request
X-Rate-Limit-Remaining: the number of requests left for the 60 seconds window

The KeyCDN API will return an HTTP 403 “Too Many Requests” response code when you exceed the rate limit.

Zones API /zones

Parameter Description

id
Zone ID
name
Zone Name
status
default is active
Zone Status: active or inactive
type
default is push
Zone Type: push or pull
forcedownload
default is disabled
Forces files to download instead of opening (Content-Disposition header).
cors
default is disabled
Enable cross-origin resource sharing (CORS). This will set the header to: Access-Control-Allow-Origin "*"
gzip
default is disabled
Enables or disables GZip compression.
expire
default is 0

Adding or modifying the Expires and Cache-Control response header fields that are sent to the client if the response code equals 200, 201, 204, 206, 301, 302, 303, 304, or 307. This setting overwrites the value received from the origin in case of a pull zone. The expire value has only an impact on the web browser cache and not on the KeyCDN cache.

-1
Cache-Control: no-cache
0
Push Zone: disabled
Pull Zone: as received from the origin (header honoring)
>0
Cache-Control: max-age=t, where t is the time specified in the directive in minutes converted to seconds
http2
default is disabled
This feature enables support for HTTP/2.0 in combination with SSL.
securetoken
default is disabled
Restricting access to all files within this zone by secure access tokens.
securetokenkey
Secret used to check authenticity of requested links.
sslcert
default is disabled
shared: Shared SSL enables the wildcard certificate for this zone: https://*.kxcdn.com
custom: Custom SSL is required if you want to use a Zonealias, e.g.: https://cdn.foo.com
letsencrypt: Letsencrypt SSL (beta) automatically creates a certificate for your Zonealias (limited to only one Zonealias), e.g. https://cdn.foo.com
You need to remove an exising Zonealias first before enabling the Letsencrypt option (or recreate the Zonealias afterwards).
customsslkey

Insert the private key including the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- statements.

Important: Don't forget to create the corresponding Zonealias and add the cname in your DNS. E.g. cdn.yourdomain.com
customsslcert

The required format of the SSL certificate is PEM (Base64 encoded ASCII), which is the most common format that Certificate Authorities issue certificates. Options to insert the certificate:

Cert only
-----BEGIN CERTIFICATE-----
Certificate
-----END CERTIFICATE-----
Cert incl. Intermediate Cert
-----BEGIN CERTIFICATE-----
Certificate
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Intermediate certificate
-----END CERTIFICATE-----
forcessl
default is disabled
Redirects HTTP requests to HTTPS. Returns a 301 Moved Permanently.
originurl
URL (incl. http:// or https://) of the origin server where the content is automatically pulled from. Only enter the URL of your server (e.g. http://www.foo.com). Don't enter a specific file path (e.g. http://www.foo.com/yourfile.txt).
originshield
default is disabled
Predefined shield servers, instead of our edge servers, will pull the content from your origin server if enabled. This will reduce the traffic on your origin server but adds an additional request from the edge server to the shield server if the content has not yet been cached.
cachemaxexpire
default is 1440
This specifies the maximum time for which cachable HTTP documents will be retained without checking the origin server. Applies only if NOT defined by the origin either by X-Accel-Expires, Cache-Control or Expires.
cacheignorecachecontrol
default is enabled
Disables processing of Cache-Control response header fields from the origin server (ignores X-Accel-Expires, Cache-Control and Expires). Max Expires has precedence if enabled.
cacheignorequerystring
default is enabled
The feature ignore query string tells the cache to reply with a cached reply even if the query string differs. From a caching point of view the request is treated as if having no query string when this feature is enabled.
cachestripcookies
default is disabled
Files with cookies are not cacheable but ignoring the cookies will force to cache the files.
cachexpullkey
default is KeyCDN
Specify a X-Pull request header key to have the possibility to restrict access to your origin server (X-Pull: [key]). Default if empty: X-Pull: KeyCDN
cachecanonical
default is disabled
Add a canonical header in order to improve SEO. Reference is your origin URL. E.g. Link: <http://foo.co/a/b.pdf>; rel="canonical"
cacherobots
default is disabled

Block crawlers from indexing the content in your zone.

User-agent: *
Disallow: /	
dirlist
default is disabled
Generates directory indexes automatically, similar to the Unix ls command or the Win32 dir shell command. It is recommended to disable this feature.
dirindex
default is disabled
Serving directory index files (index.html) without specifing them in the URL. A request for http://foo.com/docs/ would return http://foo.com/docs/index.html if it exists.

List Zones

Returns a list of all zones on the specified account.

Response Parameters

Returns a list of zones as defined in View Zone

$ curl "https://api.keycdn.com/zones.json" -u [apikey]:

{
    "status": "success",
    "description": "Data successfully received.",
    "data": {
        "zones": [
            {
	            "id": "1000",
	            "name": "foopull",
	            "status": "active",
	            "type": "pull",
	            "forcedownload": "disabled",
	            "cors": "disabled",
	            "gzip": "disabled",
	            "expire": "0",
	            "http2": "disabled",
	            "securetoken": "disabled",
	            "securetokenkey": null,
	            "sslcert": "disabled",
	            "customsslkey": null,
	            "customsslcert": null,
	            "forcessl": "disabled",
	            "originurl": "http://foo.com",
	            "cachemaxexpire": "1440",
	            "cacheignorecachecontrol": "enabled",
	            "cacheignorequerystring": "enabled",
	            "cachestripcookies": "disabled",
	            "cachexpullkey": "KeyCDN",
	            "cachecanonical": "disabled",
	            "cacherobots": "disabled"
            },
            {
                "id": "1001",
                "name": "foopush",
                "status": "active",
                "type": "push",
                "forcedownload": "disabled",
                "cors": "disabled",
                "gzip": "disabled",
                "expire": "0",
                "http2": "disabled",
                "securetoken": "disabled",
                "securetokenkey": "",
                "sslcert": "disabled",
                "customsslkey": "",
                "customsslcert": "",
                "forcessl": "disabled",
                "dirlist": "disabled",
                "dirindex": "disabled"
            },
            ...
        ]
    }
}

View Zone

Returns a zone specified by the {zone_id} parameter.

Response Parameters

Parameter pull push
id
name
status
type
forcedownload
cors
gzip
expire
http2
securetoken
securetokenkey
sslcert
customsslkey
customsslcert
forcessl
originurl
originshield
cachemaxexpire
cacheignorecachecontrol
cacheignorequerystring
cachestripcookies
cachexpullkey
cachecanonical
cacherobots
dirlist
dirindex

$ curl "https://api.keycdn.com/zones/{zone_id}.json" -u [apikey]:

{
    "status": "success",
    "description": "Data successfully received.",
    "data": {
        "zone": {
            "id": "1000",
            "name": "foobar",
            "status": "active",
            "type": "pull",
            "forcedownload": "disabled",
            "cors": "disabled",
            "gzip": "disabled",
            "expire": "0",
            "http2": "disabled",
            "securetoken": "disabled",
            "securetokenkey": null,
            "sslcert": "disabled",
            "customsslkey": null,
            "customsslcert": null,
            "forcessl": "disabled",
            "originurl": "http://foo.com",
            "originshield": "disabled",
            "cachemaxexpire": "1440",
            "cacheignorecachecontrol": "enabled",
            "cacheignorequerystring": "enabled",
            "cachestripcookies": "disabled",
            "cachexpullkey": "KeyCDN",
            "cachecanonical": "disabled",
            "cacherobots": "disabled"
        }
    }
}

Purge Zone Cache

Clears the entire cache for a given pull zone specified by the {zone_id} parameter.

$ curl "https://api.keycdn.com/zones/purge/{zone_id}.json" -u [apikey]:

{
    "status": "success",
    "description": "Cache has been cleared for zone examplezone."
}

Purge Zone URL

Clears the cache for specific URLs of a pull zone specified by the {zone_id} parameter.

Request Parameters

Parameter Value Description
urls array of urls (without http(s)://) Single or Bulk URL purge

By default, use the zone URL to purge assets (e.g. lorem-1.kxcdn.com).

Only use the zonealias if the cache key has been changed by KeyCDN support.

$ curl "https://api.keycdn.com/zones/purgeurl/{zone_id}.json" -u [apikey]: -X DELETE -H "Content-Type: application/json" --data '{"urls":["foo","bar"]}'

# example of JSON encoded urls variables
... --data '{"urls":["demo-1.kxcdn.com/lorem.css","demo-1.kxcdn.com/lorem.jpg"]}'

// requires the PHP Library for the KeyCDN API on GitHub

// single or bulk url purge
$result = $keycdn->delete('zones/purgeurl/{zone_id}.json', array(
    'urls' => array('foo-1.kxcdn.com/bar1.jpg','foo-1.kxcdn.com/bar2.jpg'),
));

{
    "status": "success",
    "description": "Cache has been cleared for URL(s)."
}

Purge Zone Tag

Clears the cache for specific tags of a pull zone specified by the {zone_id} parameter.

Request Parameters

Parameter Value Description
tags array of tags, max-length: 128 Purge by tags in the Cache-Tag header

$ curl "https://api.keycdn.com/zones/purgetag/{zone_id}.json" -u [apikey]: -X DELETE -H "Content-Type: application/json" --data '{"tags":["foo","bar"]}'

# example of JSON encoded tags variables
... --data '{"tags":["tag1","tag2"]}'

// requires the PHP Library for the KeyCDN API on GitHub

// purge by tag example
$result = $keycdn->delete('zones/purgetag/{zone_id}.json', array(
    'tags' => array('tag1','tag2'),
));

{
    "status": "success",
    "description": "Cache has been cleared by tag(s)."
}

Add Zone

Add a new zone with the specified parameters for the accessing user.

Request Parameters

  • required parameter
  • optional parameter
Parameter Value pull push
name alphanumeric, max-length: 20
status active | inactive
type pull | push
forcedownload enabled | disabled
cors enabled | disabled
gzip enabled | disabled
expire numeric, range: -1 to 525949
http2 enabled | disabled
securetoken enabled | disabled
securetokenkey alphanumeric, length: 4-15
sslcert disabled | shared | custom
customsslkey valid key
customsslcert valid cert
forcessl disabled | enabled
originurl url (incl. http(s)://), max-length: 128
originshield enabled | disabled
cachemaxexpire numeric, range: 1 to 525949
cacheignorecachecontrol enabled | disabled
cacheignorequerystring enabled | disabled
cachestripcookies enabled | disabled
cachexpullkey alphanumeric, length: 4-15
cachecanonical enabled | disabled
cacherobots enabled | disabled
dirlist enabled | disabled
dirindex enabled | disabled

Response Parameters

Returns the newly created zone according to View Zone.

$ curl "https://api.keycdn.com/zones.json" -u [apikey]: -X POST -d name={name} -d type={type}

{
    "status": "success",
    "description": "Zone successfully added.",
    "data": {
        "zone": {
            "id": "1000",
            "name": "foobar",
            "status": "active",
            "type": "pull",
            "forcedownload": "disabled",
            "cors": "disabled",
            "gzip": "disabled",
            "expire": "0",
            "http2": "disabled",
            "securetoken": "disabled",
            "securetokenkey": null,
            "sslcert": "disabled",
            "customsslkey": null,
            "customsslcert": null,
            "forcessl": "disabled",
            "originurl": "http://foo.com",
            "originshield": "disabled",
            "cachemaxexpire": "1440",
            "cacheignorecachecontrol": "enabled",
            "cacheignorequerystring": "enabled",
            "cachestripcookies": "disabled",
            "cachexpullkey": "KeyCDN",
            "cachecanonical": "disabled",
            "cacherobots": "disabled"
        }
    }
}

Edit Zone

Edit the given zone specified by the parameter {zone_id} with the specified request parameters.

Request Parameters

Same request parameters as in Add Zone (but all are optional).

Response Parameters

Returns the edited zone according to View Zone.

$ curl "https://api.keycdn.com/zones/{zone_id}.json" -u [apikey]: -X PUT -d expire={expire}

{
    "status": "success",
    "description": "Zone successfully changed.",
    "data": {
        "zone": {
            "id": "1000",
            "name": "foobar1",
            "status": "active",
            "type": "pull",
            "forcedownload": "disabled",
            "cors": "disabled",
            "gzip": "disabled",
            "expire": "0",
            "http2": "disabled",
            "securetoken": "disabled",
            "securetokenkey": null,
            "sslcert": "disabled",
            "customsslkey": null,
            "customsslcert": null,
            "forcessl": "disabled",
            "originurl": "http://foo.com",
            "originshield": "disabled",
            "cachemaxexpire": "1440",
            "cacheignorecachecontrol": "enabled",
            "cacheignorequerystring": "enabled",
            "cachestripcookies": "disabled",
            "cachexpullkey": "KeyCDN",
            "cachecanonical": "disabled",
            "cacherobots": "disabled"
        }
    }
}

Delete Zone

Delete the given zone specified by the parameter {zone_id}.

$ curl "https://api.keycdn.com/zones/{zone_id}.json" -u [apikey]: -X DELETE

{
    "status": "success",
    "description": "Zone successfully deleted.",
    "data": []
}

Zonealiases API /zonealiases

Parameter Description

id
Zonealias ID
zone_id
Associated Zone ID
name
Zonealias, e.g. cdn.foo.com

List Zonealiases

Returns a list of all zonealiases on the specified account.

Response Parameters

Parameter
id
zone_id
name

$ curl "https://api.keycdn.com/zonealiases.json" -u [apikey]:

{
    "status": "success",
    "description": "Data successfully received.",
    "data": {
        "zonealiases": [
            {
                "id": "1001",
                "zone_id": "2001",
                "name": "assets.yourwebsite.com"
            },
            {
                "id": "1002",
                "zone_id": "2002",
                "name": "cdn.yourwebsite.com"
            }
        ]
    }
}

Add Zonealias

Adds a zonealiases for a given zone.

Request Parameters

Parameter Value
zone_id numeric
name domain, max-length: 128

Response Parameters

Returns the added zonealias with the same parameters as in List Zonealiases.

$ curl "https://api.keycdn.com/zonealiases.json" -u [apikey]: -X POST -d name={name} -d zone_id={zone_id}

{
    "status": "success",
    "description": "Zonealias successfully added.",
    "data": {
        "zonealias": {
            "id": "1001",
            "name": "assets.yourwebsite.com",
            "zone_id": "2001"
        }
    }
}

Edit Zonealias

Edit the given zonealias specified by the parameter {zonealias_id} with the speciefied request parameters.

Request Parameters

Same request parameters as in Add Zonealias.

Response Parameters

Returns the changed zonealias with the same parameters as in List Zonealiases.

$ curl "https://api.keycdn.com/zonealiases/{zonealias_id}.json" -u [apikey]: -X PUT -d name={name} -d zone_id={zone_id}

{
    "status": "success",
    "description": "Zonealias successfully changed.",
    "data": {
        "zonealias": {
            "id": "1001",
            "name": "assets.yourwebsite.com",
            "zone_id": "2001"
        }
    }
}

Delete Zonealias

Delete the given zonealias specified by the parameter {zonealias_id}.

$ curl "https://api.keycdn.com/zonealiases/{zonealias_id}.json" -u [apikey]: -X DELETE

{
    "status": "success",
    "description": "Zonealias successfully deleted.",
    "data": []
}

Zonereferrers API /zonereferrers

Parameter Description

id
Zonereferrer ID
zone_id
Associated Zone ID
name
Zonereferrer, e.g. www.foo.com

List Zonereferrers

Returns a list of all zonereferrers on the specified account.

Response Parameters

Parameter
id
zone_id
name

$ curl "https://api.keycdn.com/zonereferrers.json" -u [apikey]:

{
    "status": "success",
    "description": "Data successfully received.",
    "data": {
        "zonereferrers": [
            {
                "id": "1001",
                "zone_id": "2001",
                "name": "assets.yourwebsite.com"
            },
            {
                "id": "1002",
                "zone_id": "2002",
                "name": "cdn.yourwebsite.com"
            }
        ]
    }
}

Add Zonereferrer

Adds a zonereferrers for a given zone.

Request Parameters

Parameter Value
zone_id numeric
name domain, max-length: 46

Response Parameters

Returns the added zonereferrer with the same parameters as in List Zonereferrers.

$ curl "https://api.keycdn.com/zonereferrers.json" -u [apikey]: -X POST -d name={name} -d zone_id={zone_id}

{
    "status": "success",
    "description": "Zonereferrer successfully added.",
    "data": {
        "zonereferrer": {
            "id": "1001",
            "name": "assets.yourwebsite.com",
            "zone_id": "2001"
        }
    }
}

Edit Zonereferrer

Edit the given zonereferrer specified by the parameter {zonereferrer_id} with the speciefied request parameters.

Request Parameters

Same request parameters as in Add Zonereferrer.

Response Parameters

Returns the changed zonereferrer with the same parameters as in List Zonereferrers.

$ curl "https://api.keycdn.com/zonereferrers/{zonereferrer_id}.json" -u [apikey]: -X PUT -d name={name} -d zone_id={zone_id}

{
    "status": "success",
    "description": "Zonereferrer successfully changed.",
    "data": {
        "zonereferrer": {
            "id": "1001",
            "name": "assets.yourwebsite.com",
            "zone_id": "2001"
        }
    }
}

Delete Zonereferrer

Delete the given zonereferrer specified by the parameter {zonereferrer_id}.

$ curl "https://api.keycdn.com/zonereferrers/{zonereferrer_id}.json" -u [apikey]: -X DELETE

{
    "status": "success",
    "description": "Zonereferrer successfully deleted.",
    "data": []
}

Reports API /reports

Traffic Statistics

Returns a list of traffic statistics for a given time range.

Request Parameters

Parameter Value
zone_id numeric, optional
start timestamp, required
end timestamp, required

Response Parameters

Parameter
amount (bytes)
timestamp

$ curl "https://api.keycdn.com/reports/traffic.json?start={start}&end={end}" -u [apikey]:

{
    "status": "success",
    "description": "Data successfully received.",
    "data": {
        "stats": [
            {
                "amount": "1476240660",
                "timestamp": "1408668601"
            },
            {
                "amount": "1308742288",
                "timestamp": "1408755001"
            },
            {
                "amount": "1381211876",
                "timestamp": "1408841401"
            }
        ]
    }
}

Storage Statistics

Returns a list of storage statistics for a given time range.

Request Parameters

Parameter Value
zone_id numeric, optional
start timestamp, required
end timestamp, required

Response Parameters

Parameter
amount (bytes)
timestamp

$ curl "https://api.keycdn.com/reports/storage.json?start={start}&end={end}" -u [apikey]:

{
    "status": "success",
    "description": "Data successfully received.",
    "data": {
        "stats": [
            {
                "amount": "23729283",
                "timestamp": "1408665721"
            },
            {
                "amount": "23737475",
                "timestamp": "1408752121"
            },
            {
                "amount": "23753859",
                "timestamp": "1408838521"
            }
        ]
    }
}

Status Statistics

Returns a list of state statistics for a given time range.

Request Parameters

Parameter Value
zone_id numeric, optional
start timestamp, required
end timestamp, required

Response Parameters

Parameter
totalcachehit
totalcachemiss
totalerror (4xx)
totalsuccess (2xx)
timestamp

$ curl "https://api.keycdn.com/reports/statestats.json?start={start}&end={end}" -u [apikey]:

{
    "status": "success",
    "description": "Data successfully received.",
    "data": {
        "stats": [
            {
                "totalcachehit": "1535",
                "totalcachemiss": "76",
                "totalsuccess": "1652",
                "totalerror": "46",
                "timestamp": "1408751401"
            },
            {
                "totalcachehit": "1363",
                "totalcachemiss": "0",
                "totalsuccess": "1365",
                "totalerror": "0",
                "timestamp": "1408837801"
            },
            {
                "totalcachehit": "1438",
                "totalcachemiss": "0",
                "totalsuccess": "1440",
                "totalerror": "4",
                "timestamp": "1408924201"
            }
        ]
    }
}

Credits Statistics

Returns a list of credit bookings for a given time range.

Request Parameters

Parameter Value
start timestamp, required
end timestamp, required

Response Parameters

Parameter
amount (credits)
type, e.g. traffic | storage | zones | initial | payment
timestamp

$ curl "https://api.keycdn.com/reports/credits.json?start={start}&end={end}" -u [apikey]:

{
    "status": "success",
    "description": "Data successfully received.",
    "data": {
        "stats": [
            {
                "amount": "-0.06",
                "type": "traffic",
                "timestamp": "1408668601"
            },
            {
                "amount": "-0.05",
                "type": "storage",
                "timestamp": "1408755001"
            },
            {
                "amount": "-0.05",
                "type": "traffic",
                "timestamp": "1408841401"
            }
        ]
    }
}