EdgeNext | Building the Edge for What's Next

CDN

Domain Configure

Endpoint

Request URL: domain/config (POST)

API Host: cdn.api.edgenext.com

API Version: v2

Description

Configures and modifies various features for acceleration domains. Supported features: origin, origin host, cache rules, referer blacklist/whitelist, IP blacklist, and response header addition.

Notes:

Rate limit: 30 requests per minute.

Each request supports configuring a single feature or multiple features simultaneously. When configuring multiple features at once, if any feature configuration is invalid, none of the features in the request will be applied.

Please contact your project manager to request access.

Request Parameters

Common parameters: Tokens can be obtained from the on-call team.

POST Parameters

Parameters support form-data, x-www-form-urlencoded, JSON, and other formats.

Parameter	Data Type	Required	Description
domains	string	Yes	Acceleration domain(s) to configure. Maximum 10 domains per request.
config	array	Yes	Feature configuration items:`origin`: Origin server`origin_host`: Origin host header`cache_rule_list`: Cache rules (new)`referer`: Referer blacklist/whitelist`ip_black_list`: IP blacklist`add_response_head`: Add response headers

origin (Origin Server)

Parameter	Data Type	Required	Description
default_master	string	Yes	Primary origin address. Accepts multiple IPs or a single domain.Separate multiple IPs with commas (,); primary and backup origins must not share the same IP or domain.
default_slave	string	No	Backup origin address. Accepts multiple IPs or a single domain.Separate multiple IPs with commas (,); primary and backup origins must not share the same IP or domain.
origin_mode	string	No	Origin pull protocol:`default`: Uses the protocol and port from the client request`http`: HTTP protocol on port 80`https`: HTTPS protocol on port 443`custom`: Custom protocol (`ori_https`) and port (`port`)Default: `default` if not specified.
ori_https	string	No	Required when `origin_mode=custom`.HTTPS origin pull:`yes`: Enabled`no`: Disabled
port	int	No	Required when `origin_mode=custom`.Origin port. Valid range: 0–65535.

# Modify origin
curl -X POST "https://cdn.api.edgenext.com/v2/domain/config"\
  -H 'content-type: application/json' \
  -d '{
    "token":"xxx",
    "domains":"example.com",
    "config": {   
        "origin": {
            "default_master":"1.1.1.1,1.1.1.2",
            "default_slave":"2.2.2.2",
            "origin_mode":"custom",
            "ori_https":"yes",
            "port":1040
        }
    }
}'

origin_host (Origin Host Header)

Parameter	Data Type	Required	Description
host	string	Yes	Origin host header.If not set, the CDN uses the acceleration domain as the origin host.

# Set origin host
curl -X POST "https://cdn.api.edgenext.com/v2/domain/config"\
  -H 'content-type: application/json' \
  -d '{
    "token":"xxx",
    "domains":"example.com",
    "config": {   
        "origin_host": {
            "host": "www.example.com"
        }
    }
}'

cache_rule (Cache Rules — Legacy)

Parameter	Data Type	Required	Description
type	int	Yes	Cache rule type:`1`: File extension`2`: Directory`3`: Exact path match`4`: Regex
pattern	string	Yes	Cache rule pattern. Multiple values separated by commas, e.g.:For `type=1`: `jpg,png,gif`For `type=2`: `/product/index,/test/index,/user/index`For `type=3`: `/index.html,/test/*.jpg,/user/get?index`For `type=4`: See regex usage note below. Requests matching the regex use this cache rule.Default: caches with query strings, ignores no-cache headers, does not ignore origin expiration.
time	int	Yes	Cache duration, combined with `timeunit`. Maximum: 2 years.`When time=0, caching is disabled for the specified pattern (no-cache).`
timeunit	string	No	Cache time unit. Default: `s`. Options: `Y` (year), `M` (month), `D` (day), `h` (hour), `i` (minute), `s` (second)
`ignore_no_cache`	string	No	Effective only when time > 0. Ignore origin no-cache headers. Default: `off`. Options: `on`, `off`
`ignore_expired`	string	No	Effective only when time > 0. Ignore origin expiration time. Default: `on`. Options: `on`, `off`
`ignore_query`	string	No	Effective only when time > 0. Ignore query string for both caching and origin pulls. Default: `off`. Options: `on`, `off`

Regex Cache Rule Usage Note: Regex rules are intended for scenarios where standard rule types are insufficient. Improper use can cause unexpected caching issues. We recommend only developers familiar with regex use this feature. When a regex rule is set, the full request URL (including protocol, domain, port if present, path, and query string) is matched against the regex. On match, the rule's cache TTL applies.

