UCDN API v3 Documentation

Try UCDN API v4

About

You can use this API with any RESTful compliant client.
In the tables below you will find useful information about request methods, URIs, parameters, how to validate different data and a short description for each. Some of the requests have default values or helper functions. The latter can be used to quickly perform a simple task.
The main purpose of this API is to allow you to configure or fetch information about your zones, or create a purge cache job.

Authentication

You can find your Authentication Token (also known as API key) in your control panel under "View Profile". You will need this token for authenticating with UCDN API. Every request to our API should be authenticated. At the moment we support the following methods of authentication. You can select whichever one you find most suitable for you.
  • Query Token - for every request to our API supply the query parameter token. So the request to GET your account info will become GET https://api.ucdn.com/v3/account/?token=your-api-token.
  • HTTP Header Token - every request to our API must include the HTTP header X-UCDN-Token with value your Authentication Token.

Request Prameters and Responses

Request prameters for the GET method must be in the query string. For every other method (POST, PUT, PATCH) parameters should be supplied in the request body using application/json or application/x-www-form-urlencoded. Content-Type header in the request is required.
Our API always responds with json.

Certificates

List all certificates

This API call lists all certificates for your account. It retuns an array with objects. Every object is information for one certificate. See the call for single certificate where all keys and values for single object are explained.
GET https://api.ucdn.com/v3/certificates
This item returns the following information
Name Flags Description
*** array All certificates for this account.
This request returns one of the following messages
Status Flags Description
200 array success message

Examples

curl -X GET "https://api.ucdn.com/v3/certificates/?token=acf0230d03f5b71d7252e336106f7338"
HTTP/1.1 200 OK
Date: Mon, 29 Jun 2015 08:03:15 GMT
Server: Apache
X-Powered-By: PHP/5.6.8-pl0-gentoo
X-Cache: hit
Vary: Accept-Encoding
Content-Length: 320
Content-Type: application/json; charset=utf-8

[
    {
        "id": 18,
        "hostname": "cdn.section9.com",
        "fingerprint": "3d284b5326388d22f9bfb15600917ebc1dfa96cd",
        "used_in_zones": [
            {
                "zone_id": 1,
                "domain": "cdn.section9.com",
                "cdn_domain": "a1-121.so.clients.cdn13.com"
            }
        ]
    },
    {
        "id": 35,
        "hostname": "cdn3.section9.co.jp",
        "fingerprint": "0f382f59b8ee80950c9663042190008927a6012f",
        "used_in_zones": []
    }
]

Single certificate information

Information for a particular certificate. For security reasons it includes the certificate's fingerprint only.
GET https://api.ucdn.com/v3/certificate/{crt_id}
This item returns the following information
Name Flags Description
id int The id of this certificate
fingerprint string sha1 of the certificate you've uploaded.
hostname string The hostname this certificate is used with.
used_in_zones array List of all zones which make use of this certificate.
This request returns one of the following messages
Status Flags Description
200 object success message
404 string certificate did not exists

Examples

curl -X GET "https://api.ucdn.com/v3/certificate/18/?token=acf0230d03f5b71d7252e336106f7338"
HTTP/1.1 200 OK
Date: Mon, 29 Jun 2015 08:03:15 GMT
Server: Apache
X-Powered-By: PHP/5.6.8-pl0-gentoo
X-Cache: hit
Vary: Accept-Encoding
Content-Length: 199
Content-Type: application/json; charset=utf-8

{
    "id": 18,
    "hostname": "cdn.section9.com",
    "fingerprint": "3d284b5326388d22f9bfb15600917ebc1dfa96cd",
    "used_in_zones": [
        {
            "zone_id": 1,
            "domain": "cdn.section9.com",
            "cdn_domain": "a1-121.so.clients.cdn13.com"
        }
    ]
}

Upload certificate

Will add this certificate in UCDN. UCDN ssl servers will start to use this certificate for this hostname.
POST https://api.ucdn.com/v3/certificate/
This request returns one of the following messages
Status Flags Description
200 string success message
409 string Error message
This request expects the following parameters
Name Flags Validation Default Description
certificate string required It must be in .pem format. Base64 encoded certificate with BEGIN and END. Your certificate in pem format
key string required It must be in .pem format. We support only base64 encoded RSA keys. Your key in pem format
ca_bundle string It must be in .pem format. Base64 encoded with BEGIN and END. CA bundle


Examples

curl -X POST "https://api.ucdn.com/v3/certificate/?token=acf0230d03f5b71d7252e336106f7338" --header "Content-Type: application/json" -d '{"key": "-----BEGIN RSA PRIVATE KEY-----\nMIICXAIBAAKBgQDc95uOOiAJNKaoZBvTqIaMjCRVWhGjiZcHkmM+rENyW4xOuai1\nY2WUyj59jYsHzusu31NmaWgNTSzeYhI0oSBPCmitIEDmp7mGzfqadwFlbtQuAsaK\nR2QkvdpTHkPJaiT0N58Isq2J3M2jjwHnX2npYQILxgndWwt+syeXFoDauwIDAQAB\nAoGAEijfRd8NBvSmxawEhW6SMDbMPZ97V59VJDApq9roaBuR+l5TuSSEEqhUXmkl\nhezBc0azSfVbscwn5dbVfDHJv84Y5BcPyvzBqtrUhzO64HPefFICQh6HpE4t/rke\npSl9KeznWpiQqMq5AQwQo1IHeINnXdp7ZLDp9mCGOJV4Y3ECQQDwIL7kM7Q0nhZ/\nOO4yYzL+AMAYvs1hvhR2Ij7bWYuqJ+Pb/8aV8IrjDQMujFcfS2GwKDEPed42oQZl\n79hQjvavAkEA65Kjzck51prvMNdwv1abcq66COXLf8EdyY74QqjrtKknEweQclQs\nihCt0x47O+YiB1zJ/VLpW845EBCfUpbftQJAI7s7rIllD09W2aeHCkholhNWglgi\nB6FZOhrub4Vrmu5Eob/1tOoOQKr3Bj4r2KRG7QeOBVeFEWv0n8aI0bP0UQJBAKY9\n+LzbmaZ59fxIvTc5/j9DUOPAjwicFtJLw6T/Ij9+86U5PFWCU2AnfxOyjOirci4x\n7BWKckYoVRqiMF0PPdUCQEeq3IancNy8/5s7N6PKxEtnJ6G/Odty03pZ5xwSReM9\njBYtqogXMe6BSm9HlVSPYfA8gs4vynFtJlt0Cdc1A/c=\n-----END RSA PRIVATE KEY-----", "certificate": "-----BEGIN CERTIFICATE-----\nMIICLTCCAZYCCQCl/56DTdFTUDANBgkqhkiG9w0BAQUFADBbMQswCQYDVQQGEwJB\nVTETMBEGA1UECAwKU29tZS1TdGF0ZTEhMB8GA1UECgwYSW50ZXJuZXQgV2lkZ2l0\ncyBQdHkgTHRkMRQwEgYDVQQDDAtleGFtcGxlLmNvbTAeFw0xNTAxMjYxNjIzMTla\nFw0xNjAxMjYxNjIzMTlaMFsxCzAJBgNVBAYTAkFVMRMwEQYDVQQIDApTb21lLVN0\nYXRlMSEwHwYDVQQKDBhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQxFDASBgNVBAMM\nC2V4YW1wbGUuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDc95uOOiAJ\nNKaoZBvTqIaMjCRVWhGjiZcHkmM+rENyW4xOuai1Y2WUyj59jYsHzusu31NmaWgN\nTSzeYhI0oSBPCmitIEDmp7mGzfqadwFlbtQuAsaKR2QkvdpTHkPJaiT0N58Isq2J\n3M2jjwHnX2npYQILxgndWwt+syeXFoDauwIDAQABMA0GCSqGSIb3DQEBBQUAA4GB\nAAEQreWBJw7zReaELu2Pn+IUnXd8N6hJBjp3SX1jCO6LjodjKd33sqyvFvRhZOSg\nevp0wiADmAoVE9jToxPEO5ZxJ1j6dtycog60IRbMGskWeh10m/cUzaKGWYnatYqE\nZsNWvi3ahdovfzM7ukkecn9SDrUD+74+qNIhL6QDqhOD\n-----END CERTIFICATE-----"}'
HTTP/1.1 200 OK
Date: Mon, 29 Jun 2015 08:10:29 GMT
Server: Apache
X-Powered-By: PHP/5.6.8-pl0-gentoo
Vary: Accept-Encoding
Content-Length: 39
Content-Type: application/json; charset=utf-8

{
    "message": "Certificate saved",
    "id": 41
}

Delete certificate

Removes certificate from the CDN. Any further HTTPS hits on the domain for this certificate will use the shared UCDN ssl certificate. This may cause verification errors.
DELETE https://api.ucdn.com/v3/certificate/{crt_id}
This request returns one of the following messages
Status Flags Description
200 string success message
404 string certificate did not exists

