Packages packages
Base packages for sale, defining quotas such as traffic, bandwidth and domains, and prices.
Pick an endpoint to see its example call on the right.
Authentication
Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.
X-API-Key
Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).
Conventions
Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.
Times are RFC 3339 (UTC); amounts are in cents.
Writes return 200/201/204 on success; duplicates of a unique key return 409.
/api/v2/packagesList packages
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
sort | string | Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id` |
/api/v2/packagesCreate package
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
backup_group_id | integer | Backup node group; null = none. |
bandwidth_mbps | integer | Bandwidth in Mbps, -1 = unlimited. |
buy_limit | integer | Maximum copies a tenant may hold, -1 = unlimited. |
cname_domain_id | integer | CNAME root domain; null = the package binds no lines. |
cname_host_suffix | string | Suffix for newly generated host records; empty = only the 8-character random name. |
cname_mode | PackageCnameMode | CNAME mode. site = one access name per site or stream; package = sites and streams of a purchased package share one access name. |
connections | integer | Concurrent connections, -1 = unlimited. |
custom_cc_rule | boolean | Allows custom CC rules. |
des | string | Description |
domains | integer | Number of domains (each IP site counts as 1), -1 = unlimited. |
enabled | boolean | Whether enabled |
expected_updated_at | string | Optimistic lock: send the updated_at you read; if it no longer matches, 409 package_changed and nothing is saved. Omit to skip the check. Ignored on create. |
featured | boolean | Featured (at most one; requires a tier, enabled, no owners and no sale end time). |
group_ids | integer[] | Package groups it belongs to. |
http_ports | integer | Number of non-standard HTTP/HTTPS ports (other than 80/443), -1 = unlimited. |
ip_num | integer | Number of selectable IPs ("My IPs"), -1 = unlimited. |
ip_pool_id | integer | IP pool used to provision IP sites (IP product line); null = not provisioned. |
ip_site | boolean | Opens IP sites: only when true can tenants create IP sites and pick new IPs; an IP pool is required while true. Turning it off keeps the pool, IP count, port count and picked IPs; existing packages are false (on upgrade, packages already using IP sites are set to true). |
ip_site_port | integer | IP-site ports: distinct ports across all IP sites of the package (80/443 included), -1 = unlimited; IP-site ports do not count toward non-standard ports. |
l2 | boolean | Includes tiered origin (tenant switch of the paid feature l2): tenants can turn on tiered origin for sites, and nodes use it, only while the master license l2 is active; existing packages are false (on upgrade, purchased packages of tenants already using tiered origin are set to true). |
nameRequired | string | Name |
node_group_id | integer | Primary node group; null = the package binds no lines. |
origin_ip_limit | string[] | Allowed origin IPs or CIDR ranges; empty = any. When set, origins of sites under the package must fall inside them and domain origins are rejected. |
owners | integer[] | Tenant ids allowed to buy; empty = no restriction. |
price_month_centsRequired | integer | Monthly price in cents. |
price_quarter_centsRequired | integer | Quarterly price in cents. |
price_year_centsRequired | integer | Yearly price in cents. |
prices | PackagePrice[] | Per-currency prices; must include the base-currency row (mode=base, its prices = price_*_cents). mode=manual uses the fixed price, mode=auto is derived from the base price at the current rate (.99 rounding is for display prices only); reads return the current converted price on auto rows. Omit prices on write to leave non-base rows untouched. The package catalog (/package-catalog) uses the purchase view: missing currencies are filled in as auto rows priced at the current rate, and currencies whose rate is not ready are left out; the admin endpoints return only the stored rows. |
region_id | integer | Region; null = the package binds no lines. |
renew_before_days | integer | Renewal is only allowed within this many days before expiry, -1 = unlimited. |
require_verified | boolean | Real-name verification is required to purchase. |
sale_until | string | Not sold after this time; omitted/null = no limit. |
sort | integer | Display order (smaller first). |
stream_ports | integer | Number of TCP/UDP forwarding ports, -1 = unlimited. |
tier | integer | Storefront tier, 0 = none, 1-4 = tier slot; unique across packages when above 0. |
traffic_gb | integer | Traffic in GB per billing cycle, -1 = unlimited. |
waf_enhanced | boolean | Includes WAF Enhanced (tenant switch of the paid feature waf_enhanced): tenants can use standard/strict levels, big screen, deep Bot, anti-tamper and so on only while the master license WAF Enhanced is not degraded; existing packages are false. |
websocket | boolean | Allows WebSocket. |
/api/v2/packages/batch-enableBatch enable or disable packages
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
enabledRequired | boolean | Whether enabled |
idsRequired | integer[] | IDs of the objects to change, at most 100. |
/api/v2/packages/{id}Get package
Authentication: Admin only
/api/v2/packages/{id}Update package
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
backup_group_id | integer | Backup node group; null = none. |
bandwidth_mbps | integer | Bandwidth in Mbps, -1 = unlimited. |
buy_limit | integer | Maximum copies a tenant may hold, -1 = unlimited. |
cname_domain_id | integer | CNAME root domain; null = the package binds no lines. |
cname_host_suffix | string | Suffix for newly generated host records; empty = only the 8-character random name. |
cname_mode | PackageCnameMode | CNAME mode. site = one access name per site or stream; package = sites and streams of a purchased package share one access name. |
connections | integer | Concurrent connections, -1 = unlimited. |
custom_cc_rule | boolean | Allows custom CC rules. |
des | string | Description |
domains | integer | Number of domains (each IP site counts as 1), -1 = unlimited. |
enabled | boolean | Whether enabled |
expected_updated_at | string | Optimistic lock: send the updated_at you read; if it no longer matches, 409 package_changed and nothing is saved. Omit to skip the check. Ignored on create. |
featured | boolean | Featured (at most one; requires a tier, enabled, no owners and no sale end time). |
group_ids | integer[] | Package groups it belongs to. |
http_ports | integer | Number of non-standard HTTP/HTTPS ports (other than 80/443), -1 = unlimited. |
ip_num | integer | Number of selectable IPs ("My IPs"), -1 = unlimited. |
ip_pool_id | integer | IP pool used to provision IP sites (IP product line); null = not provisioned. |
ip_site | boolean | Opens IP sites: only when true can tenants create IP sites and pick new IPs; an IP pool is required while true. Turning it off keeps the pool, IP count, port count and picked IPs; existing packages are false (on upgrade, packages already using IP sites are set to true). |
ip_site_port | integer | IP-site ports: distinct ports across all IP sites of the package (80/443 included), -1 = unlimited; IP-site ports do not count toward non-standard ports. |
l2 | boolean | Includes tiered origin (tenant switch of the paid feature l2): tenants can turn on tiered origin for sites, and nodes use it, only while the master license l2 is active; existing packages are false (on upgrade, purchased packages of tenants already using tiered origin are set to true). |
nameRequired | string | Name |
node_group_id | integer | Primary node group; null = the package binds no lines. |
origin_ip_limit | string[] | Allowed origin IPs or CIDR ranges; empty = any. When set, origins of sites under the package must fall inside them and domain origins are rejected. |
owners | integer[] | Tenant ids allowed to buy; empty = no restriction. |
price_month_centsRequired | integer | Monthly price in cents. |
price_quarter_centsRequired | integer | Quarterly price in cents. |
price_year_centsRequired | integer | Yearly price in cents. |
prices | PackagePrice[] | Per-currency prices; must include the base-currency row (mode=base, its prices = price_*_cents). mode=manual uses the fixed price, mode=auto is derived from the base price at the current rate (.99 rounding is for display prices only); reads return the current converted price on auto rows. Omit prices on write to leave non-base rows untouched. The package catalog (/package-catalog) uses the purchase view: missing currencies are filled in as auto rows priced at the current rate, and currencies whose rate is not ready are left out; the admin endpoints return only the stored rows. |
region_id | integer | Region; null = the package binds no lines. |
renew_before_days | integer | Renewal is only allowed within this many days before expiry, -1 = unlimited. |
require_verified | boolean | Real-name verification is required to purchase. |
sale_until | string | Not sold after this time; omitted/null = no limit. |
sort | integer | Display order (smaller first). |
stream_ports | integer | Number of TCP/UDP forwarding ports, -1 = unlimited. |
tier | integer | Storefront tier, 0 = none, 1-4 = tier slot; unique across packages when above 0. |
traffic_gb | integer | Traffic in GB per billing cycle, -1 = unlimited. |
waf_enhanced | boolean | Includes WAF Enhanced (tenant switch of the paid feature waf_enhanced): tenants can use standard/strict levels, big screen, deep Bot, anti-tamper and so on only while the master license WAF Enhanced is not degraded; existing packages are false. |
websocket | boolean | Allows WebSocket. |
/api/v2/packages/{id}Delete package
Authentication: Admin only
/api/v2/packages/{id}/groupsSet package groups
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
group_idsRequired | integer[] | Package groups it belongs to. |
/api/v2/packages/{id}/syncsSync base package to purchased packages
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
itemsRequired | PackageSyncField[] | Fields to sync. |
Packages object
| Field | Type | Description |
|---|---|---|
backup_group_id | integer | Backup node group; null = none. |
bandwidth_mbps | integer | Bandwidth in Mbps, -1 = unlimited. |
buy_limit | integer | Maximum copies a tenant may hold, -1 = unlimited. |
cname_domain_id | integer | CNAME root domain; null = the package binds no lines. |
cname_host_suffix | string | Suffix for newly generated host records; empty = only the 8-character random name. |
cname_mode | PackageCnameMode | CNAME mode. site = one access name per site or stream; package = sites and streams of a purchased package share one access name. |
connections | integer | Concurrent connections, -1 = unlimited. |
created_at | string | Created at |
custom_cc_rule | boolean | Allows custom CC rules. |
des | string | Description |
domains | integer | Number of domains (each IP site counts as 1), -1 = unlimited. |
enabled | boolean | Whether enabled |
errors | FieldError[] | Why each remaining item was not changed; field is /ids/<index>, code as in the single-item update (not_found, readonly and so on). |
expected_updated_at | string | Optimistic lock: send the updated_at you read; if it no longer matches, 409 package_changed and nothing is saved. Omit to skip the check. Ignored on create. |
featured | boolean | Featured (at most one; requires a tier, enabled, no owners and no sale end time). |
group_ids | integer[] | Package groups it belongs to. |
http_ports | integer | Number of non-standard HTTP/HTTPS ports (other than 80/443), -1 = unlimited. |
id | integer | Record ID |
idsRequired | integer[] | IDs of the objects to change, at most 100. |
ip_num | integer | Number of selectable IPs ("My IPs"), -1 = unlimited. |
ip_pool_id | integer | IP pool used to provision IP sites (IP product line); null = not provisioned. |
ip_site | boolean | Opens IP sites: only when true can tenants create IP sites and pick new IPs; an IP pool is required while true. Turning it off keeps the pool, IP count, port count and picked IPs; existing packages are false (on upgrade, packages already using IP sites are set to true). |
ip_site_port | integer | IP-site ports: distinct ports across all IP sites of the package (80/443 included), -1 = unlimited; IP-site ports do not count toward non-standard ports. |
itemsRequired | PackageSyncField[] | Fields to sync. |
l2 | boolean | Includes tiered origin (tenant switch of the paid feature l2): tenants can turn on tiered origin for sites, and nodes use it, only while the master license l2 is active; existing packages are false (on upgrade, purchased packages of tenants already using tiered origin are set to true). |
name | string | Name |
node_group_id | integer | Primary node group; null = the package binds no lines. |
origin_ip_limit | string[] | Allowed origin IPs or CIDR ranges; empty = any. When set, origins of sites under the package must fall inside them and domain origins are rejected. |
owners | integer[] | Tenant ids allowed to buy; empty = no restriction. |
price_month_cents | integer | Monthly price in cents. |
price_quarter_cents | integer | Quarterly price in cents. |
price_year_cents | integer | Yearly price in cents. |
prices | PackagePrice[] | Per-currency prices; must include the base-currency row (mode=base, its prices = price_*_cents). mode=manual uses the fixed price, mode=auto is derived from the base price at the current rate (.99 rounding is for display prices only); reads return the current converted price on auto rows. Omit prices on write to leave non-base rows untouched. The package catalog (/package-catalog) uses the purchase view: missing currencies are filled in as auto rows priced at the current rate, and currencies whose rate is not ready are left out; the admin endpoints return only the stored rows. |
region_id | integer | Region; null = the package binds no lines. |
renew_before_days | integer | Renewal is only allowed within this many days before expiry, -1 = unlimited. |
replaced | PackageReplaced | Other packages displaced by this save (package names); a field is omitted when nothing was displaced. |
require_verified | boolean | Real-name verification is required to purchase. |
sale_until | string | Not sold after this time; omitted/null = no limit. |
skipped | integer | Number skipped because they do not follow the base package or individually edited at least one changed field (other fields are still synced). |
skipped_ids | integer[] | Ids of the skipped purchased packages. |
sold_count | integer | Units sold (purchased packages referencing it); only in the admin list and detail, not in the catalog. |
sort | integer | Display order (smaller first). |
stream_ports | integer | Number of TCP/UDP forwarding ports, -1 = unlimited. |
sync | PackageSyncResult | Sync result. |
synced | integer | Number of purchased packages synced (for automatic sync, those where every changed field was synced). |
tier | integer | Storefront tier, 0 = none, 1-4 = tier slot; unique across packages when above 0. |
traffic_gb | integer | Traffic in GB per billing cycle, -1 = unlimited. |
updated | integer[] | IDs that were set (including those already in the target state), in request order. |
updated_at | string | Updated at |
waf_enhanced | boolean | Includes WAF Enhanced (tenant switch of the paid feature waf_enhanced): tenants can use standard/strict levels, big screen, deep Bot, anti-tamper and so on only while the master license WAF Enhanced is not degraded; existing packages are false. |
websocket | boolean | Allows WebSocket. |
Responses and errors
Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.
{
"id": 1,
"name": "example"
}{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}{
"code": "validation_failed",
"detail": "Invalid request parameters",
"errors": [
{
"code": "required",
"field": "/name",
"message": "name is required"
}
],
"request_id": "0123456789abcdef",
"status": 422,
"title": "Unprocessable Entity",
"type": "about:blank"
}