Example 1: .*\.(gif|png|jpg)$ — matches all URLs ending with .gif, .png, or .jpg.

Example 2: ^https?://[^/]+/dir1/dir2/(dir3_1|dir3_2)\.html — matches /dir1/dir2/dir3_1.html and /dir1/dir2/dir3_2.html on the current domain.

# Add cache rules (multiple rules supported)
curl -X POST "https://cdn.api.edgenext.com/v2/domain/config"\
  -H 'content-type: application/json' \
  -d '{
    "token":"xxx",
    "domains":"aa.qingcdn.com",
    "config": {
        "cache_rule":[
            {
                "type":1,
                "pattern":"jpg,png,gif",
                "time":3600
            },
            {
                "type":1,
                "pattern":"avi,mp4,mpeg",
                "time":3600
            }
        ]
    }
}'

cache_rule_list (Cache Rules — New)

Parameter	Data Type	Required	Description
match_method	string	Yes	Match type:`ext`: File extension`dir`: Directory`route`: Exact path match
pattern	string	Yes	Match pattern. Multiple values separated by commas, e.g.:For `match_method=ext`: `jpg,png,gif`For `match_method=dir`: `/product/index,/user/index`For `match_method=route`: `/index.html,/user/get?index`
case_ignore	string	No	Case-insensitive pattern matching:`yes`: Case-insensitive`no`: Case-sensitiveDefault: `yes`.
expire	int	Yes	Cache expiration time. Combined with `expire_unit`. Maximum: 2 years.When `expire=0`, caching is disabled for the specified pattern.
expire_unit	string	No	Cache time unit:`Y`: Year`M`: Month`D`: Day`h`: Hour`i`: Minute`s`: SecondDefault: `s`.
ignore_no_cache_headers	string	No	Ignore no-cache directives in origin response headers (e.g. `Cache-Control: no-cache`):`no`: Honor origin headers`yes`: Ignore origin headersDefault: `no`.
follow_expired	string	No	Follow origin cache expiration:`no`: Do not follow`yes`: FollowDefault: `no`.
query_params_op	string	No	Query string handling:`do_nothing`: Preserve query string`cache_back_source_remove`: Strip query string for both caching and origin pullsDefault: `do_nothing`.
priority	int	No	Rule priority. Lower values take higher precedence and are evaluated first.

# Set 2 cache rules
curl -X POST "http://cdn.api.edgenext.com/v2/domain/config"\
  -H 'content-type: application/json' \
  -d '{
    "token":"xxx",
    "domains":"example.com",
    "config": {
        "cache_rule_list":[
            {
            "match_method":"dir",
            "pattern":"/www/html,/www/aaa",
            "case_ignore":"no",
            "priority":13,
            "expire":60,
            "expire_unit":"i",
            "ignore_no_cache_headers":"yes", 
            "follow_expired":"no",
            "query_params_op":"do_nothing"
            },
            {
            "match_method":"ext",
            "pattern":"php,jsp,asp,aspx",
            "case_ignore":"no",
            "priority":15,
            "expire":3600,
            "expire_unit":"s",
            "ignore_no_cache_headers":"yes", 
            "follow_expired":"no",
            "query_params_op":"cache_back_source_remove"
            }
        ]
    }
}'

referer (Referer Blacklist/Whitelist — Hotlink Protection)

Parameter	Data Type	Required	Description
type	int	Yes	Hotlink protection type:`1`: Referer blacklist`2`: Referer whitelist
list	array	Yes	Referer list. Maximum 200 entries. Multiple values separated by commas; regex not supported. For wildcard domains, prefix with `.`, e.g. `.example2.com` — matches any subdomain and empty host header.
allow_empty	bool	No	Allow requests with empty referer:`true`: Allowed`false`: BlockedDefault: `true`.

# Set referer blacklist
curl -X POST "https://cdn.api.edgenext.com/v2/domain/config"\
  -H 'content-type: application/json' \
  -d '{
    "token":"xxx",
    "domains":"example.com",
    "config": {   
        "referer": {
            "type":"1",
            "list":[
                "*.example.com",
                "www.example2.com"
            ],
            "allow_empty":true
        }
    }
}'

# Set referer whitelist
curl -X POST "https://cdn.api.edgenext.com/v2/domain/config"\
  -H 'content-type: application/json' \
  -d '{
    "token":"xxx",
    "domains":"example.com",
    "config": {   
        "referer": {
            "type":"2",
            "list":[
                "*.example.com",
                "www.example2.com"
            ],
            "allow_empty":false
        }
    }
}'

ip_black_list (IP Blacklist)