Examples

curl -X DELETE "https://api.ucdn.com/v3/certificate/20/?token=acf0230d03f5b71d7252e336106f7338"
HTTP/1.1 200 OK
Date: Mon, 29 Jun 2015 08:10:28 GMT
Server: Apache
X-Powered-By: PHP/5.6.8-pl0-gentoo
Vary: Accept-Encoding
Content-Length: 33
Content-Type: application/json; charset=utf-8

{
    "message": "Certificate 43 was deleted"
}

Reports

Usage report

Returns served bytes and requests satisfied for particular zone or this account as a whole when `zone_id` is omitted or 0.
GET https://api.ucdn.com/v3/reports/[{zone_id}]/[?date_from=...][&date_to=...]
This item returns the following information
Name Flags Description
bytes_served int Bytes served for the requested period
hits int File hits for the requested period
This request returns one of the following messages
Status Flags Description
200 json data
400 json Fail message
404 json Fail message
532 json Fail message
This request expects the following parameters
Name Flags Validation Default Description
date_from required string GMT date in format YYYY-MM-DD or a Unix timestamp 24 hours ago From which date to generate the reports. Inclusive.
date_to required string GMT date in format YYYY-MM-DD or a Unix timestamp Now To which date to generate the reports. Exclusive.


Examples

curl -X GET "https://api.ucdn.com/v3/reports/1/?date_from=2015-08-12&date_to=2015-08-13&token=a1cceef964910f10947c09257e87ca40"
HTTP/1.1 200 OK
Date: Wed, 12 Aug 2015 13:21:34 GMT
Server: Apache
Vary: Accept-Encoding
Content-Length: 49
Content-Type: application/json; charset=utf-8

{
    "hits": 72223298971,
    "bytes_served": 1031761416566
}

Countries

Statistics for the traffic destination by country. It shows hits and bytes served to this country.
GET https://api.ucdn.com/v3/reports/countries/[?from=...][&to=...][&zones=1,2,3][&countries=de,ru,jp]
This item returns the following information
Name Flags Description
elements object A key-value pairs. The key in the pair is a ISO 3166-1 country code. The value an array with the generated data. Every element in the array represents a time slot. See the `element_description` field for for information on what it is made of.
element_duration int Lenght of tht time interval for each element. In seconds.
element_description array Every element in `elements` is an array of values. This fields says what does each value in an element mean.
This request returns one of the following messages
Status Flags Description
200 object Reports data
400 string Fail message
532 string Fail message
This request expects the following parameters
Name Flags Validation Default Description
from string Valid formats are: YYYY-MM-DD HH:mm with optional timezone parameter or a Unix timestamp. Examples: 2014-03-12 15:32 GMT+3, 1394571600 24 hours ago From which date to generate the reports
to string Valid formats are: YYYY-MM-DD HH:mm with optional timezone parameter or a Unix timestamp. Examples: 2014-03-12 15:32 GMT+3, 1394571600 now To which date to generate the reports
zones string A zone id or a list of zone ids separated with comma. Example: 1,2,3,4 All zones for this account Filter output for user zones. This way a report for particular zone or a group of zones can be made.
countries string Comma separated list of countries. Every country must be represented by a ISO 3166-1 country code. Examples: 'bg,vn,ru' All countries. List of countries for which to show statistics.


Examples

curl -X GET "https://api.ucdn.com/v3/reports/countries/?token=a1cceef964910f10947c09257e87ca40"
HTTP/1.1 200 OK
Date: Wed, 12 Aug 2015 11:04:50 GMT
Server: Apache
Vary: Accept-Encoding
Content-Length: 4406
Content-Type: application/json; charset=utf-8

{
    "element_description": [
        "unix timestamp of the time slot start",
        "hits from this country",
        "bytes served to this country"
    ],
    "element_duration": 86400,
    "elements": {
        "CH": [
            [
                1439290800,
                0,
                0
            ],
            [
                1439294400,
                384465,
                19224985
            ],
            [
                1439298000,
                373860,
                18694275
            ],
            [
                1439301600,
                367775,
                18390470
            ]
        ],
        "GB": [
            [
                1439290800,
                0,
                0
            ],
            [
                1439294400,
                427190,
                21361100
            ],
            [
                1439298000,
                415390,
                20771405
            ],
            [
                1439301600,
                408645,
                20433865
            ],
            [
                1439305200,
                407865,
                20394660
            ],
            [
                1439308800,
                415540,
                20778725
            ],
            [
                1439312400,
                439510,
                21977240
            ],
            [
                1439316000,
                476520,
                23827165
            ],
            [
                1439319600,
                515800,
                25791430
            ],
            [
                1439323200,
                531010,
                26551560
            ]
        ],
        "MX": [
            [
                1439290800,
                0,
                0
            ],
            [
                1439294400,
                261435,
                13072990
            ],
            [
                1439298000,
                254210,
                12712090
            ],
            [
                1439301600,
                250090,
                12505515
            ]
        ],
        "RU": [
            [
                1439290800,
                0,
                0
            ]
        ],
        "US": [
            [
                1439290800,
                0,
                0
            ],
            [
                1439294400,
                449685,
                22485365
            ],
            [
                1439298000,
                437260,
                21864645
            ],
            [
                1439301600,
                430150,
                21509335
            ],
            [
                1439305200,
                429335,
                21468070
            ]
        ],
        "VN": [
            [
                1439290800,
                0,
                0
            ],
            [
                1439294400,
                196060,
                9804735
            ],
            [
                1439298000,
                190655,
                9534070
            ],
            [
                1439301600,
                187550,
                9379120
            ],
            [
                1439305200,
                187185,
                9361135
            ]
        ]
    }
}

Bytes served

Returns stats with bytes served. The data is for particular time period and grouped in time intervals.
GET https://api.ucdn.com/v3/reports/bytes/[?from=...][&to=...][&zones=1,2,3][&by=hour]
This item returns the following information
Name Flags Description
elements array An array with the generated data. Every element in the array represents a time slot. See the `element_description` field for for information on what it is made of.
element_duration int Lenght of tht time interval for each element. In seconds.
element_description array Every element in `elements` is an array of values. This fields says what does each value in an element mean.
This request returns one of the following messages
Status Flags Description
200 object Reports data
400 string Fail message
532 string Fail message
This request expects the following parameters
Name Flags Validation Default Description
from string Valid formats are: YYYY-MM-DD HH:mm with optional timezone parameter or a Unix timestamp. Examples: 2014-03-12 15:32 GMT+3, 1394571600 24 hours ago From which date to generate the reports
to string Valid formats are: YYYY-MM-DD HH:mm with optional timezone parameter or a Unix timestamp. Examples: 2014-03-12 15:32 GMT+3, 1394571600 now To which date to generate the reports
zones string A zone id or a list of zone ids separated with comma. Example: 1,2,3,4 All zones for this account Filter output for user zones. This way a report for particular zone or a group of zones can be made.
by string One of to following: 5min, hour, day hour Group the reported elements in slots with particular time length.


Examples

curl -X GET "https://api.ucdn.com/v3/reports/bytes/?from=2015-08-12&to=2015-08-13&token=a1cceef964910f10947c09257e87ca40&zones=1,3"
HTTP/1.1 200 OK
Date: Wed, 12 Aug 2015 13:21:35 GMT
Server: Apache
Vary: Accept-Encoding
Content-Length: 602
Content-Type: application/json; charset=utf-8

{
    "element_description": [
        "unix timestamp of the time slot start",
        "bytes served in this time slot"
    ],
    "element_duration": 3600,
    "elements": [
        [
            1439337600,
            0
        ],
        [
            1439341200,
            105885510745
        ],
        [
            1439344800,
            114271292947
        ],
        [
            1439348400,
            124036006918
        ],
        [
            1439352000,
            120396189741
        ],
        [
            1439355600,
            101645584874
        ],
        [
            1439359200,
            80206732783
        ],
        [
            1439362800,
            69543285192
        ],
        [
            1439366400,
            68522904965
        ],
        [
            1439370000,
            73195626735
        ],
        [
            1439373600,
            67897186868
        ],
        [
            1439377200,
            0
        ],
        [
            1439380800,
            0
        ],
        [
            1439384400,
            0
        ],
        [
            1439388000,
            0
        ],
        [
            1439391600,
            0
        ],
        [
            1439395200,
            0
        ],
        [
            1439398800,
            0
        ],
        [
            1439402400,
            0
        ],
        [
            1439406000,
            0
        ],
        [
            1439409600,
            0
        ],
        [
            1439413200,
            0
        ],
        [
            1439416800,
            0
        ],
        [
            1439420400,
            0
        ]
    ]
}

Bytes served via HTTP2

