All requests to the CDNetworks platform must be authenticated using an API account name and key assigned to your organization. For security, the API key is not passed directly but is secured as described in the example script below.

The authentication type is HTTP Basic, and the authorization string is specified in the HTTP header field called Authorization.

<pre>
<code>
#!/bin/bash
#URL of the CDN Pro API server
API_SERVER=https://ngapi.cdnetworks.com

#You will be given the following information by the CDNetworks sales team
USER="{API user name}"
API_KEY="{API key (make sure to escape the $ sign if any)}"

#Date in RFC 1123 format
DATE=`LC_TIME="C" date -u "+%a, %d %b %Y %H:%M:%S GMT"`

#Generate the password. Raw output from openssl by adding the "-binary" flag
passw=$(echo -n "$DATE" | openssl dgst -sha1 -hmac "$API_KEY" -binary | base64)
echo " "

#Construct the curl command to query list of properties
apiCall="curl -i --url '${API_SERVER}/cdn/properties'
               -X GET
               -u $USER:$passw
               -H 'Date: $DATE'
               -H 'Accept: application/json'"

eval $apiCall
echo " "
</code>
</pre>

If you are a reseller you can also specify a child customer's ID in an On-Behalf-Of HTTP header field to make API calls to manage your child customer.

A more advanced Bash script allowing you to make calls to many CDN Pro APIs is available <a href="https://github.com/mileweb/CDNProCLI/tree/master/cdn/bash">here</a>.

CDN Pro APIs allow you to manage the CDN Pro service.  <p><a href="https://github.com/mileweb/CDNProCLI">CDNProCLI</a> is a command line tool that facilitates API calls in <a href="https://github.com/mileweb/CDNProCLI/tree/master/cdn/bash">bash</a> and <a href="https://github.com/mileweb/CDNProCLI/tree/master/cdn/js">JavaScript</a>. It includes the "cdnapi.sh" shell script mentioned in this document's examples.</p>

CDN Pro API Specification

This API allows you to create an annotation for a report shown in the CDN Pro portal. The request body lets you specify the conditions under which the annotation appears along with the text to show.

If you are a reseller, you can use this header to specify the ID of a child customer.

On-Behalf-Of

Specify the conditions in which the annotation appears and the text to show.

The annotation was created and will appear in the CDN Pro portal reports under the conditions you specified. The Location response header will include a URL to the object.

A URL to the annotation object, for example, <code>Location: http://ngapi.cdnetworks.com/cdn/annotations/5dd50ef0ace044000163278f</code>.

Invalid request. Refer to the response body for details.

You do not have permission to delete the annotation.

Retrieve details about a report annotation including the conditions in which it will appear in a CDN Pro report.

The response contains details about the annotation.

Update a report annotation. It will appear within CDN Pro portal reports when its conditions are met.

Specify the information about the annotation to update.

Obtain a list of annotations you have created. Annotations appear in the CDN Pro portal's reports based on the conditions defined for each annotation. Filter results using the query parameters and request body.

RFC 3339 date indicating the beginning of the time period. The time must be specified using the UTC timezone; it cannot be an offset. Example: <code>startdate=2019-10-30T00:00:00Z</code>

startdate

RFC 3339 format date indicating the end of the time period. The time must be specified using the UTC timezone; it cannot be an offset. Example: <code>enddate=2019-10-30T00:00:00Z</code> The maximum timespan should be no more than 366 days.

enddate

Indicates the type of annotation (client, configuration, or operation). Operation annotations can only be created by CDNetworks.

type

Search for annotations whose ID or comment match this value. When searching by ID, only an exact match will return results. The match on comments is case insensitive, and partial matches are supported.

search

offset

limit

An optional header that resellers can use to specify whether to include annotations from children customers. <table><tr><th>Value</th><th>Behavior</th></tr><tr><td>self-only</td><td>Include annotations from the caller.</td></tr><tr><td>children-only</td><td>Only annotations owned by children customers will be included.</td></tr><tr><td>self+children</td><td>Include annotations of both the caller and children customers.</td></tr></table>

Report-Range

An object that can be passed to report API calls to filter the results. For example, you can specify to only return data for a particular hostname.

reportfiltershostnamesonly

Filters let you control which annotations to return. Note that if multiple hostnames are specified, the API returns annotations that apply to any of the hostnames.

