[go: up one dir, main page]

API

Complete content delivery control from any application in any language.

Overview

The KeyCDN API allows you to manage your Zones, Zone Aliases, Zone Referrers, 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 open a support request if you have any questions.
  • Please submit a request for enhancement (RFE) if you need more functionality.

Changelog

  • 2024-06-12 Added region to traffic statistics.
  • 2022-02-24 Added Cache Key Country.
  • 2021-04-08 Added Secure Token IP address.
  • 2020-06-12 Added Block Referrer feature.
  • 2020-02-12 Added credit balance and Image Processing reporting.
  • 2020-01-28 Added Image Processing feature.
  • 2020-01-20 Added 3xx and 5xx to status statistics.
  • 2019-08-05 Increased API rate limit.
  • 2019-03-30 Added support to purge various cache key combinations.
  • 2017-09-01 Added Forward Host Header, Cache Key Scheme, Cache Key Host, Cache Key Cookie, Cache Key Device, Cache Brotli, and Generic Error Pages features.
  • 2016-07-22 Changed Edit Zone to not require name parameter.
  • 2016-03-05 Added Let's Encrypt feature.
  • 2015-11-20 Changed the API base URL to api.keycdn.com.
  • 2015-09-22 Purge simplification.
  • 2015-09-22 Updated API key authentication.
  • 2015-01-26 Added Origin Shield feature.
  • 2014-09-10 Added Force SSL feature.
  • 2014-08-25 Added Zones, Zone Aliases, and Zone Referrers.
  • 2014-08-25 Introduced rate limiting.
  • 2014-07-29 Added Reports 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). To receive data or make changes to your account, replace the example API key with your actual API key.

Example Request

                    
                        $ curl https://api.keycdn.com/zones.json \
                            -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86:
                    
                

Response Parameters

ParameterDescription
statusStatus code of the current API call.
descriptionDescription of an API call.
dataThe response data of the API call.

Example Response

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

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), and codes in the 5xx range indicate an error with KeyCDN's edge servers.

Not all errors map cleanly onto HTTP response codes.

HTTP Status Code Summary

StatusDescription
200 OKEverything worked as expected.
400 Bad RequestOften missing a required parameter.
403 ForbiddenAccess denied.
404 Not FoundThe requested item does not exist.
413 Request Entity Too LargeMaximum body size is 64 KB.
429 Too Many RequestsRate limit exceeded.
451 IllegalIllegal or malicious request.
500, 502, 503, or 504Something went wrong on KeyCDN's end.

Rate Limiting

API requests are currently rate limited at 60 queries per 60 seconds window. Purge requests are limited to 1 request per second. Ensure that you inspect the following HTTP response headers, as they provide pertinent data on where your utilization is at for the given rate limit. The calling IP will be blocked if the X-Rate-Limit-Remaining value reaches 0.

HeaderDescription
X-Rate-Limit-LimitThe rate limit ceiling for that given request.
X-Rate-Limit-RemainingThe number of requests left for the 60 seconds window.
The KeyCDN API will return an HTTP 429 Too Many Requests response status when you exceed the rate limit.

Zones API