Returns stats with bytes served. The data is for particular time period and grouped in time intervals.
GET https://api.ucdn.com/v3/reports/bytes/http2[?from=...][&to=...][&zones=1,2,3][&by=hour]
This item returns the following information
Name Flags Description
elements array An array with the generated data. Every element in the array represents a time slot. See the `element_description` field for for information on what it is made of.
element_duration int Lenght of tht time interval for each element. In seconds.
element_description array Every element in `elements` is an array of values. This fields says what does each value in an element mean.
This request returns one of the following messages
Status Flags Description
200 object Reports data
400 string Fail message
532 string Fail message
This request expects the following parameters
Name Flags Validation Default Description
from string Valid formats are: YYYY-MM-DD HH:mm with optional timezone parameter or a Unix timestamp. Examples: 2014-03-12 15:32 GMT+3, 1394571600 24 hours ago From which date to generate the reports
to string Valid formats are: YYYY-MM-DD HH:mm with optional timezone parameter or a Unix timestamp. Examples: 2014-03-12 15:32 GMT+3, 1394571600 now To which date to generate the reports
zones string A zone id or a list of zone ids separated with comma. Example: 1,2,3,4 All zones for this account Filter output for user zones. This way a report for particular zone or a group of zones can be made.
by string One of to following: 5min, hour, day hour Group the reported elements in slots with particular time length.


Examples

curl -X GET 'https://api.ucdn.com/v3/reports/bytes/http2?from=2024-02-26&to=2024-02-27&zones=1,2,3&by=hour&token=acf0230d03f5b71d7252e336106f7338'
{
    "element_description": [
        "unix timestamp of the time slot start",
        "bytes served in this time slot"
    ],
    "element_duration": 3600,
    "elements": [
        [
            1708905600,
            0
        ],
        [
            1708909200,
            0
        ],
        [
            1708912800,
            0
        ],
        [
            1708916400,
            0
        ],
        [
            1708920000,
            0
        ],
        [
            1708923600,
            0
        ],
        [
            1708945200,
            0
        ],
        [
            1708948800,
            0
        ],
        [
            1708952400,
            0
        ],
        [
            1708956000,
            0
        ],
        [
            1708959600,
            0
        ],
        [
            1708963200,
            0
        ],
        [
            1708966800,
            0
        ],
        [
            1708970400,
            0
        ]
    ]
}

Hits via HTTP2

Returns total number of hits. The data is for particular time period and grouped in time intervals.
GET https://api.ucdn.com/v3/reports/hits/http2[?from=...][&to=...][&zones=1,2,3][&by=hour]
This item returns the following information
Name Flags Description
elements array An array with the generated data. Every element in the array represents a time slot. See the `element_description` field for for information on what it is made of.
element_duration int Lenght of tht time interval for each element. In seconds.
element_description array Every element in `elements` is an array of values. This fields says what does each value in an element mean.
This request returns one of the following messages
Status Flags Description
200 object Reports data
400 string Fail message
532 string Fail message
This request expects the following parameters
Name Flags Validation Default Description
from string Valid formats are: YYYY-MM-DD HH:mm with optional timezone parameter or a Unix timestamp. Examples: 2014-03-12 15:32 GMT+3, 1394571600 24 hours ago From which date to generate the reports
to string Valid formats are: YYYY-MM-DD HH:mm with optional timezone parameter or a Unix timestamp. Examples: 2014-03-12 15:32 GMT+3, 1394571600 now To which date to generate the reports
zones string A zone id or a list of zone ids separated with comma. Example: 1,2,3,4 All zones for this account Filter output for user zones. This way a report for particular zone or a group of zones can be made.
by string One of to following: 5min, hour, day hour Group the reported elements in slots with particular time length.


Examples

curl -X GET 'https://api.ucdn.com/v3/reports/hits/http2?from=2021-01-03&to=2024-01-03&zones=1&token=acf0230d03f5b71d7252e336106f7338'
{
    "element_description": [
        "unix timestamp of the time slot start",
        "bytes served in this time slot"
    ],
    "element_duration": 3600,
    "elements": [
        [
            1609632000,
            0
        ],
        [
            1609635600,
            0
        ],
        [
            1609639200,
            0
        ],
        [
            1609642800,
            0
        ],
        [
            1609646400,
            0
        ],
        [
            1609650000,
            0
        ],
        [
            1609653600,
            0
        ],
        [
            1609657200,
            0
        ],
        [
            1609660800,
            0
        ],
        [
            1609664400,
            0
        ],
        [
            1609668000,
            0
        ],
        [
            1609671600,
            0
        ],
        [
            1609675200,
            0
        ],
        [
            1609678800,
            0
        ]
    ]
}

Bytes served via SSL

Returns stats with bytes served. The data is for particular time period and grouped in time intervals.
GET https://api.ucdn.com/v3/reports/bytes/ssl[?from=...][&to=...][&zones=1,2,3][&by=hour]
This item returns the following information
Name Flags Description
elements array An array with the generated data. Every element in the array represents a time slot. See the `element_description` field for for information on what it is made of.
element_duration int Lenght of tht time interval for each element. In seconds.
element_description array Every element in `elements` is an array of values. This fields says what does each value in an element mean.
This request returns one of the following messages
Status Flags Description
200 object Reports data
400 string Fail message
532 string Fail message
This request expects the following parameters
Name Flags Validation Default Description
from string Valid formats are: YYYY-MM-DD HH:mm with optional timezone parameter or a Unix timestamp. Examples: 2014-03-12 15:32 GMT+3, 1394571600 24 hours ago From which date to generate the reports
to string Valid formats are: YYYY-MM-DD HH:mm with optional timezone parameter or a Unix timestamp. Examples: 2014-03-12 15:32 GMT+3, 1394571600 now To which date to generate the reports
zones string A zone id or a list of zone ids separated with comma. Example: 1,2,3,4 All zones for this account Filter output for user zones. This way a report for particular zone or a group of zones can be made.
by string One of to following: 5min, hour, day hour Group the reported elements in slots with particular time length.


Examples

curl -X GET 'https://api.ucdn.com/v3/reports/bytes/ssl?from=2021-01-03&to=2024-01-03&zones=1&token=acf0230d03f5b71d7252e336106f7338'
{
    "element_description": [
        "unix timestamp of the time slot start",
        "bytes served in this time slot"
    ],
    "element_duration": 3600,
    "elements": [
        [
            1609632000,
            0
        ],
        [
            1609635600,
            0
        ],
        [
            1609639200,
            0
        ],
        [
            1609642800,
            0
        ],
        [
            1609646400,
            0
        ],
        [
            1609650000,
            0
        ],
        [
            1609653600,
            0
        ],
        [
            1609657200,
            0
        ],
        [
            1609660800,
            0
        ],
        [
            1609664400,
            0
        ],
        [
            1609668000,
            0
        ],
        [
            1609671600,
            0
        ],
        [
            1609675200,
            0
        ],
        [
            1609678800,
            0
        ]
    ]
}

Storages

Returns the used UCDN storage in bytes.
GET https://api.ucdn.com/v3/reports/storages/[?from=...][&to=...][&by=hour]
This item returns the following information
Name Flags Description
elements array An array with the generated data. Every element in the array represents a time slot. See the `element_description` field for for information on what it is made of.
element_duration int Lenght of tht time interval for each element. In seconds.
element_description array Every element in `elements` is an array of values. This fields says what does each value in an element mean.
This request returns one of the following messages
Status Flags Description
200 object Reports data
400 string Fail message
532 string Fail message
This request expects the following parameters
Name Flags Validation Default Description
from string Valid formats are: YYYY-MM-DD HH:mm with optional timezone parameter or a Unix timestamp. Examples: 2014-03-12 15:32 GMT+3, 1394571600 24 hours ago From which date to generate the reports
to string Valid formats are: YYYY-MM-DD HH:mm with optional timezone parameter or a Unix timestamp. Examples: 2014-03-12 15:32 GMT+3, 1394571600 now To which date to generate the reports
by string Only one possible value is supported for now: hour hour Group the reported elements in slots with particular time length.


Examples

curl -X GET "https://api.ucdn.com/v3/reports/storages/?token=a1cceef964910f10947c09257e87ca40"
HTTP/1.1 200 OK
Date: Wed, 12 Aug 2015 11:04:52 GMT
Server: Apache
Vary: Accept-Encoding
Content-Length: 698
Content-Type: application/json; charset=utf-8