The response body contains a list of annotations.

The API call was invalid. Refer to the response body for details.

Control which CDN endpoints an <a href="#operation/post-ngadmin-apiAccounts">API account</a> can access. The permissions work with the API account's type, <i>operator</i> or <i>read-only</i>. For example, for security, you can limit a read-only API account to the property management APIs. This would allow the API account to see your property configurations but not make changes to them; it would not be permitted to call other APIs. 

You must call this API to create permissions for each new API account before it can be used. After you create a custom API permission for the API account, you can update its permissions further by calling our <a href="#operation/patch-cdn-apiPermissions-id">update permission API</a>.

If you are a reseller, you can use this header to specify the ID of a child customer for which you are creating an API permission.

Customize the access permitted to an API account.

The API permission was created. A location header in the response allows you to access its settings. The ID is the API account's ID.

Refers to the API permission for the API account. Example: Location: https://ngapi.cdnetworks.com/cdn/apiPermissions/1234567890


The request was invalid. Refer to the response body for details.

Delete custom permissions for an API account.

The API account's custom permissions were removed. This does not remove the API account itself. The API account still has default permissions.

Return an API account's permissions, both custom ones as well as the defaults. If you have not set an API account's permissions, you will get a 404 HTTP response. To specify the permissions of a new API account, you must <a href="#operation/post-cdn-apiPermissions">create an API permission</a> object for your API account with custom settings. Later, you can call our <a href="#operation/patch-cdn-apiPermissions-id">API to modify the permissions</a> further if needed.

The response body contains the API account's permissions.

Update permissions for an API account. If you have not yet customized the permissions of an API account, you must first <a href="#operation/post-cdn-apiPermissions">create a custom API permission</a>. Otherwise, this API will return a 404 response.

The account's API permissions were updated.

The request was invalid. Refer to the response body.

Get a list of available certificates including each certificate's ID, name, version deployed to production, version deployed to staging, the latest version number, when the certificate was last updated, and when the certificate expires. By default, certificates are returned in order of most recently updated first. Use query parameters to filter the list of returned certificates.

This parameter specifies a keyword to be searched in the 'name' field of the certificate.

The offset indicates the index of the first certificate to return. The default is 0.

The limit indicates the maximum number of certificates to return.

Filters the results based on where the certificate has been deployed. <table><tr><th>Value</th><th>Effect</th></tr><tr><td></td><td>An empty target parameter results in all certificates being returned whether or not they have been deployed.</td></tr><td>all</td><td>Return all certificates deployed to either staging or production environments.</td></tr><tr><td>staging</td><td>Only return certificates deployed to staging.</td></tr><tr><td>production</td><td>Only return certificates deployed to production.</td></tr></table>


target

Filter results based on auto renewal status. By default, all certificates are returned.

autoRenew

Returns certificates sorted by this field.

sortBy

Return results sorted in this order ("asc" for ascending order, "desc" for descending order).


sortOrder

An optional header that resellers can use to specify whether to include data from children customers. <table><tr><th>Value</th><th>Behavior</th></tr><tr><td>self-only</td><td>Include certificates owned by or shared with the caller.</td></tr><tr><td>children-only</td><td>Include certificates owned by or shared with children customers only.</td></tr><tr><td>self+children</td><td>Include certificates owned by or shared with the caller or children customers.</td></tr></table>

The response contains a list of certificates.

Create a certificate along with its first version. You can choose to upload the key/certificate pair or generate a self-signed one.

The certificate was created. The <i>Location</i> header contains a URL to the new certificate.

The Location header's value will be a URL allowing you to get details about the new certificate.  Example: <code>Location: http://ngapi.cdnetworks.com/cdn/certificates/d60b730d9a586425677940cc</code>

The request was forbidden. Please refer to the response body for details.

This API lets you delete a certificate that is not being used in production or staging.

This response is returned if the certificate was successfully deleted.

The certificate cannot be deleted because it is being used in production or staging.

Gets details about a certificate including the versions of the certificate and who is using it.

The response body contains information about the certificate.

certificateID