ParameterDescription
idZone ID
nameZone name
statusZone status
typeZone type
forcedownloadForces content to download instead of opening. The following response header will be set: Content-Disposition: Attachment
corsAllow unrestricted Cross-Origin Resource Sharing (CORS). The following response header will be set: Access-Control-Allow-Origin: \*
gzipGzip compression on content 1 KB or larger.
imgprocTransform and optimize images in real time with simple query parameters.
Image Processing incurs an additional cost.
expireAdding or modifying the Cache-Control and Expires response headers that are sent to the client if the HTTP response status code equals 200, 201, 204, 206, 301, 302, 303, 304, or 307:
-1Cache-Control: no-cache
0Push Zone: disabled
Pull Zone: as received from the origin server
>0Cache-Control: max-age=t where t is the time specified in minutes and then converted to seconds
If cacheignorecachecontrol is enabled the expire value will only have an impact on the browser cache and not on the KeyCDN cache.
blockbadbotsBlock bad bots (returns a 451 Unavailable For Legal Reasons response status).
allowemptyreferrerAllow requests with an empty Referer request header value if one or more Zone Referrer is active.
blockreferrerBlock requests with a Referer request header value matching a Zone Referrer (returns a 403 Forbidden response status).
securetokenRestrict access to all content within Zone by Secure Token.
securetokenkeySecret used to check authenticity of request if securetoken is enabled.
securetokenipThe IP of the client will be part of Secure Token if enabled.
sslcertAdd SSL/TLS certificate to be used for HTTPS requests:
sharedEnables the shared wildcard certificate to be used with the Zone URL (e.g. https://examplepull-hexid.kxcdn.com)
customEnables the custom certificate defined in customsslkey and customsslcert to be used with a Zone Alias (e.g. https://cdn.example.com)
letsencryptEnables a Let's Encrypt certificate to be used with one Zone Alias (e.g. https://cdn.example.com)
You must remove an exising Zone Alias before enabling the letsencrypt option (or recreate the Zone Alias afterwards).
customsslkeyThe custom SSL/TLS certificate private key. Include the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- statements.
customsslcertThe custom SSL/TLS certificate. The required format is PEM (Base64 encoded ASCII), which is the most common format that Certificate Authorities issue. Include the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- statements and optionally include the intermediate certificate:
Cert only
                                                        
                                                            -----BEGIN CERTIFICATE-----
                                                            Certificate
                                                            -----END CERTIFICATE-----
                                                        
                                                    
With intermediate cert
                                                        
                                                            -----BEGIN CERTIFICATE-----
                                                            Certificate
                                                            -----END CERTIFICATE-----
                                                            -----BEGIN CERTIFICATE-----
                                                            Intermediate certificate
                                                            -----END CERTIFICATE-----
                                                        
                                                    
forcesslRedirects HTTP requests to HTTPS (returns a 301 Moved Permanently response status).
originurlURL of the origin server where content is pulled from. Include only the scheme and hostname (e.g. https://www.example.com). Do not include a file path (e.g. https://www.example.com/index.html).
originshieldPredefined shield servers will pull content from the origin server instead of our edge servers. This will reduce traffic on the origin server but adds an additional request from the edge server to the shield server if the content has not been cached yet. The following response header will be set: X-Shield: active
cachemaxexpireDefine the maximum time in minutes that cacheable content will be retained in the KeyCDN cache without checking the origin server. Applies only if not defined by the origin server X-Accel-Expires, Cache-Control, or Expires response headers.
cacheignorecachecontrolIgnores processing of X-Accel-Expires, Cache-Control, and Expires response headers received from the origin server. If enabled the cachemaxexpire value has precedence.
cacheignorequerystringIgnores the presence of query strings. The KeyCDN cache will respond with a cached response even if the query string differs.
cachehostheaderForwards the Host request header (e.g. Host: cdn.example.com) to the origin server as received from the client instead of the Host request header defined by the originurl hostname.
cachekeyschemeScheme based caching (http:// or https://) as requested by the client.
cachekeyhostHost request header based caching that matches the Zone Alias.
cachekeycookieCookie variable based caching as received in the Cookie request header.
cachekeydeviceDevice based caching (desktop, tablet, or mobile) as received in the User-Agent request header.
The default device type is desktop.
cachekeywebpWebP image format based caching as received in the Accept request header.
cachekeycountryCountry code based caching derived from the client IP address.
cachebrBrotli based caching as requested by the client.
The origin server must support the Brotli compression format.
cachecookiesIgnore the presence of cookies. By default content with cookies are not cacheable, but when cookies are ignored content becomes cacheable.
cachestripcookiesStrip the Set-Cookie response header received from the origin server.
cachexpullkeySet a custom X-Pull request header value (e.g. X-Pull: example). This is a custom request header that can serve multiple purposes, such as restricting access to the origin server or allowing all KeyCDN edge server requests through a firewall.
cachecanonicalAdd a canonical response header with the originurl as the reference to consolidate duplicate content. The following response header will be set:
                                        
                                            Link: <https://www.example.com/css/style.css>; rel="canonical"
                                        
                                    
cacherobotsAdding or modifying the robots.txt to prevent content from being indexed:
                                        
                                            User-agent: *
                                            Disallow: /
                                        
                                    
cacheerrorpagesDeliver generic error pages for 4xx and 5xx errors instead of the error pages received from the origin server.
dirlistGenerates directory indexes automatically (similar to the Unix ls command or the Win32 dir shell command).

List Zones

Returns a list of all Zones on the specified account.

                    
                        GEThttps://api.keycdn.com/zones.json
                    
                

Response Parameters

Returns a list of Zones as defined in View Zone.

Example

            
                
                    $ curl https://api.keycdn.com/zones.json \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86:
                
            
        
            
                
                    {
                        "status": "success",
                        "description": "Data successfully received.",
                        "data": {
                            "zones": [
                                {
                                    "id": "1000",
                                    "name": "examplepull",
                                    "status": "active",
                                    "type": "pull",
                                    "forcedownload": "disabled",
                                    "cors": "disabled",
                                    "gzip": "disabled",
                                    "imgproc": "disabled",
                                    "expire": "0",
                                    "blockbadbots": "enabled",
                                    "allowemptyreferrer": "enabled",
                                    "blockreferrer": "disabled",
                                    "securetoken": "disabled",
                                    "securetokenkey": null,
                                    "securetokenip": "disabled",
                                    "sslcert": "shared",
                                    "customsslkey": null,
                                    "customsslcert": null,
                                    "forcessl": "disabled",
                                    "originurl": "https://example.com",
                                    "cachemaxexpire": "1440",
                                    "cacheignorecachecontrol": "enabled",
                                    "cacheignorequerystring": "enabled",
                                    "cachehostheader": "disabled",
                                    "cachekeyscheme": "disabled",
                                    "cachekeyhost": "disabled",
                                    "cachekeycookie": null,
                                    "cachekeydevice": "disabled",
                                    "cachekeywebp": "disabled",
                                    "cachekeycountry": "disabled",
                                    "cachebr": "disabled",
                                    "cachecookies": "disabled",
                                    "cachestripcookies": "disabled",
                                    "cachexpullkey": "KeyCDN",
                                    "cachecanonical": "disabled",
                                    "cacherobots": "disabled",
                                    "cacheerrorpages": "enabled"
                                },
                                {
                                    "id": "1001",
                                    "name": "examplepush",
                                    "status": "active",
                                    "type": "push",
                                    "forcedownload": "disabled",
                                    "cors": "disabled",
                                    "gzip": "disabled",
                                    "imgproc": "disabled",
                                    "expire": "0",
                                    "blockbadbots": "enabled",
                                    "allowemptyreferrer": "enabled",
                                    "blockreferrer": "disabled",
                                    "securetoken": "disabled",
                                    "securetokenkey": null,
                                    "securetokenip": "disabled",
                                    "sslcert": "shared",
                                    "customsslkey": null,
                                    "customsslcert": null,
                                    "forcessl": "disabled",
                                    "dirlist": "disabled"
                                },
                                ...
                            ]
                        }
                    }
                
            
        

View Zone

Returns a Zone specified by the {zone_id} parameter.

                    
                        GEThttps://api.keycdn.com/zones/{zone_id}.json
                    
                

Response Parameters

ParameterPullPush
id
name
status
type
forcedownload
cors
gzip
imgproc
expire
blockbadbots
allowemptyreferrer
blockreferrer
securetoken
securetokenkey
securetokenip
sslcert
customsslkey
customsslcert
forcessl
originurl
originshield
cachemaxexpire
cacheignorecachecontrol
cacheignorequerystring
cachehostheader
cachekeyscheme
cachekeyhost
cachekeycookie
cachekeydevice
cachekeywebp
cachekeycountry
cachebr
cachecookies
cachestripcookies
cachexpullkey
cachecanonical
cacherobots
cacheerrorpages
dirlist

Example

            
                
                    $ curl https://api.keycdn.com/zones/1000.json \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86:
                
            
        
            
                
                    {
                        "status": "success",
                        "description": "Data successfully received.",
                        "data": {
                            "zone": {
                                "id": "1000",
                                "name": "examplepull",
                                "status": "active",
                                "type": "pull",
                                "forcedownload": "disabled",
                                "cors": "disabled",
                                "gzip": "disabled",
                                "imgproc": "disabled",
                                "expire": "0",
                                "blockbadbots": "enabled",
                                "allowemptyreferrer": "enabled",
                                "blockreferrer": "disabled",
                                "securetoken": "disabled",
                                "securetokenkey": null,
                                "securetokenip": "disabled",
                                "sslcert": "shared",
                                "customsslkey": null,
                                "customsslcert": null,
                                "forcessl": "disabled",
                                "originurl": "https://example.com",
                                "originshield": "disabled",
                                "cachemaxexpire": "1440",
                                "cacheignorecachecontrol": "enabled",
                                "cacheignorequerystring": "enabled",
                                "cachehostheader": "disabled",
                                "cachekeyscheme": "disabled",
                                "cachekeyhost": "disabled",
                                "cachekeycookie": null,
                                "cachekeydevice": "disabled",
                                "cachekeywebp": "disabled",
                                "cachekeycountry": "disabled",
                                "cachebr": "disabled",
                                "cachecookies": "disabled",
                                "cachestripcookies": "disabled",
                                "cachexpullkey": "KeyCDN",
                                "cachecanonical": "disabled",
                                "cacherobots": "disabled",
                                "cacheerrorpages": "enabled"
                            }
                        }
                    }
                
            
        

Add Zone

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

                    
                        POSThttps://api.keycdn.com/zones.json
                    
                

Request Parameters

ParameterValueDefaultPullPush
name
required
{alphanumeric}
max length: 20
status
optional
active or inactiveactive
type
required
pull or pushpush
forcedownload
optional
enabled or disableddisabled
cors
optional
enabled or disableddisabled
gzip
optional
enabled or disableddisabled
imgproc
optional
enabled or disableddisabled
expire
optional
{numeric}
range: -1 to 525949
0
blockbadbots
optional
enabled or disableddisabled
allowemptyreferrer
optional
enabled or disabledenabled
blockreferrer
optional
enabled or disableddisabled
securetoken
optional
enabled or disableddisabled
securetokenkey
optional
{alphanumeric}
length: 4-15
securetokenip
optional
enabled or disableddisabled
sslcert
optional
shared,custom,
letsencrypt or disabled
shared
customsslkey
optional
{valid key}
customsslcert
optional
{valid cert}
forcessl
optional
enabled or disableddisabled
originurl
required
{url}
max length: 128
originshield
optional
enabled or disableddisabled
cachemaxexpire
optional
{numeric}
range: 1 to 525949
1440
cacheignorecachecontrol
optional
enabled or disabledenabled
cacheignorequerystring
optional
enabled or disabledenabled
cachehostheader
optional
enabled or disableddisabled
cachekeyscheme
optional
enabled or disableddisabled
cachekeyhost
optional
enabled or disableddisabled
cachekeycookie
optional
{alphanumeric}
max length: 32
cachekeydevice
optional
enabled or disableddisabled
cachekeywebp
optional
enabled or disableddisabled
cachekeycountry
optional
enabled or disableddisabled
cachebr
optional
enabled or disableddisabled
cachecookies
optional
enabled or disableddisabled
cachestripcookies
optional
enabled or disableddisabled
cachexpullkey
optional
{alphanumeric}
length: 4-15
KeyCDN
cachecanonical
optional
enabled or disableddisabled
cacherobots
optional
enabled or disableddisabled
cacheerrorpages
optional
enabled or disabledenabled
dirlist
optional
enabled or disableddisabled

Response Parameters

Returns the newly created Zone according to View Zone.

Example

            
                
                    $ curl https://api.keycdn.com/zones.json \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86: \
                        -X POST \
                        -d name=examplepull \
                        -d type=pull \
                        -d originurl=https://example.com
                
            
        
            
                
                    {
                        "status": "success",
                        "description": "Zone successfully added.",
                        "data": {
                            "zone": {
                                "id": "1000",
                                "name": "examplepull",
                                "status": "active",
                                "type": "pull",
                                "forcedownload": "disabled",
                                "cors": "disabled",
                                "gzip": "disabled",
                                "imgproc": "disabled",
                                "expire": "0",
                                "blockbadbots": "enabled",
                                "allowemptyreferrer": "enabled",
                                "blockreferrer": "disabled",
                                "securetoken": "disabled",
                                "securetokenkey": null,
                                "securetokenip": "disabled",
                                "sslcert": "shared",
                                "customsslkey": null,
                                "customsslcert": null,
                                "forcessl": "disabled",
                                "originurl": "https://example.com",
                                "originshield": "disabled",
                                "cachemaxexpire": "1440",
                                "cacheignorecachecontrol": "enabled",
                                "cacheignorequerystring": "enabled",
                                "cachehostheader": "disabled",
                                "cachekeyscheme": "disabled",
                                "cachekeyhost": "disabled",
                                "cachekeycookie": null,
                                "cachekeydevice": "disabled",
                                "cachekeywebp": "disabled",
                                "cachekeycountry": "disabled",
                                "cachebr": "disabled",
                                "cachecookies": "disabled",
                                "cachestripcookies": "disabled",
                                "cachexpullkey": "KeyCDN",
                                "cachecanonical": "disabled",
                                "cacherobots": "disabled",
                                "cacheerrorpages": "enabled"
                            }
                        }
                    }
                
            
        

Edit Zone

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

                    
                        PUThttps://api.keycdn.com/zones/{zone_id}.json
                    
                

Request Parameters

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

Response Parameters

Returns the edited Zone according to View Zone.

Example

            
                
                    $ curl https://api.keycdn.com/zones/1000.json \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86: \
                        -X PUT \
                        -d expire=43200
                
            
        
            
                
                    {
                        "status": "success",
                        "description": "Zone successfully changed.",
                        "data": {
                            "zone": {
                                "id": "1000",
                                "name": "examplepull",
                                "status": "active",
                                "type": "pull",
                                "forcedownload": "disabled",
                                "cors": "disabled",
                                "gzip": "disabled",
                                "imgproc": "disabled",
                                "expire": "43200",
                                "blockbadbots": "enabled",
                                "allowemptyreferrer": "enabled",
                                "blockreferrer": "disabled",
                                "securetoken": "disabled",
                                "securetokenkey": null,
                                "securetokenip": "disabled",
                                "sslcert": "shared",
                                "customsslkey": null,
                                "customsslcert": null,
                                "forcessl": "disabled",
                                "originurl": "https://example.com",
                                "originshield": "disabled",
                                "cachemaxexpire": "1440",
                                "cacheignorecachecontrol": "enabled",
                                "cacheignorequerystring": "enabled",
                                "cachehostheader": "disabled",
                                "cachekeyscheme": "disabled",
                                "cachekeyhost": "disabled",
                                "cachekeycookie": null,
                                "cachekeydevice": "disabled",
                                "cachekeywebp": "disabled",
                                "cachekeycountry": "disabled",
                                "cachebr": "disabled",
                                "cachecookies": "disabled",
                                "cachestripcookies": "disabled",
                                "cachexpullkey": "KeyCDN",
                                "cachecanonical": "disabled",
                                "cacherobots": "disabled",
                                "cacheerrorpages": "enabled"
                            }
                        }
                    }
                
            
        

Delete Zone

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

                    
                        DELETEhttps://api.keycdn.com/zones/{zone_id}.json
                    
                

Example

            
                
                    $ curl https://api.keycdn.com/zones/1000.json \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86: \
                        -X DELETE
                
            
        
            
                
                    {
                        "status": "success",
                        "description": "Zone successfully deleted.",
                        "data": []
                    }
                
            
        

Purge Zone Cache

Clears the entire cache of a Pull Zone specified by the {zone_id} parameter.

                    
                        GEThttps://api.keycdn.com/zones/purge/{zone_id}.json
                    
                

Example

            
                
                    $ curl https://api.keycdn.com/zones/purge/1000.json \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86:
                
            
        
            
                
                    {
                        "status": "success",
                        "description": "Cache has been cleared for zone examplepull."
                    }
                
            
        

Purge Zone URL

Clears the cache for the defined URL(s) by the {zone_id} parameter.

                    
                        DELETEhttps://api.keycdn.com/zones/purgeurl/{zone_id}.json
                    
                

Request Parameters

ParameterValueDefaultPullPush
urls
required
{array of URLs}
without scheme

Example

            
                
                    $ curl https://api.keycdn.com/zones/purgeurl/1000.json \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86: \
                        -X DELETE \
                        -H "Content-Type: application/json" \
                        --data '{"urls":["examplepull-hexid.kxcdn.com/css/style.css","examplepull-hexid.kxcdn.com/js/app.js","examplepull-hexid.kxcdn.com/img/logo.svg"]}'
                
            
        
            
                
                    {
                        "status": "success",
                        "description": "Cache has been cleared for URL(s)."
                    }
                
            
        
If cachekeyscheme is enabled prepend the scheme.

Example

            
                
                    $ curl https://api.keycdn.com/zones/purgeurl/1000.json \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86: \
                        -X DELETE \
                        -H "Content-Type: application/json" \
                        --data '{"urls":["http://examplepull-hexid.kxcdn.com/css/style.css","https://examplepull-hexid.kxcdn.com/css/style.css"]}'
                
            
        
            
                
                    {
                        "status": "success",
                        "description": "Cache has been cleared for URL(s)."
                    }
                
            
        
If cachekeyhost is enabled use the Zone Alias instead of the Zone URL.

Example

            
                
                    $ curl https://api.keycdn.com/zones/purgeurl/1000.json \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86: \
                        -X DELETE \
                        -H "Content-Type: application/json" \
                        --data '{"urls":["cdnpull.example.com/css/style.css","cdnpull.example.com/js/app.js","cdnpull.example.com/img/logo.svg"]}'
                
            
        
            
                
                    {
                        "status": "success",
                        "description": "Cache has been cleared for URL(s)."
                    }
                
            
        
If cacheignorequerystring is disabled append the query string.

Example

            
                
                    $ curl https://api.keycdn.com/zones/purgeurl/1000.json \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86: \
                        -X DELETE \
                        -H "Content-Type: application/json" \
                        --data '{"urls":["examplepull-hexid.kxcdn.com/css/style.css","examplepull-hexid.kxcdn.com/css/style.css?name=value"]}'
                
            
        
            
                
                    {
                        "status": "success",
                        "description": "Cache has been cleared for URL(s)."
                    }
                
            
        
If cachekeycookie is enabled append the cookie variable.

Example

            
                
                    $ curl https://api.keycdn.com/zones/purgeurl/1000.json \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86: \
                        -X DELETE \
                        -H "Content-Type: application/json" \
                        --data '{"urls":["examplepull-hexid.kxcdn.com/css/style.css","examplepull-hexid.kxcdn.com/css/style.csscookie"]}'
                
            
        
            
                
                    {
                        "status": "success",
                        "description": "Cache has been cleared for URL(s)."
                    }
                
            
        
If cachekeydevice is enabled append the device type.

Example

            
                
                    $ curl https://api.keycdn.com/zones/purgeurl/1000.json \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86: \
                        -X DELETE \
                        -H "Content-Type: application/json" \
                        --data '{"urls":["examplepull-hexid.kxcdn.com/css/style.cssdesktop","examplepull-hexid.kxcdn.com/css/style.csstablet","examplepull-hexid.kxcdn.com/css/style.cssmobile"]}'
                
            
        
            
                
                    {
                        "status": "success",
                        "description": "Cache has been cleared for URL(s)."
                    }
                
            
        
If cachekeywebp is enabled append webp.

Example

            
                
                    $ curl https://api.keycdn.com/zones/purgeurl/1000.json \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86: \
                        -X DELETE \
                        -H "Content-Type: application/json" \
                        --data '{"urls":["examplepull-hexid.kxcdn.com/img/logo.png", "examplepull-hexid.kxcdn.com/img/logo.pngwebp"]}'
                
            
        
            
                
                    {
                        "status": "success",
                        "description": "Cache has been cleared for URL(s)."
                    }
                
            
        
If cachekeycountry is enabled append the two-letter country code (e.g. US).

Example

            
                
                    $ curl https://api.keycdn.com/zones/purgeurl/1000.json \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86: \
                        -X DELETE \
                        -H "Content-Type: application/json" \
                        --data '{"urls":["examplepull-hexid.kxcdn.com/img/logo.png", "examplepull-hexid.kxcdn.com/img/logo.pngUS"]}'
                
            
        
            
                
                    {
                        "status": "success",
                        "description": "Cache has been cleared for URL(s)."
                    }
                
            
        
If cachebr is enabled append br.

Example

            
                
                    $ curl https://api.keycdn.com/zones/purgeurl/1000.json \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86: \
                        -X DELETE \
                        -H "Content-Type: application/json" \
                        --data '{"urls":["examplepull-hexid.kxcdn.com/css/style.css","examplepull-hexid.kxcdn.com/css/style.cssbr"]}'
                
            
        
            
                
                    {
                        "status": "success",
                        "description": "Cache has been cleared for URL(s)."
                    }
                
            
        
Combine two or more cache keys in the following order: scheme host querystring cookie br device webp country

Example

            
                
                    $ curl https://api.keycdn.com/zones/purgeurl/1000.json \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86: \
                        -X DELETE \
                        -H "Content-Type: application/json" \
                        --data '{"urls":["https://cdnpull.example.com/css/style.css?name=valuecookiebrdesktop"]}'
                
            
        
            
                
                    {
                        "status": "success",
                        "description": "Cache has been cleared for URL(s)."
                    }
                
            
        

Zone Aliases API

ParameterDescription
idZone Alias ID
zone_idAssociated Zone ID
nameZone Alias hostname

List Zone Aliases

Returns a list of all Zone Aliases on the specified account.

                    
                        GEThttps://api.keycdn.com/zonealiases.json
                    
                

Response Parameters

ParameterPullPush
id
zone_id
name

Example

            
                
                    $ curl https://api.keycdn.com/zonealiases.json \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86:
                
            
        
            
                
                    {
                        "status": "success",
                        "description": "Data successfully received.",
                        "data": {
                            "zonealiases": [
                                {
                                    "id": "2000",
                                    "zone_id": "1000",
                                    "name": "cdnpull.example.com"
                                },
                                {
                                    "id": "2001",
                                    "zone_id": "1001",
                                    "name": "cdnpush.example.com"
                                }
                            ]
                        }
                    }
                
            
        

Add Zone Alias

Adds a Zone Aliases for a given Zone.

                    
                        POSThttps://api.keycdn.com/zonealiases.json
                    
                

Request Parameters

ParameterValueDefaultPullPush
zone_id
required
{numeric}
name
required
{hostname}
max length: 128

Response Parameters

Returns the added Zone Alias with the same parameters as in List Zone Aliases.

Example

            
                
                    $ curl https://api.keycdn.com/zonealiases.json \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86: \
                        -X POST \
                        -d name=cdnpull.example.com \
                        -d zone_id=1000
                
            
        
            
                
                    {
                        "status": "success",
                        "description": "Zone Alias successfully added.",
                        "data": {
                            "zonealias": {
                                "id": "2000",
                                "name": "cdnpull.example.com",
                                "zone_id": "1000"
                            }
                        }
                    }
                
            
        

Edit Zone Alias

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

                    
                        PUThttps://api.keycdn.com/zonealiases/{zonealias_id}.json
                    
                

Request Parameters

Same request parameters as in Add Zone Alias.

Response Parameters

Returns the changed Zone Alias with the same parameters as in List Zone Aliases.

Example

            
                
                    $ curl https://api.keycdn.com/zonealiases/2000.json \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86: \
                        -X PUT \
                        -d name=cdn-pull.example.com \
                        -d zone_id=1000
                
            
        
            
                
                    {
                        "status": "success",
                        "description": "Zone Alias successfully changed.",
                        "data": {
                            "zonealias": {
                                "id": "2000",
                                "name": "cdn-pull.example.com",
                                "zone_id": "1000"
                            }
                        }
                    }
                
            
        

Delete Zone Alias

Delete the given Zone Alias specified by the parameter {zonealias_id}.

                    
                        DELETEhttps://api.keycdn.com/zonealiases/{zonealias_id}.json
                    
                

Example

            
                
                    $ curl https://api.keycdn.com/zonealiases/2000.json \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86: \
                        -X DELETE
                
            
        
            
                
                    {
                        "status": "success",
                        "description": "Zone Alias successfully deleted.",
                        "data": []
                    }
                
            
        

Zone Referrers API

ParameterDescription
idZone Referrer ID
zone_idAssociated Zone ID
nameZone Referrer hostname

List Zone Referrers

Returns a list of all Zone Referrers on the specified account.

                    
                        GEThttps://api.keycdn.com/zonereferrers.json
                    
                

Response Parameters

ParameterPullPush
id
zone_id
name

Example

            
                
                    $ curl https://api.keycdn.com/zonereferrers.json \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86:
                
            
        
            
                
                    {
                        "status": "success",
                        "description": "Data successfully received.",
                        "data": {
                            "zonereferrers": [
                                {
                                    "id": "3000",
                                    "zone_id": "1000",
                                    "name": "example.com"
                                },
                                {
                                    "id": "3001",
                                    "zone_id": "1000",
                                    "name": "cdnpull.example.com"
                                },
                                {
                                    "id": "3002",
                                    "zone_id": "1000",
                                    "name": "examplepull-hexid.kxcdn.com"
                                }
                            ]
                        }
                    }
                
            
        

Add Zone Referrer

Adds a Zone Referrers for a given Zone.

                    
                        POSThttps://api.keycdn.com/zonereferrers.json
                    
                

Request Parameters

ParameterValueDefaultPullPush
zone_id
required
{numeric}
name
required
{hostname}
max length: 46

Response Parameters

Returns the added Zone Referrer with the same parameters as in List Zone Referrers.

Example

            
                
                    $ curl https://api.keycdn.com/zonereferrers.json \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86: \
                        -X POST \
                        -d name=example.com \
                        -d zone_id=1000
                
            
        
            
                
                    {
                        "status": "success",
                        "description": "Zone Referrer successfully added.",
                        "data": {
                            "zonereferrer": {
                                "id": "3000",
                                "name": "example.com",
                                "zone_id": "1000"
                            }
                        }
                    }
                
            
        

Edit Zone Referrer

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

                    
                        PUThttps://api.keycdn.com/zonereferrers/{zonereferrer_id}.json
                    
                

Request Parameters

Same request parameters as in Add Zone Referrer.

Response Parameters

Returns the changed Zone Referrer with the same parameters as in List Zone Referrers.

Example

            
                
                    $ curl https://api.keycdn.com/zonereferrers/3000.json \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86: \
                        -X PUT \
                        -d name=example.net \
                        -d zone_id=1000
                
            
        
            
                
                    {
                        "status": "success",
                        "description": "Zone Referrer successfully changed.",
                        "data": {
                            "zonereferrer": {
                                "id": "3000",
                                "name": "example.net",
                                "zone_id": "1000"
                            }
                        }
                    }
                
            
        

Delete Zone Referrer

Delete the given Zone Referrer specified by the parameter {zonereferrer_id}.

                    
                        DELETEhttps://api.keycdn.com/zonereferrers/{zonereferrer_id}.json
                    
                

Example

            
                
                    $ curl https://api.keycdn.com/zonereferrers/3000.json \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86: \
                        -X DELETE
                
            
        
            
                
                    {
                        "status": "success",
                        "description": "Zone Referrer successfully deleted.",
                        "data": []
                    }
                
            
        

Reports API

Traffic Statistics

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

                    
                        GEThttps://api.keycdn.com/reports/traffic.json
                    
                

Request Parameters

ParameterValueDefaultPullPush
zone_id
optional
{numeric}
start
required
{timestamp}
unix
end
required
{timestamp}
unix
region
optional
a, b or c

Response Parameters

ParameterPullPush
amount
bytes
timestamp
unix

Example

            
                
                    $ curl "https://api.keycdn.com/reports/traffic.json?start=1541030400&end=1541203200" \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86:
                
            
        
            
                
                    {
                        "status":"success",
                        "description":"Data successfully received.",
                        "data":{
                            "stats":[
                                {
                                    "amount":"6822186",
                                    "timestamp":"1541030400"
                                },
                                {
                                    "amount":"9327251",
                                    "timestamp":"1541116800"
                                },
                                {
                                    "amount":"6104220",
                                    "timestamp":"1541203200"
                                }
                            ]
                        }
                    }
                
            
        

Storage Statistics

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

                    
                        GEThttps://api.keycdn.com/reports/storage.json
                    
                

Request Parameters

ParameterValueDefaultPullPush
zone_id
optional
{numeric}
start
required
{timestamp}
unix
end
required
{timestamp}
unix

Response Parameters

ParameterPullPush
amount
bytes
timestamp
unix

Example

            
                
                    $ curl "https://api.keycdn.com/reports/storage.json?start=1541030400&end=1541203200" \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86:
                
            
        
            
                
                    {
                        "status":"success",
                        "description":"Data successfully received.",
                        "data":{
                            "stats":[
                                {
                                    "amount":"538923008",
                                    "timestamp":"1541030400"
                                },
                                {
                                    "amount":"538923008",
                                    "timestamp":"1541116800"
                                },
                                {
                                    "amount":"538923008",
                                    "timestamp":"1541203200"
                                }
                            ]
                        }
                    }
                
            
        

Image Processing Statistics

Returns a list of Image Processing statistics for a given time range.

                    
                        GEThttps://api.keycdn.com/reports/ip.json
                    
                

Request Parameters

ParameterValueDefaultPullPush
zone_id
optional
{numeric}
start
required
{timestamp}
unix
end
required
{timestamp}
unix

Response Parameters

ParameterPullPush
amount
ops
timestamp
unix

Example

            
                
                    $ curl "https://api.keycdn.com/reports/ip.json?start=1541030400&end=1541203200" \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86:
                
            
        
            
                
                    {
                        "status":"success",
                        "description":"Data successfully received.",
                        "data":{
                            "stats":[
                                {
                                    "amount":"1208",
                                    "timestamp":"1541030400"
                                },
                                {
                                    "amount":"1234",
                                    "timestamp":"1541116800"
                                },
                                {
                                    "amount":"1062",
                                    "timestamp":"1541203200"
                                }
                            ]
                        }
                    }
                
            
        

Status Statistics

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

                    
                        GEThttps://api.keycdn.com/reports/statestats.json
                    
                

Request Parameters

ParameterValueDefaultPullPush
zone_id
optional
{numeric}
start
required
{timestamp}
unix
end
required
{timestamp}
unix

Response Parameters

ParameterPullPush
totalcachehit
totalcachemiss
total2xx
total3xx
total4xx
total5xx
timestamp
unix

Example

            
                
                    $ curl "https://api.keycdn.com/reports/statestats.json?start=1541030400&end=1541203200" \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86:
                
            
        
            
                
                    {
                        "status":"success",
                        "description":"Data successfully received.",
                        "data":{
                            "stats":[
                                {
                                    "totalcachehit":"313",
                                    "totalcachemiss":"18",
                                    "totalsuccess":"329",
                                    "totalerror":"5",
                                    "timestamp":"1541030400"
                                },
                                {
                                    "totalcachehit":"219",
                                    "totalcachemiss":"4",
                                    "totalsuccess":"220",
                                    "totalerror":"2",
                                    "timestamp":"1541116800"
                                },
                                {
                                    "totalcachehit":"284",
                                    "totalcachemiss":"11",
                                    "totalsuccess":"302",
                                    "totalerror":"4",
                                    "timestamp":"1541203200"
                                }
                            ]
                        }
                    }
                
            
        

Credits Statistics

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

                    
                        GEThttps://api.keycdn.com/reports/credits.json
                    
                

Request Parameters

ParameterValueDefault
start
required
{timestamp}
unix
end
required
{timestamp}
unix

Response Parameters

Parameter
amount
credits
type
traffic, storage, zones, initial, or payment
timestamp
unix

Example

            
                
                    $ curl "https://api.keycdn.com/reports/credits.json?start=?start=1541030400&end=1541203200" \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86:
                
            
        
            
                
                    {
                        "status":"success",
                        "description":"Data successfully received.",
                        "data":{
                            "stats":[
                                {
                                    "amount":"-0.01",
                                    "type":"storage",
                                    "timestamp":"1541030400"
                                },
                                {
                                    "amount":"-0.02",
                                    "type":"traffic",
                                    "timestamp":"1541030400"
                                },
                                {
                                    "amount":"-0.01",
                                    "type":"traffic",
                                    "timestamp":"1541116800"
                                },
                                {
                                    "amount":"-0.01",
                                    "type":"storage",
                                    "timestamp":"1541116800"
                                },
                                {
                                    "amount":"-0.01",
                                    "type":"storage",
                                    "timestamp":"1541203200"
                                },
                                {
                                    "amount":"-0.02",
                                    "type":"traffic",
                                    "timestamp":"1541203200"
                                }
                            ]
                        }
                    }
                
            
        

Credit Balance

Returns the credit balance.

                    
                        GEThttps://api.keycdn.com/reports/creditbalance.json
                    
                

Response Parameters

Parameter
amount
credits

Example

            
                
                    $ curl "https://api.keycdn.com/reports/creditbalance.json" \
                        -u sk_prod_zbSVNe8gVUMT4KjYcJWuyC86:
                
            
        
            
                
                    {
                        "status":"success",
                        "description":"Data successfully received.",
                        "data":{
                            "amount":"100"
                        }
                    }
                
            
        
KeyCDN uses cookies to make its website easier to use. Learn more