{
    "element_description": [
        "unix timestamp of the time slot start",
        "used size in bytes"
    ],
    "element_duration": 3600,
    "elements": [
        [
            1439290800,
            0
        ],
        [
            1439294400,
            2887995255
        ],
        [
            1439298000,
            2887995255
        ],
        [
            1439301600,
            2887995255
        ],
        [
            1439305200,
            2887995255
        ],
        [
            1439308800,
            2887995255
        ],
        [
            1439312400,
            2887995255
        ],
        [
            1439316000,
            2887995255
        ],
        [
            1439319600,
            2887995255
        ],
        [
            1439323200,
            2887995255
        ],
        [
            1439326800,
            2887995255
        ],
        [
            1439330400,
            2887995255
        ],
        [
            1439334000,
            2887995255
        ],
        [
            1439337600,
            2887995255
        ],
        [
            1439341200,
            2887995255
        ],
        [
            1439344800,
            2887995255
        ],
        [
            1439348400,
            2887995255
        ],
        [
            1439352000,
            2887995255
        ],
        [
            1439355600,
            2887995255
        ],
        [
            1439359200,
            2887995255
        ],
        [
            1439362800,
            2887995255
        ],
        [
            1439366400,
            2887995255
        ],
        [
            1439370000,
            2887995255
        ],
        [
            1439373600,
            0
        ],
        [
            1439377200,
            0
        ]
    ]
}

Hits

Returns statistics with the number of HTTP hits
GET https://api.ucdn.com/v3/reports/hits/[?from=...][&to=...][&zones=1,2,3][&by=hour]
This item returns the following information
Name Flags Description
elements array An array with the generated data. Every element in the array represents a time slot. See the `element_description` field for for information on what it is made of.
element_duration int Lenght of tht time interval for each element. In seconds.
element_description array Every element in `elements` is an array of values. This fields says what does each value in an element mean.
This request returns one of the following messages
Status Flags Description
200 object Reports data
400 string Fail message
532 string Fail message
This request expects the following parameters
Name Flags Validation Default Description
from string Valid formats are: YYYY-MM-DD HH:mm with optional timezone parameter or a Unix timestamp. Examples: 2014-03-12 15:32 GMT+3, 1394571600 24 hours ago From which date to generate the reports
to string Valid formats are: YYYY-MM-DD HH:mm with optional timezone parameter or a Unix timestamp. Examples: 2014-03-12 15:32 GMT+3, 1394571600 now To which date to generate the reports
zones string A zone id or a list of zone ids separated with comma. Example: 1,2,3,4 All zones for this account Filter output for user zones. This way a report for particular zone or a group of zones can be made.
by string One of to following: 5min, hour, day hour Group the reported elements in slots with particular time length.


Examples

curl -X GET "https://api.ucdn.com/v3/reports/hits/?token=a1cceef964910f10947c09257e87ca40"
HTTP/1.1 200 OK
Date: Wed, 12 Aug 2015 11:04:50 GMT
Server: Apache
Vary: Accept-Encoding
Content-Length: 602
Content-Type: application/json; charset=utf-8

{
    "element_description": [
        "unix timestamp of the time slot start",
        "hits"
    ],
    "element_duration": 3600,
    "elements": [
        [
            1439290800,
            0
        ],
        [
            1439294400,
            739857
        ],
        [
            1439298000,
            719431
        ],
        [
            1439301600,
            707736
        ],
        [
            1439305200,
            706384
        ],
        [
            1439308800,
            719685
        ],
        [
            1439312400,
            761199
        ],
        [
            1439316000,
            825275
        ],
        [
            1439319600,
            893314
        ],
        [
            1439323200,
            919642
        ],
        [
            1439326800,
            984416
        ],
        [
            1439330400,
            962014
        ],
        [
            1439334000,
            919178
        ],
        [
            1439337600,
            873281
        ],
        [
            1439341200,
            871015
        ],
        [
            1439344800,
            939998
        ],
        [
            1439348400,
            1020329
        ],
        [
            1439352000,
            990386
        ],
        [
            1439355600,
            836136
        ],
        [
            1439359200,
            659778
        ],
        [
            1439362800,
            572053
        ],
        [
            1439366400,
            563661
        ],
        [
            1439370000,
            602095
        ],
        [
            1439373600,
            558520
        ],
        [
            1439377200,
            0
        ]
    ]
}

Hits SSL

Returns total number of hits. The data is for particular time period and grouped in time intervals.
GET https://api.ucdn.com/v3/reports/hits/ssl[?from=...][&to=...][&zones=1,2,3][&by=hour]
This item returns the following information
Name Flags Description
elements array An array with the generated data. Every element in the array represents a time slot. See the `element_description` field for for information on what it is made of.
element_duration int Lenght of tht time interval for each element. In seconds.
element_description array Every element in `elements` is an array of values. This fields says what does each value in an element mean.
This request returns one of the following messages
Status Flags Description
200 object Reports data
400 string Fail message
532 string Fail message
This request expects the following parameters
Name Flags Validation Default Description
from string Valid formats are: YYYY-MM-DD HH:mm with optional timezone parameter or a Unix timestamp. Examples: 2014-03-12 15:32 GMT+3, 1394571600 24 hours ago From which date to generate the reports
to string Valid formats are: YYYY-MM-DD HH:mm with optional timezone parameter or a Unix timestamp. Examples: 2014-03-12 15:32 GMT+3, 1394571600 now To which date to generate the reports
zones string A zone id or a list of zone ids separated with comma. Example: 1,2,3,4 All zones for this account Filter output for user zones. This way a report for particular zone or a group of zones can be made.
by string One of to following: 5min, hour, day hour Group the reported elements in slots with particular time length.


Examples

curl -X GET 'https://api.ucdn.com/v3/reports/hits/ssl?from=2021-01-03&to=2024-01-03&zones=1&token=acf0230d03f5b71d7252e336106f7338'
{
    "element_description": [
        "unix timestamp of the time slot start",
        "bytes served in this time slot"
    ],
    "element_duration": 3600,
    "elements": [
        [
            1609632000,
            0
        ],
        [
            1609635600,
            0
        ],
        [
            1609639200,
            0
        ],
        [
            1609642800,
            0
        ],
        [
            1609646400,
            0
        ],
        [
            1609650000,
            0
        ],
        [
            1609653600,
            0
        ],
        [
            1609657200,
            0
        ],
        [
            1609660800,
            0
        ],
        [
            1609664400,
            0
        ],
        [
            1609668000,
            0
        ],
        [
            1609671600,
            0
        ],
        [
            1609675200,
            0
        ],
        [
            1609678800,
            0
        ]
    ]
}

Status codes

Statistics for HTTP status codes.
GET https://api.ucdn.com/v3/reports/status/codes/[?from=...][&to=...][&zones=1,2,3][&by=hour][&code=301]
This item returns the following information
Name Flags Description
elements object A key-value pairs. The key in the pair is a HTTP status code. The value an array with the generated data. Every element in the array represents a time slot. See the `element_description` field for for information on what it is made of.
element_duration int Lenght of tht time interval for each element. In seconds.
element_description array Every element in `elements` is an array of values. This fields says what does each value in an element mean.
This request returns one of the following messages
Status Flags Description
200 object Reports data
400 string Fail message
532 string Fail message
This request expects the following parameters
Name Flags Validation Default Description
from string Valid formats are: YYYY-MM-DD HH:mm with optional timezone parameter or a Unix timestamp. Examples: 2014-03-12 15:32 GMT+3, 1394571600 24 hours ago From which date to generate the reports
to string Valid formats are: YYYY-MM-DD HH:mm with optional timezone parameter or a Unix timestamp. Examples: 2014-03-12 15:32 GMT+3, 1394571600 now To which date to generate the reports
zones string A zone id or a list of zone ids separated with comma. Example: 1,2,3,4 All zones for this account Filter output for user zones. This way a report for particular zone or a group of zones can be made.
by string One of to following: 5min, hour, day hour Group the reported elements in slots with particular time length.
code string Integer. Represents a HTTP status code between 100 and 599. All status codes. Show staistics for particular HTTP status code.


Examples

curl -X GET "https://api.ucdn.com/v3/reports/status/codes/?from=2015-08-12&to=2015-08-13&token=a1cceef964910f10947c09257e87ca40&code=404"
HTTP/1.1 200 OK
Date: Wed, 12 Aug 2015 13:21:34 GMT
Server: Apache
Vary: Accept-Encoding
Content-Length: 643
Content-Type: application/json; charset=utf-8

{
    "element_description": [
        "unix timestamp of the time slot start",
        "hits",
        "percents of all"
    ],
    "element_duration": 3600,
    "elements": {
        "404": [
            [
                1439337600,
                0,
                0
            ],
            [
                1439341200,
                181058,
                0
            ],
            [
                1439344800,
                195398,
                0
            ],
            [
                1439348400,
                212096,
                0
            ],
            [
                1439352000,
                205871,
                0
            ],
            [
                1439355600,
                173808,
                0
            ],
            [
                1439359200,
                137148,
                0
            ],
            [
                1439362800,
                118913,
                0
            ],
            [
                1439366400,
                117169,
                0
            ],
            [
                1439370000,
                125157,
                0
            ],
            [
                1439373600,
                116099,
                0
            ],
            [
                1439377200,
                0,
                0
            ],
            [
                1439380800,
                0,
                0
            ],
            [
                1439384400,
                0,
                0
            ],
            [
                1439388000,
                0,
                0
            ],
            [
                1439391600,
                0,
                0
            ],
            [
                1439395200,
                0,
                0
            ],
            [
                1439398800,
                0,
                0
            ],
            [
                1439402400,
                0,
                0
            ],
            [
                1439406000,
                0,
                0
            ],
            [
                1439409600,
                0,
                0
            ],
            [
                1439413200,
                0,
                0
            ],
            [
                1439416800,
                0,
                0
            ],
            [
                1439420400,
                0,
                0
            ]
        ]
    }
}