Update a certificate using this API. The fields are the same as those in the <a href="#operation/createCertificate">Create a certificate API</a>. If the certificate is currently used by properties deployed to production or staging, we recommend that you follow this API call by <a href="#operation/createDeployment">creating a deployment task</a> to deploy the updated certificate. Otherwise, CDN Pro may still serve content using an older version of the certificate.

The request body indicates the fields that will be updated. If a field is omitted, then its value will be unchanged.

This response indicates a new certificate version was created.

The Location header returns a URL to the specific certificate version if a new one is created.  Example:  <code>Location: http://ngapi.cdnetworks.com/cdn/certificates/329f12c1fe6708c23c31e91f/versions/5</code>

This response indicates the request was invalid. Please refer to the response body for more details.

The request was forbidden. Please refer to the response body for more details.

Obtain the certificate signing request (CSR) information. You can take it to a certificate authority to apply for a certificate. Once you have it, you should update our system using the <a href="#operation/updateCertificate">Update a certificate API</a>.

This optional parameter can be used to request a domain control validation (DCV) file. Currently, we support the certificate authority, Sectigo, by specifying "sectigo" as the value of the parameter.

This endpoint can be used to delete the latest version of a certificate if it was accidentally created but never deployed. The version number will be reused the next time the certificate is <a href="#operation/updateCertificate">updated to a new version</a>.

The latest version of the certificate was deleted.

The latest version of the certificate cannot be deleted if it was deployed to production or staging before. 

Delete the latest version of a certificate

Obtain details about a certificate version including the expiration date, algorithm and key length, fingerprint, and whether it is deployed in production and staging.

The response contains details about the version of the certificate.

Version of the certificate to retrieve. It can be an integer representing the version like "1" or "latest" to return the most recently created version of the certificate.

version

Get a list of client regions that can be used in <a href="#operation/createEdgeHostname">edge hostname client zone rules</a>. Query parameters allow you to filter and sort the results.

Return regions whose code or name contains the specified value.


Order of client regions returned. Use 'asc' for ascending order or 'desc' for descending order.

Limit the returned regions to those where an ISP operates. The value should be one of the ISP codes returned by the <a href="#operation/get-cdn-isps">ISPs API</a>.

ispCode

The response body contains a list of regions. You can specify a region's code in an edge hostname's client zone rule.

Get a summary of deployment tasks. Filter results using the query parameters. If you specify more than one query parameter, only the tasks meeting all criteria will be returned.

Only return deployment tasks related to this property.

propertyId

Only return deployment tasks related to this certificate.

certificateId

Return deployment tasks to a particular environment. By default, all tasks are returned.

Filter based on text in the deployment name or in a property's hostname.

A comma-separated list of task IDs indicating which ones to return.

taskIds

Enter an RFC 3339 format date to return deployments which were submitted by this date.

Enter an RFC 3339 format date to return deployments which were submitted no later than this date.

An optional header that resellers can use to specify whether to include data from children customers. <table><tr><th>Value</th><th>Behavior</th></tr><tr><td>self-only</td><td>Include deployment tasks of the caller.</td></tr><tr><td>children-only</td><td>Include deployment tasks of children customers only</td></tr><tr><td>self+children</td><td>Include deployment tasks of both the caller and children customers.</td></tr></table>

Filter based on the deployment task's status. By default, tasks are returned regardless of their status.

status

A list of deployment tasks is returned in the response body.

Create a deployment task to deploy your property or certificate to the staging or production environments or to remove the property or certificate. The staging environment allows you to test your property to ensure correct behavior before you make it available to end users. Refer to <a href="/cdn/docs/portal/edge-configurations/testing-property">testing a property</a> for more information.

If a property uses a certificate, an error will be returned by this API if the certificate has not yet been deployed to the target environment. An error will also be returned if the certificate's Subject Alternative Name (SAN) does not include the hostnames specified in the property version. A SAN with a wildcard hostname will support subdomains only at the same level as the wildcard. For instance, the wildcard '*.xyz.com' supports 'abc.xyz.com' but not 'def.abc.xyz.com'.

After a property version is deployed, it will be frozen to prevent additional changes. You can modify the property by <a href="#operation/createPropertyVersion">creating a new property version</a>.

By default, if you deploy a property using a certificate, we check that the hostnames in the property are covered by the subject alternative name (SAN) of the certificate and that the certificate has not expired. For test purposes, you can bypass this check by passing the <i>Check-Certificate: no</i> header when creating the deployment task. You should not use this header when deploying for real users of your content since their browsers will warn about the invalid certificate and discourage them from visiting.