Parameter	Data Type	Required	Description
list	array	Yes	IP blacklist entries. Supports /8, /16, and /24 CIDR blocks; ranges must not overlap. Maximum 500 entries, separated by commas.`IP blacklist and IP whitelist are mutually exclusive. Setting an IP blacklist clears any existing IP whitelist configuration.`
mode	string	No	`append`: Append to existing list`cover`: Overwrite existing list (default)

# Set IP blacklist
curl -X POST "https://cdn.api.edgenext.com/v2/domain/config"\
  -H 'content-type: application/json' \
  -d '{
    "token":"xxx",
    "domains":"example.com",
    "config": {   
        "ip_black_list": {
            "list": [
                "14.12.11.0/24",
                "1.2.3.4"
            ],
            "mode": "cover"
        }
    }
}'

add_response_head (Add Response Headers)

Parameter	Data Type	Required	Description
type	string	Yes	Response header operation mode:`reset`: Replace all response headers with the provided set`add`: Append response headers. If a key already exists, its value is overwritten.`remove`: Delete specified response headers.
list	array	Yes	Header list:For `reset` and `add`: Pass header name and value — `{"name":"Content-Type","value":"text/html"}`For `remove`: Pass only header names — `"Content-Type"`

# Add response headers — reset mode
curl -X POST "https://cdn.api.edgenext.com/v2/domain/config"\
    -H "Content-Type: application/json"\
    -d '{
    "token":"xxx",
    "domains":"example.com",
    "config": {
        "add_response_head": {
            "type":"reset",
            "list":[
                {
                    "name":"Content-Type", 
                    "value":"text/html; charset=ISO-8859-4"
                },
                {
                    "name":"Cache-Control", 
                    "value":"max-age=300, must-revalidate"
                }
            ]
        }
    }
}'

# Add response headers — add mode
curl -X POST "https://cdn.api.edgenext.com/v2/domain/config"\
    -H "Content-Type: application/json"\
    -d '{
    "token":"xxx",
    "domains":"example.com",
    "config": {
        "add_response_head": {
            "type":"add",
            "list":[
                {
                    "name":"Content-T1", 
                    "value":"text/html; charset=ISO-8859-4"
                },
                {
                    "name":"Cache-C1", 
                    "value":"max-age=300, must-revalidate"
                }
            ]
        }
    }
}'

# Remove response headers — remove mode
curl -X POST "https://cdn.api.edgenext.com/v2/domain/config"\
    -H "Content-Type: application/json"\
    -d '{
    "token":"xxx",
    "domains":"example.com",
    "config": {
        "add_response_head": {
            "type":"remove",
            "list":[
               "Content-T1",
                "Cache-C1"
            ]
        }
    }
}'

Example — Multiple Features

# Configure multiple features
curl -X POST "https://cdn.api.edgenext.com/v2/domain/config"\
    -H "Content-Type: application/json"\
    -d '{
    "token":"xxx",
    "domains":"example.com,example2.com",
    "config": {
        "origin": {
            "default_master": "133.233.133.33",
            "default_slave": "12.13.41.21"
        },
        "origin_host": {
            "host": "test.example.com"
        },
        "referer": {
            "type": 1,
            "list": [
                "*.example.com",
                "new.vx.example.com"
            ],
            "allow_empty": false
        },
        "ip_black_list": {
            "list": [
                "14.12.11.0/24",
                "1.2.3.1"
            ]
        },
        "add_response_head":{
            "type":"add",
            "list":[
                {
                    "name":"Content-Type", 
                    "value":"text/html; charset=ISO-8859-4"
                },
                {
                    "name":"Cache-Control", 
                    "value":"max-age=300, must-revalidate"
                }
            ]
        },
        "https":{
            "cert_id":123
        }
    }
}'

Response Example

JSON format — returns the successfully applied configuration corresponding to the requested parameters:

{
    "code": 0, // 0 = success; non-zero returns error message
    "data": {
        "config": {
            "origin": {
                "default_master": "133.233.133.33",
                "default_slave": "12.13.41.21"
            },
            ...
        }
    }
}

Response Headers

HTTP/1.0 200 OK
Api-Id: 221328331
Content-Type: application/json; charset=utf-8
X-Ratelimit-Grad: minute   // Rate limit granularity (minute/hour/day)
X-Ratelimit-Limit: 50      // Requests per minute limit
X-Ratelimit-Remaining: 29  // Remaining requests this minute
X-Retry-After: 43          // Seconds until the current rate limit window resets

HTTP Status Codes

Status Code	Description
404	The requested URL is invalid
401	Authentication error — invalid token or API access not enabled
400	Invalid request parameters
200	Request succeeded, data returned
5xx	Please contact the on-call team

Need help? Contact our support team at support@edgenext.com.

Back to documentation home

EdgeNext Documentation