Cache

Purge files

Removes files from a cache zone. This call will create a purge job which will be executed atomically.
POST https://api.ucdn.com/v3/purge/zone/{zone_id}/
This item returns the following information
Name Flags Description
job_id string The ID of the newly created purge job
This request returns one of the following messages
Status Flags Description
204 json Success message
532 json Fail message
This request expects the following parameters
Name Flags Validation Default Description
files string You can use either http://example.com/dir/file.txt or /dir/file.txt A list of files separated by a new line


Examples

curl --include --request POST "https://api.ucdn.com/v3/purge/zone/1/?token=a1cceef964910f10947c09257e87ca40" --header "Content-Type: application/json" -d '{"files":"/example/logo.png\n/second/file"}'
HTTP/1.1 200 OK
Date: Wed, 12 Aug 2015 13:21:34 GMT
Server: Apache
Vary: Accept-Encoding
Content-Length: 80
Content-Type: application/json; charset=utf-8

{
    "message": "Purge request received",
    "job_id": "3cfb478531097f1830056a828752cbdd"
}

View purge job

Returns information for particular purge job.
GET https://api.ucdn.com/v3/purge/job/{job_id}/
This item returns the following information
Name Flags Description
job_id string The ID of this purge job
files array List of file which make up this purge job
status string The status of this purge job. It can be "waiting", "running", "finished" or "failed"
created_at int The time this job was created in Unix timestamp
This request returns one of the following messages
Status Flags Description
200 string Success message
532 string Fail message
This request expects the following parameters
Name Flags Validation Default Description
job_id string - A purge job id as returned by the job creation call


Examples

curl -X GET "https://api.ucdn.com/v3/purge/job/2170dd23decc45691adf28987282d0bc/?token=a1cceef964910f10947c09257e87ca40"
HTTP/1.1 200 OK
Date: Wed, 12 Aug 2015 13:21:33 GMT
Server: Apache
Vary: Accept-Encoding
Content-Length: 210
Content-Type: application/json; charset=utf-8

{
    "job_id": "2170dd23decc45691adf28987282d0bc",
    "files": [
        "http:\/\/a1-121.so.clients.cdn13.com\/example\/logo.png",
        "http:\/\/a1-121.so.clients.cdn13.com\/second\/file"
    ],
    "status": "finished",
    "created_at": 1435318980
}

List purge jobs

Returns an array with the latest purge jobs.
GET https://api.ucdn.com/v3/purge/[?status=...][&count=...]
This request returns one of the following messages
Status Flags Description
200 array Array with purge jobs
532 string Fail message
This request expects the following parameters
Name Flags Validation Default Description
status string required Supported values are "waiting", "running", "finished" and "failed" Will show "waiting", "running" and "failed" purge jobs only Return only purge jobs which are in this status.
count integer Positive integer less or equal to 500 20 How many purge jobs to return


Examples

curl -X GET "https://api.ucdn.com/v3/purge/?status=finished&token=a1cceef964910f10947c09257e87ca40"
HTTP/1.1 200 OK
Date: Wed, 12 Aug 2015 13:21:33 GMT
Server: Apache
Vary: Accept-Encoding
Content-Length: 1900
Content-Type: application/json; charset=utf-8

[
    {
        "job_id": "ed74f89ab1469b4942fa6fee32832c31",
        "files": [
            "http:\/\/a1-121.so.clients.cdn13.com\/example\/logo.png",
            "http:\/\/a1-121.so.clients.cdn13.com\/second\/file"
        ],
        "status": "finished",
        "created_at": 1439377493
    },
    {
        "job_id": "58432bcd7c38551ab1c3552315962a39",
        "files": [
            "http:\/\/a1-121.so.clients.cdn13.com\/example\/logo.png",
            "http:\/\/a1-121.so.clients.cdn13.com\/second\/file"
        ],
        "status": "finished",
        "created_at": 1435565013
    },
    {
        "job_id": "ae2f114aa4ee1940fe960a2dca2d2d4d",
        "files": [
            "http:\/\/a1-121.so.clients.cdn13.com\/example\/logo.png",
            "http:\/\/a1-121.so.clients.cdn13.com\/second\/file"
        ],
        "status": "finished",
        "created_at": 1435564159
    },
    {
        "job_id": "e2a311eaaf6408621c6ba10d37b0a17f",
        "files": [
            "http:\/\/a1-121.so.clients.cdn13.com\/example\/logo.png",
            "http:\/\/a1-121.so.clients.cdn13.com\/second\/file"
        ],
        "status": "finished",
        "created_at": 1435564105
    },
    {
        "job_id": "2170dd23decc45691adf28987282d0bc",
        "files": [
            "http:\/\/a1-121.so.clients.cdn13.com\/example\/logo.png",
            "http:\/\/a1-121.so.clients.cdn13.com\/second\/file"
        ],
        "status": "finished",
        "created_at": 1435318980
    },
    {
        "job_id": "cd704ed605964e55a2a3c64162f94b05",
        "files": [
            "http:\/\/a1-121.so.clients.cdn13.com\/example\/logo.png",
            "http:\/\/a1-121.so.clients.cdn13.com\/second\/file"
        ],
        "status": "finished",
        "created_at": 1435317428
    },
    {
        "job_id": "a301e0571b0402a5fca1b6271612612b",
        "files": [
            "http:\/\/a1-121.so.clients.cdn13.com\/example\/logo.png",
            "http:\/\/a1-121.so.clients.cdn13.com\/second\/file"
        ],
        "status": "finished",
        "created_at": 1435317395
    },
    {
        "job_id": "9dfb57172bbbdc33abeb66862bb995d4",
        "files": [
            "http:\/\/a1-121.so.clients.cdn13.com\/example\/logo.png",
            "http:\/\/a1-121.so.clients.cdn13.com\/second\/file"
        ],
        "status": "finished",
        "created_at": 1435317350
    },
    {
        "job_id": "72709f187f5b5759d1db5055ac3c1340",
        "files": [
            "http:\/\/a1-121.so.clients.cdn13.com\/example\/logo.png",
            "http:\/\/a1-121.so.clients.cdn13.com\/second\/file"
        ],
        "status": "finished",
        "created_at": 1435317296
    }
]

Delete a purge job

Removes a purge job. Note that only purge jobs which are waiting or finished can be deleted.
DELETE https://api.ucdn.com/v3/purge/job/{job_id}
This request returns one of the following messages
Status Flags Description
200 string Success message
532 string Fail message
This request expects the following parameters
Name Flags Validation Default Description
job_id string - A purge job id as returned by the job creation call


Examples

curl --include --request DELETE "https://api.ucdn.com/v3/purge/job/cd704ed605964e55a2a3c64162f94b05/?token=a1cceef964910f10947c09257e87ca40"
HTTP/1.1 200 OK
Date: Wed, 12 Aug 2015 13:21:40 GMT
Server: Apache
Vary: Accept-Encoding
Content-Length: 39
Content-Type: application/json; charset=utf-8

{
    "message": "The purge job was removed"
}

Storage

Create storage

Creates a new UCDN storage and returns its ID on success. The storage will be ready for uploading files and general use but still not attached to any cache zone. See zone creation and reconfiguration API calls for details on how to use particular UCDN storage.
POST https://api.ucdn.com/v3/storage
This item returns the following information
Name Flags Description
id int The id of the created storage
status string Operation success message
This request returns one of the following messages
Status Flags Description
200 json Message for successful creation
532 json Error message
504 json Storage backend failed
This request expects the following parameters
Name Flags Validation Default Description
name string required At least 3 characters long identifier. Name wihch will be used for the swift container.
region string required "europe" or "north-america". The geographical region of this container.


Examples

curl -X POST "https://api.ucdn.com/v3/storage/?token=acf0230d03f5b71d7252e336106f7338" --header "Content-Type: application/json" -d '{"region":"north-america", "name": "level-4-logs"}'
HTTP/1.1 200 OK
Date: Mon, 29 Jun 2015 08:10:29 GMT
Server: Apache
X-Powered-By: PHP/5.6.8-pl0-gentoo
Vary: Accept-Encoding
Content-Length: 36
Content-Type: application/json; charset=utf-8

{
    "message": "Storage Created",
    "id": 3
}

List storages