Check-Certificate

By default, we check if the deployment would result in removal of hostnames which have been recently used as determined by the number of requests to them in the past 24 hours. If this is the case, the API returns an error with the code 'RemovingActiveHostname'. This safety check is intended to protect against accidentally impacting visitors to your content.  You can pass the <i>Check-Usage: no</i> header to bypass this check.

Check-Usage

Identifies the properties and certificates to deploy.

The deployment task has been created. The Location header in the response contains a URL to the new task. You can call our <a href="#operation/queryDeploymentTask">API to get the status of the deployment</a>.

The Location header's value will be the URL of the new deployment task.  Example: <code>Location: http://ngapi.cdnetworks.com/cdn/deploymentTasks/ac8e3085-ef92-4c12-ab1b-19b18ac9383c</code>

The request was forbidden. Refer to the response body for details.

The deployment task could not be created. Refer to the response body for details.

Get details about a deployment task including the associated actions, when it was submitted, its status, and additional details if the deployment failed.

The response body contains details about the deployment task.

Get a list of edge hostnames. Specify search, offset, and limit parameters to filter your results. The default is to return the most recently updated edge hostname first.

The value is matched against the 'description' and 'edgeHostname' fields of each edge hostname.

Indicates the first edge hostname to return. The first has an offset of 0.

Maximum number of edge hostnames to return.

Indicates the order of edge hostnames returned. Use 'asc' for ascending order or 'desc' for descending order.

Specify <i>true</i> to obtain a list of edge hostnames flagged for use with hostnames that have a Beian license, allowing them to be served by servers in mainland China. Specify <i>false</i> to retrieve only those edge hostnames without the Beian flag. By default, all edge hostnames are returned.

hasBeian

An optional header that resellers can use to specify whether to include data from children customers. <table><tr><th>Value</th><th>Behavior</th></tr><tr><td>self-only</td><td>Include edge hostnames of the caller.</td></tr><tr><td>children-only</td><td>Include edge hostnames of children customers only.</td></tr><tr><td>self+children</td><td>Include edge hostnames of both the caller and children customers.</td></tr></table>

Comma-separated list of server groups ( chinaStandard, chinaPremium, standard, premium, deluxe, ultra, and nearChina). Only edge hostnames whose client zone rules reference the server groups will be returned.

serverGroups

The response contains edge hostnames matching the criteria.

This API enables you to create edge hostnames to control how requests from different client zones are handled. You must create CNAME DNS records to point your properties' hostnames to an edge hostname created using this API in order for the CDN to handle your content.

The request body contains rules for your edge hostname.

The edge hostname was created. The Location header has a reference to the new edge hostname.

The value is a URL to the new edge hostname.

The edge hostname could not be created due to a conflict. Refer to the response body for details.

Use this API to delete an edge hostname. If you have configured your DNS server with this edge hostname, you should update your DNS records before deleting it. Otherwise, visitors to the associated hostnames will see an error.

By default, we check if the edge hostname has been recently used as determined by the number of requests to it in the past 24 hours. This safety check is intended to protect against accidentally impacting visitors to your content.  You can pass the <i>Check-Usage: no</i> header to bypass this check.

The edge hostname was successfully deleted.

This API returns information about an edge hostname including the associated client zone rules and operation history.

The response body contains details of the edge hostname.

edgeHostname

This API allows you to update an edge hostname by sending only the fields that are changing.

The request body contains the fields you wish to modify.

The edge hostname was successfully updated.

The edge hostname could not be found. Refer to the response body for details.

The edgeHostname field cannot be changed because it may cause a service interruption.

Use this API to update an edge hostname. Be sure to enter all fields describing your edge hostname including ones that are not changing.

The request body fully describes the edge hostname. Please include all fields even if you are not changing their values.

Get a list of hostnames belonging to properties that have been deployed to production or staging.

Index of the first hostname to return. Defaults to 0.

An optional header that resellers can use to specify whether to include data from children customers. <table><tr><th>Value</th><th>Behavior</th></tr><tr><td>self-only</td><td>Include hostnames of the caller.</td></tr><tr><td>children-only</td><td>Include hostnames of children customers only.</td></tr><tr><td>self+children</td><td>Include hostnames of both the caller and children customers.</td></tr></table>