Returns a list with all of your UCDN storages. For every storage in the list there is a object with information for it.
GET https://api.ucdn.com/v3/storages
This item returns the following information
Name Flags Description
id int The identificator of this storage instance
container string The name of this storage
ftp_host string FTP host for this storage
ftp_user string FTP user for this storage
ftp_password string FTP password for this storage
region string The geo region this storage is in
synchronized_with_storage string Id of a storage which is synchronized with this one if there is one.
This request returns one of the following messages
Status Flags Description
200 array Array with information for all storages
532 json Error message

Examples

curl -X GET "https://api.ucdn.com/v3/storages/?token=acf0230d03f5b71d7252e336106f7338"
HTTP/1.1 200 OK
Date: Mon, 29 Jun 2015 08:03:11 GMT
Server: Apache
X-Powered-By: PHP/5.3.10-1ubuntu3.16
X-Cache: miss
Vary: Accept-Encoding
Content-Length: 388
Content-Type: application/json; charset=utf-8

[
    {
        "id": 2,
        "container": "despensable",
        "ftp_host": "europe.upload.cdn13.com",
        "ftp_user": "1000121.1000121",
        "ftp_password": "ftppassword",
        "region": "europe",
        "synchronized_with_storage": null
    },
    {
        "id": 1,
        "container": "level-3-logs",
        "ftp_host": "north-america.upload.cdn13.com",
        "ftp_user": "1000121.1000121",
        "ftp_password": "ftppassword",
        "region": "north-america",
        "synchronized_with_storage": null
    }
]

Reconfigure storages

This API call makes possible changing the settings for all storages in particular region. Different values of the `action` parameter mean different operations to be performed.
PATCH https://api.ucdn.com/v3/storages
This item returns the following information
Name Flags Description
new_ftp_password string The new FTP password which must be used with storages in the patched region. Will be returned only if the `action` request parameter is "change_ftp_password".
message string Success message
This request returns one of the following messages
Status Flags Description
200 object Relevant information for the successful `action`
400 string Something wrong with the request
409 string Insufficient parameters
504 string Storage backend errors
532 string Fail message
This request expects the following parameters
Name Flags Validation Default Description
region string required "europe" or "north-america". The region in which will storages be patched.
action string required Only "change_ftp_password" is supported for now. With it, all storages in the region will have their FTP passwords changed. Tells what will this reconfiguration do.


Examples

curl -X PATCH "https://api.ucdn.com/v3/storages/?token=jasdhjshad234234jh" --header "Content-Type: application/json" -d '{"action":"change_ftp_password", "region": "north-america"}'
HTTP/1.1 200 OK
Date: Tue, 24 Nov 2015 11:03:39 GMT
Server: Apache/2.4.7 (Ubuntu)
X-Powered-By: PHP/5.5.9-1ubuntu4.14
Content-Length: 41
Content-Type: application/json; charset=utf-8

{
    "new_ftp_password": "dd9028f5f3ed79408e"
}

Storage FTP

Returns information for a particular UCDN storage.
GET https://api.ucdn.com/v3/storage/{id}
This item returns the following information
Name Flags Description
id int The identificator of this storage instance
container string The name of this storage
ftp_host string FTP host for this storage
ftp_user string FTP user for this storage
ftp_password string FTP password for this storage
region string The geo region this storage is in
synchronized_with_storage string Id of a storage which is synchronized with this one if there is one.
This request returns one of the following messages
Status Flags Description
200 json Information for this storage
404 json No active storage found message
532 json Error message

Examples

curl -X GET "https://api.ucdn.com/v3/storage/1/?token=acf0230d03f5b71d7252e336106f7338"
HTTP/1.1 200 OK
Date: Mon, 29 Jun 2015 08:03:12 GMT
Server: Apache
X-Powered-By: PHP/5.6.8-pl0-gentoo
X-Cache: hit
Vary: Accept-Encoding
Content-Length: 200
Content-Type: application/json; charset=utf-8

{
    "id": 1,
    "container": "level-3-logs",
    "ftp_host": "north-america.upload.cdn13.com",
    "ftp_user": "1000121.1000121",
    "ftp_password": "ftppassword",
    "region": "north-america",
    "synchronized_with_storage": null
}

Storage consumed size

Returns utilisation information for this storage. How big it is and how many objects there are.
GET https://api.ucdn.com/v3/storage/{id}/size
This item returns the following information
Name Flags Description
bytes int Number of bytes consumed on this storage
objects int Number files and folders on this storage
This request returns one of the following messages
Status Flags Description
200 json Consumed size
404 json No active storage found message
532 json Error message

Examples

curl -X GET "https://api.ucdn.com/v3/storage/1/size/?token=acf0230d03f5b71d7252e336106f7338"
HTTP/1.1 200 OK
Date: Mon, 29 Jun 2015 08:03:11 GMT
Server: Apache
X-Powered-By: PHP/5.3.10-1ubuntu3.16
X-Cache: miss
Vary: Accept-Encoding
Content-Length: 23
Content-Type: application/json; charset=utf-8

{
    "bytes": 0,
    "objects": 0
}

Remove storage

Removes an UCDN storage. To remove a storage there are few preconditions: it must be empty and there must be no cache zone using it as its origin.
DELETE https://api.ucdn.com/v3/storage/{id}
This request returns one of the following messages
Status Flags Description
200 json Message for successful deletion
404 json No active storage found message
532 json Error message
504 json Storage backend failed

Examples

curl -X DELETE "https://api.ucdn.com/v3/storage/2/?token=acf0230d03f5b71d7252e336106f7338"
HTTP/1.1 200 OK
Date: Mon, 29 Jun 2015 08:10:35 GMT
Server: Apache
X-Powered-By: PHP/5.6.8-pl0-gentoo
Vary: Accept-Encoding
Content-Length: 33
Content-Type: application/json; charset=utf-8

{
    "message": "Storage was deleted"
}

Login

Check user credentials

Checks if a email and password pair belong to a valid user and returns its ID if they do. By saying "email" we actually mean "username or email". Both will work for logging in.
POST https://api.ucdn.com/v3/check/login/
This item returns the following information
Name Flags Description
authenticated bool True if the credentials are valid or false otherwise
user_id int The user ID of the user for which the credentials matched. Only present in successful logins.
reason string Huaman readable sentence explaining the result from this call
token string The token for this user needed for authenticating against the Public API. Only present in successful logins.
This request returns one of the following messages
Status Flags Description
200 string Message
401 string Invalid login credentials
532 string An error message
This request expects the following parameters
Name Flags Validation Default Description
email string required The email with which this user has been registered Email supplied by the user
password string required The password for this user Password supplied by the user


Examples

curl -X POST "https://api.ucdn.com/v3/check/login/" --header "Content-Type: application/json" -d '{"email":"major@section9.co.jp", "password": "password"}'
HTTP/1.1 200 OK
Date: Mon, 29 Jun 2015 08:03:16 GMT
Server: Apache
X-Powered-By: PHP/5.6.8-pl0-gentoo
Vary: Accept-Encoding
Content-Length: 118
Content-Type: application/json; charset=utf-8

{
    "authenticated": true,
    "user_id": 121,
    "reason": "Login credentials are valid",
    "token": "acf0230d03f5b71d7252e336106f7338"
}

Account

Fetch account info

Returns information for your current account.
GET https://api.ucdn.com/v3/account
This item returns the following information
Name Flags Description
id int Your unique user ID
username string Your username
name string Your name
email string This account contact email
timezone string Timezone for the Control Panel reports
trial int Whether this account is part of the UCDN Free trial program
This request returns one of the following messages
Status Flags Description
200 object Account Information

Examples

curl -X GET "https://api.ucdn.com/v3/account/?token=acf0230d03f5b71d7252e336106f7338"
HTTP/1.1 200 OK
Date: Mon, 29 Jun 2015 08:03:08 GMT
Server: Apache
X-Powered-By: PHP/5.3.10-1ubuntu3.16
X-Cache: miss
Vary: Accept-Encoding
Content-Length: 127
Content-Type: application/json; charset=utf-8

{
    "id": "121",
    "username": "kusanagi",
    "email": "major@section9.co.jp",
    "name": "Motoko Kusanagi",
    "timezone": "Asia\/Tokyo",
    "trial": "0"
}

Fetch subaccounts list

Returns all accounts with the same parent id as for your current account.
GET https://api.ucdn.com/v3/subaccounts
This request returns one of the following messages
Status Flags Description
200 object Account Information

Examples