Limit the response to hostnames from properties deployed to staging only or production only. By default, all hostnames from properties deployed to either production or staging are returned.

The response contains a list of hostnames that have been deployed.

Get list of hostnames that have been deployed

Get a list of hostnames belonging to properties that were successfully <a href="#tag/Deployment-Management">deployed</a> to production or staging during a particular timeframe.

Beginning of the time period in RFC 3339 format. The time must be specified using the UTC timezone; it cannot be an offset. Example: <code>startdate=2019-11-14T00:00:00Z</code> By default, the value is when you began using CDN Pro.

End of the time period in RFC 3339 format. The time must be specified using the UTC timezone; it cannot be an offset. Example: <code>enddate=2019-11-14T00:00:00Z</code> The default is the current time.

Filter by looking up the beginning portion of a hostname.

The response body contains a list of hostnames.

The request was invalid. The response body includes details about the error.

Get historical information about hostnames

This API returns information about a hostname's deployments to production and staging. Query parameters let you specify a timeframe to search and where the hostname was deployed.

Return historical information about deployments to a particular environment. By default, information about deployments to both staging and production are returned.

The response body contains details about the hostname.

Get historical information about one hostname

hostname

This API returns information about a specific hostname belonging to a property that has been deployed to production or staging.

The response contains information about the version of the associated property deployed to production and staging. If the hostname does not exist, the fields will be null.

Get information about a specific hostname

Obtain a list of ISPs that can be used in <a href="#operation/createEdgeHostname">edge hostname client zone rules</a>.

Return ISPs whose code or name contains this value.

Order of ISPs returned. Use 'asc' for ascending order or 'desc' for descending order.

Limit returned ISPs to those operating in a particular region. The value of <i>regionCode</i> should be one of the codes representing a region returned by the <a href="#operation/get-cdn-clientRegions">client regions API</a>.

regionCode

The response contains a list of ISPs. You can specify an ISP's code in an <a href="#operation/createEdgeHostname">edge hostname's client zone rule</a>.

Get a list of log aggregation points that are used to collect raw server logs.

The value of the search parameter is matched on the name, description, and destinationURL fields of log aggregation points. Partial matches are supported.

The response contains a list of log aggregation points.

Create a new log aggregation point where batches of logs are sent together rather than individually. The maximum number of log aggregation points that can be created by a customer are defined in the customer's service quota.

The request body defines the parameters of the aggregation point.

The log aggregation point was created. The <i>Location</i> header contains a URL to the new log aggregation point. The URL can then be used in the <i>logUrl</i> field of the <a href="#operation/createProperty">realTimeLog setting in a property</a>.

This error is returned if you try to create a log aggregation point using the name of an existing one.

Use this API to delete a log aggregation point.

The log aggregation point was successfully deleted.

Use this API to get details about a log aggregration point.

The response body contains details about a log aggregation point.

The log aggregation point does not exist.

Get details about a log aggregation point

Use this API to update a log aggregation point.

The request body contains the fields to update.

This API returns a list of IP addresses used by our origin fast route servers. If you use our <a href="/cdn/docs/edge-logic/supported-directives#origin_fast_route">fast route feature</a> to make the connections faster and more reliable and wish to restrict access to your origin servers, add these IP addresses to your allow lists.


The response body contains a list of IP addresses.

Get a list of prefetch requests. Prefetch records are retained for fifteen days. Filter the list by specifying query parameters.

RFC 3339 date indicating the beginning of the time period. It must be in UTC time, for example, "2021-03-01T01:00:00Z".

RFC 3339 date indicating the end of the time period. It must be in UTC time, for example, "2021-03-01T01:00:00Z".

Index of the first prefetch request to return.

Maximum number of prefetch requests to return.

Controls the order in which prefetch requests are returned. The default is to return the most recently submitted request first.

Order of prefetch requests. The default is to return the most recent prefetch request first. Enter 'asc' for ascending order or 'desc' for descending order.

The value will be used to match on prefetch request names, hostnames, and the task IDs to limit the prefetch requests that are returned.

If you are a reseller, you can use this header to specify the ID of a child customer. Only requests from that customer will be returned. 