curl -X GET "https://api.ucdn.com/v3/subaccounts/?token=acf0230d03f5b71d7252e336106f7338"
{
      "address" : null,
      "api_key" : "acf0230d03f5b71d7252e336106f7338",
      "api_secret" : "e2425f9c4df5614821009bce90cc384a",
      "billing_currency" : "USD",
      "billing_methodology" : "bandwidth",
      "bonus_balance" : "0.00000000",
      "cache_objects" : "873813",
      "cache_quota" : "0",
      "can_be_suspend" : "1",
      "check_origin" : "1",
      "city" : null,
      "company_name" : null,
      "company_type" : "corporate",
      "confirmed_mail" : "1",
      "country" : null,
      "create_ts" : "1708416831",
      "delete_ts" : "0",
      "domain_base" : "cdn13.com",
      "email" : "test_email@gmail.com",
      "expiration_2fa" : null,
      "first_name" : null,
      "id" : "13956",
      "l2_cache_objects" : "500000",
      "l2_cache_objects_small" : "1000000",
      "l2_cache_quota" : "0",
      "l2_cache_quota_small" : "0",
      "l3_cache_objects" : "1000000",
      "l3_cache_objects_small" : "2000000",
      "l3_cache_quota" : "0",
      "l3_cache_quota_small" : "0",
      "last_name" : null,
      "last_updated" : "2024-02-20 08:13:51",
      "manager_id" : "0",
      "max_zones" : "512",
      "name" : "test123",
      "notes" : null,
      "origin_quota" : "0",
      "parent_id" : "13863",
      "password" : "$2y$11$y6NtNjdaeTKKx.SGAPbjm.qhECzOI5KVNcaCDxkLaHOfaeTDWbYMu",
      "payment_method" : "9",
      "secret_key_2fa" : null,
      "state" : null,
      "status" : "active",
      "storage_price" : "0.000000",
      "suspended" : "0",
      "suspended_for_payment" : "0",
      "tax_info" : null,
      "timezone" : "Europe/London",
      "traffic_bps" : "0",
      "trial" : "0",
      "type_2fa" : null,
      "type_switch_ts" : "0",
      "update_ts" : "1708416831",
      "username" : "test123",
      "zip_code" : null
}

Zone

Fetch all zones

Returns a list with all of your zones. Every zone in the list is a object with the same informations as the Fetch a zone call.
GET https://api.ucdn.com/v3/zones
This item returns the following information
Name Flags Description
* array A list of your zones
This request returns one of the following messages
Status Flags Description
200 array A list of zones
This request supports the following helpers
Name Description
count Returns the count of your zones

Examples

curl --include --request GET "https://api.ucdn.com/v3/zones/?token=acf0230d03f5b71d7252e336106f7338"
HTTP/1.1 200 OK
Date: Mon, 29 Jun 2015 08:03:10 GMT
Server: Apache
X-Powered-By: PHP/5.3.10-1ubuntu3.16
X-Cache: miss
Vary: Accept-Encoding
Content-Length: 1594
Content-Type: application/json; charset=utf-8

[
    {
        "id": "1",
        "cdn_domain": "a1-121.so.clients.cdn13.com",
        "object_size": "small",
        "upstream": {
            "endpoints": [
                {
                    "host": "news.com",
                    "port": 80
                }
            ],
            "type": "own",
            "proto": "http",
            "host_header": "news.com",
            "auth": {
                "type": "none"
            }
        },
        "is_active": "1",
        "create_ts": "1423139335",
        "update_ts": "1435564990",
        "storage_id": null,
        "error_pages": [],
        "referers": [],
        "geo_filter": [],
        "limit_rate": [],
        "custom_domains": [
            "cdn.section9.com"
        ],
        "cache_reuse_from": null,
        "expiration": 3600,
        "hash_secret": null,
        "hash_algorithm": null,
        "hash_ttl": null,
        "reconfig_status": "reconfiguring"
    },
    {
        "id": "3",
        "cdn_domain": "a3-121.so.clients.cdn13.com",
        "object_size": "small",
        "upstream": {
            "endpoints": [
                {
                    "host": "test.com",
                    "port": 80
                }
            ],
            "type": "own",
            "proto": "http",
            "host_header": "test.com",
            "auth": {
                "type": "none"
            }
        },
        "is_active": "1",
        "create_ts": "1429620438",
        "update_ts": "1429620438",
        "storage_id": null,
        "error_pages": [],
        "referers": [],
        "geo_filter": [],
        "limit_rate": [],
        "custom_domains": [],
        "cache_reuse_from": null,
        "expiration": null,
        "hash_secret": null,
        "hash_algorithm": null,
        "hash_ttl": null,
        "reconfig_status": "ready"
    },
    {
        "id": "4",
        "cdn_domain": "a4-121.so.clients.cdn13.com",
        "object_size": "small",
        "upstream": {
            "endpoints": [
                {
                    "host": "test.com",
                    "port": 443
                }
            ],
            "type": "own",
            "proto": "https",
            "host_header": "test.com",
            "auth": {
                "type": "none"
            }
        },
        "is_active": "1",
        "create_ts": "1435316148",
        "update_ts": "1435316148",
        "storage_id": null,
        "error_pages": [],
        "referers": [],
        "geo_filter": [],
        "limit_rate": [],
        "custom_domains": [],
        "cache_reuse_from": null,
        "expiration": null,
        "hash_secret": null,
        "hash_algorithm": null,
        "hash_ttl": null,
        "reconfig_status": "ready"
    }
]

Fetch a zone

Returns information for a particular cache zone as an object. Few of the fields can be `null`. This indicates that the feature they signify is off.
GET https://api.ucdn.com/v3/zone/{zone_id}
This item returns the following information
Name Flags Description
id int This zone ID
cdn_domain string Unique domain name with which you can access your files
object_size string File size for this zone. Small (= 20MB)
is_active int Whether this zone is enabled (1) or disabled (0)
error_pages object Custom error pages activated for this zone
upstream object Upstream for this zone(where to pull files from)
referers array Allowed referers for files in this zone
geo_filter object Geo filtering configuration
limit_rate object Limit rates configuration
custom_domains array Array with custom domains for this zone. They must be CNAMEs this zone's cdn_domain
cache_reuse_from int zone_id of the zone this account reuses cache from
expiration int Forced expiration time of files in this zone
hash_secret string Security token's secret key
hash_algorithm string They hashing algorithm with which the security token is hashed
hash_ttl int Number of seconds for which URLs generated with security token work
create_ts int Unix time of the moment this zone was created
update_ts int Unix time. Last time this zone was edited in any way
storage_id int If this zone uses UCDN Storage as its origin, this is the ID of this storage
This request returns one of the following messages
Status Flags Description
200 object Information for thsi zone

Examples

curl --include --request GET "https://api.ucdn.com/v3/zone/1/?token=acf0230d03f5b71d7252e336106f7338"
HTTP/1.1 200 OK
Date: Mon, 29 Jun 2015 08:03:09 GMT
Server: Apache
X-Powered-By: PHP/5.3.10-1ubuntu3.16
X-Cache: miss
Vary: Accept-Encoding
Content-Length: 538
Content-Type: application/json; charset=utf-8

{
    "id": "1",
    "cdn_domain": "a1-121-so.ssl.cdn13.com",
    "object_size": "small",
    "upstream": {
        "endpoints": [
            {
                "host": "news.com",
                "port": 80
            }
        ],
        "type": "own",
        "proto": "http",
        "host_header": "news.com",
        "auth": {
            "type": "none"
        }
    },
    "is_active": "1",
    "create_ts": "1423139335",
    "update_ts": "1435564989",
    "storage_id": null,
    "error_pages": {},
    "referers": [],
    "geo_filter": [],
    "limit_rate": [],
    "custom_domains": [
        "cdn.section9.com"
    ],
    "cache_reuse_from": null,
    "expiration": 3600,
    "ssl_type": "own",
    "hash_secret": null,
    "hash_algorithm": null,
    "hash_ttl": null,
    "reconfig_status": "reconfiguring"
}

Create a new zone

With this API call you can create a new cache zone. The only required parameters are `upstream` and `object_size`. With the first one you can control the location of the files for this cache zone and with the second you tell us if they are big files or small. Picking good `object_size` may be the difference between fast cache and almost no cache at all. For every other parameter check their description.
POST https://api.ucdn.com/v3/zone
This item returns the following information
Name Flags Description
zone_id int The ID of the newly created zone
This request returns one of the following messages
Status Flags Description
200 json The new zone's id
532 json An error message
This request expects the following parameters
Name Flags Validation Default Description
object_size required string big
small 		File size for this zone. Small objects are those less than 20MB
upstream required object valid upstream object Discribes where to pull files from. See the example for more info.
custom_domains string array domain,domain,domain... Custom domains for your zone. They must be CNAMEs to this zone's cdn_domain. This field does not have any effect when using shared SSL.
error_pages string array status:url Custom URLs to besed for redirecting from various HTTP error statuses (e.g. 404)
referers string array valid domains Allow access only from certain referers
geo_filter_allow string array ISO 3166-1 country code Allow access only from certain countries
geo_filter_deny string array ISO 3166-1 country code Deny access to certain countries
limit_rate_global string NNk, e.g. 20k Limit rate for every connection in this zone. It is mutually exclusive with limit_rate_security
limit_rate_security string on
off 		Use security token's limit rate. It is mutually exclusive with limit_rate_global
hash_secret string valid url query string Access security token, used in conjuction with hash_algorithm and hash_ttl
hash_algorithm string md5
sha1 		Hashing algorithm of the security token
hash_ttl integer in seconds Time to live of the security token hash
cache_reuse_from integer valid zone id Zone id of another zone. You cane use it to force this zone into using the other's cache.
expiration integer in seconds Forced cache expiration in seconds. When this is set expire and cache-control headers from the origin are ignored


Examples

## Zone with own origin
curl --include --request POST "https://api.ucdn.com/v3/zone/?token=acf0230d03f5b71d7252e336106f7338" --header "Content-Type: application/json" -d '{"object_size":"small", "upstream":{"endpoints":[{"host":"news.com","port":80}],"type":"own","proto":"http","host_header":"news.com","auth":{"type":"none"}}}'

## Zone with own origin and basic auth
curl --include --request POST "https://api.ucdn.com/v3/zone/?token=acf0230d03f5b71d7252e336106f7338" --header "Content-Type: application/json" -d '{"object_size":"small", "upstream":{"endpoints":[{"host":"news.com","port":80}],"type":"own","proto":"http","host_header":"news.com","auth":{"type":"http_basic", "username":"a", "password": "b"}}}'

## Zone with aws origin and signing key auth
curl --include --request POST "https://api.ucdn.com/v3/zone/?token=acf0230d03f5b71d7252e336106f7338" --header "Content-Type: application/json" -d '{"object_size":"small", "upstream":{"endpoints":[{"host":"s3.eu-central-1.domain.com"}],"type":"aws-s3","proto":"http","auth":{"type":"aws_signing_key","access_key":"examplekey","key_scope":"example_scope","signing_key":"skey1"}}}'

## Zone with aws origin and secret key auth
curl --include --request POST "https://api.ucdn.com/v3/zone/?token=acf0230d03f5b71d7252e336106f7338" --header "Content-Type: application/json" -d '{"object_size":"small", "upstream":{"endpoints":[{"host":"s3.eu-central-1.domain.com", "bucket":"test","region":"test"}],"type":"aws-s3","proto":"http","auth":{"type":"aws_secret_key","access_key":"examplekey","secret_key":"skey1"}}}'
HTTP/1.1 200 OK
Date: Mon, 29 Jun 2015 08:10:37 GMT
Server: Apache
X-Powered-By: PHP/5.3.10-1ubuntu3.16
X-Cache: miss
Vary: Accept-Encoding
Content-Length: 13
Content-Type: application/json; charset=utf-8

{
    "zone_id": 5
}

Replace a zone configuration

Using this API call you can completely replace a zone configuration. It work just like creating new zone but instead of creating the zone it replaces the configuration for an already existing one. No cache is lost after this call. The only limitation when using this call is that you cannot change the zone object size type.
PUT https://api.ucdn.com/v3/zone/{zone_id}
This request returns one of the following messages
Status Flags Description
200 json Success message
532 json Fail message
This request expects the following parameters
Name Flags Validation Default Description
upstream required object valid upstream object Discribes where to pull files from. See the example for more info.
custom_domains string array domain,domain,domain... Custom domains for your zone. They must be CNAMEs to this zone's cdn_domain. This field does not have any effect when using shared SSL.
error_pages string array status:url Custom URLs to besed for redirecting from various HTTP error statuses (e.g. 404)
referers string array valid domains Allow access only from certain referers
geo_filter_allow string array ISO 3166-1 country code Allow access only from certain countries
geo_filter_deny string array ISO 3166-1 country code Deny access to certain countries
limit_rate_global string NNk, e.g. 20k Limit rate for every connection in this zone. It is mutually exclusive with limit_rate_security
limit_rate_security string on
off 		Use security token's limit rate. It is mutually exclusive with limit_rate_global
hash_secret string valid url query string Access security token, used in conjuction with hash_algorithm and hash_ttl
hash_algorithm string md5
sha1 		Hashing algorithm of the security token
hash_ttl integer in seconds Time to live of the security token hash
cache_reuse_from integer valid zone id Zone id of another zone. You cane use it to force this zone into using the other's cache.
expiration integer in seconds Forced cache expiration in seconds. When this is set expire and cache-control headers from the origin are ignored


Examples

curl --include --request PUT "https://api.ucdn.com/v3/zone/1/?token=acf0230d03f5b71d7252e336106f7338" --header "Content-Type: application/json" -d '{"object_size": "small", "upstream":{"endpoints":[{"host":"news.com","port":80}],"type":"own","proto":"http","host_header":"news.com","auth":{"type":"none"}}, "expiration": 3600, "custom_domains": ["cdn.section9.com"]}'
HTTP/1.1 200 OK
Date: Mon, 29 Jun 2015 08:03:09 GMT
Server: Apache
X-Powered-By: PHP/5.3.10-1ubuntu3.16
X-Cache: miss
Vary: Accept-Encoding
Content-Length: 27
Content-Type: application/json; charset=utf-8

{
    "message": "Zone replaced"
}

Replace a single zone parameter

You can edit the configuration for a particular zone with this API call. You may pass one or many of the parameters from the following.
PATCH https://api.ucdn.com/v3/zone/{zone_id}
This request returns one of the following messages
Status Flags Description
200 json Success message
532 json Fail message
This request supports the following helpers
Name Description
enable Enable the zone
disable Disable the zone
clear_security_token Unset the security token
clear_geo_filters Unset the geo filters
clear_limit_rates Unset the limit rates
clear_origins_auth Unset origin authentication
clear_referers Unset referers and referer_filter_rules filter
clear_referer_filter_rules Unset referers and referer_filter_rules filter
clear_custom_domains Unset all additional domains
clear_origins_header Unset the origin "Host:" header
clear_reuse_cache Stop reusing another zone's cache
This request expects the following parameters
Name Flags Validation Default Description
upstream object valid upstream object Discribes where to pull files from. See the example for more info.
custom_domains string array domain,domain,domain... Custom domains for your zone. They must be CNAMEs to this zone's cdn_domain. This field does not have any effect when using shared SSL.
error_pages string array status:url Custom URLs to besed for redirecting from various HTTP error statuses (e.g. 404)
referers string array valid domains Allow access only from certain referers
geo_filter_allow string array ISO 3166-1 country code Allow access only from certain countries
geo_filter_deny string array ISO 3166-1 country code Deny access to certain countries
limit_rate_global string NNk, e.g. 20k Limit rate for every connection in this zone. It is mutually exclusive with limit_rate_security
limit_rate_security string on
off 		Use security token's limit rate. It is mutually exclusive with limit_rate_global
hash_secret string valid url query string Access security token, used in conjuction with hash_algorithm and hash_ttl
hash_algorithm string md5
sha1 		Hashing algorithm of the security token
hash_ttl integer in seconds Time to live of the security token hash
cache_reuse_from integer valid zone id Zone id of another zone. You cane use it to force this zone into using the other's cache.
expiration integer in seconds Forced cache expiration in seconds. When this is set expire and cache-control headers from the origin are ignored


Examples

curl --include --request PATCH "https://api.ucdn.com/v3/zone/1/?token=acf0230d03f5b71d7252e336106f7338" --header "Content-Type: application/json" -d '{"expiration": 3600}'
HTTP/1.1 200 OK
Date: Mon, 29 Jun 2015 08:03:08 GMT
Server: Apache
X-Powered-By: PHP/5.3.10-1ubuntu3.16
X-Cache: miss
Vary: Accept-Encoding
Content-Length: 26
Content-Type: application/json; charset=utf-8

{
    "message": "Zone patched"
}

Delete a zone

Removes a cache zone. Once removed a cache zone cannot be restored and all of its cache is lost.
DELETE https://api.ucdn.com/v3/zone/{zone_id}
This request returns one of the following messages
Status Flags Description
200 json Success message
406 json Fail message
532 json Fail message

Examples

curl --include --request DELETE "https://api.ucdn.com/v3/zone/4/?token=acf0230d03f5b71d7252e336106f7338"
HTTP/1.1 200 OK
Date: Mon, 29 Jun 2015 08:10:38 GMT
Server: Apache
X-Powered-By: PHP/5.3.10-1ubuntu3.16
X-Cache: miss
Vary: Accept-Encoding
Content-Length: 26
Content-Type: application/json; charset=utf-8

{
    "message": "Zone deleted"
}

Add Letsencrypt for zone

This API call will create letsencrypt request for any of the additional domains in the provided zone at the moment of the call. The success of the call doesn't mean that the certificates are ready, it means that the UCDN started the process.
POST https://api.ucdn.com/v3/letsencrypt/{zone_id}
This request returns one of the following messages
Status Flags Description
202 string Success message
200 string Nothing changed message
400 string Bad request
532 string Fail message
This request expects the following parameters
Name Flags Validation Default Description
zone_id integer required Existing zone id Create letsencrypt for this zone_id