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.

PackagesAuthentication: Admin only8 endpoints

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.

GET/api/v2/packagesList packages

Authentication: Admin only

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
sortstring Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id`
POST/api/v2/packagesCreate package

Authentication: Admin only

Request body application/json

FieldTypeDescription
backup_group_idinteger Backup node group; null = none.
bandwidth_mbpsinteger Bandwidth in Mbps, -1 = unlimited.
buy_limitinteger Maximum copies a tenant may hold, -1 = unlimited.
cname_domain_idinteger CNAME root domain; null = the package binds no lines.
cname_host_suffixstring Suffix for newly generated host records; empty = only the 8-character random name.
cname_modePackageCnameMode CNAME mode. site = one access name per site or stream; package = sites and streams of a purchased package share one access name.
Values ["site","package"]
connectionsinteger Concurrent connections, -1 = unlimited.
custom_cc_ruleboolean Allows custom CC rules.
desstring Description
domainsinteger Number of domains (each IP site counts as 1), -1 = unlimited.
enabledboolean Whether enabled
expected_updated_atstring 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.
featuredboolean Featured (at most one; requires a tier, enabled, no owners and no sale end time).
group_idsinteger[] Package groups it belongs to.
http_portsinteger Number of non-standard HTTP/HTTPS ports (other than 80/443), -1 = unlimited.
ip_numinteger Number of selectable IPs ("My IPs"), -1 = unlimited.
ip_pool_idinteger IP pool used to provision IP sites (IP product line); null = not provisioned.
ip_siteboolean 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_portinteger 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.
l2boolean 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).
nameRequiredstring Name
node_group_idinteger Primary node group; null = the package binds no lines.
origin_ip_limitstring[] 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.
ownersinteger[] Tenant ids allowed to buy; empty = no restriction.
price_month_centsRequiredinteger Monthly price in cents.
price_quarter_centsRequiredinteger Quarterly price in cents.
price_year_centsRequiredinteger Yearly price in cents.
pricesPackagePrice[] 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_idinteger Region; null = the package binds no lines.
renew_before_daysinteger Renewal is only allowed within this many days before expiry, -1 = unlimited.
require_verifiedboolean Real-name verification is required to purchase.
sale_untilstring Not sold after this time; omitted/null = no limit.
sortinteger Display order (smaller first).
stream_portsinteger Number of TCP/UDP forwarding ports, -1 = unlimited.
tierinteger Storefront tier, 0 = none, 1-4 = tier slot; unique across packages when above 0.
traffic_gbinteger Traffic in GB per billing cycle, -1 = unlimited.
waf_enhancedboolean 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.
websocketboolean Allows WebSocket.
POST/api/v2/packages/batch-enableBatch enable or disable packages

Authentication: Admin only

Request body application/json

FieldTypeDescription
enabledRequiredboolean Whether enabled
idsRequiredinteger[] IDs of the objects to change, at most 100.
GET/api/v2/packages/{id}Get package

Authentication: Admin only

PUT/api/v2/packages/{id}Update package

Authentication: Admin only

Request body application/json

FieldTypeDescription
backup_group_idinteger Backup node group; null = none.
bandwidth_mbpsinteger Bandwidth in Mbps, -1 = unlimited.
buy_limitinteger Maximum copies a tenant may hold, -1 = unlimited.
cname_domain_idinteger CNAME root domain; null = the package binds no lines.
cname_host_suffixstring Suffix for newly generated host records; empty = only the 8-character random name.
cname_modePackageCnameMode CNAME mode. site = one access name per site or stream; package = sites and streams of a purchased package share one access name.
Values ["site","package"]
connectionsinteger Concurrent connections, -1 = unlimited.
custom_cc_ruleboolean Allows custom CC rules.
desstring Description
domainsinteger Number of domains (each IP site counts as 1), -1 = unlimited.
enabledboolean Whether enabled
expected_updated_atstring 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.
featuredboolean Featured (at most one; requires a tier, enabled, no owners and no sale end time).
group_idsinteger[] Package groups it belongs to.
http_portsinteger Number of non-standard HTTP/HTTPS ports (other than 80/443), -1 = unlimited.
ip_numinteger Number of selectable IPs ("My IPs"), -1 = unlimited.
ip_pool_idinteger IP pool used to provision IP sites (IP product line); null = not provisioned.
ip_siteboolean 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_portinteger 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.
l2boolean 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).
nameRequiredstring Name
node_group_idinteger Primary node group; null = the package binds no lines.
origin_ip_limitstring[] 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.
ownersinteger[] Tenant ids allowed to buy; empty = no restriction.
price_month_centsRequiredinteger Monthly price in cents.
price_quarter_centsRequiredinteger Quarterly price in cents.
price_year_centsRequiredinteger Yearly price in cents.
pricesPackagePrice[] 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_idinteger Region; null = the package binds no lines.
renew_before_daysinteger Renewal is only allowed within this many days before expiry, -1 = unlimited.
require_verifiedboolean Real-name verification is required to purchase.
sale_untilstring Not sold after this time; omitted/null = no limit.
sortinteger Display order (smaller first).
stream_portsinteger Number of TCP/UDP forwarding ports, -1 = unlimited.
tierinteger Storefront tier, 0 = none, 1-4 = tier slot; unique across packages when above 0.
traffic_gbinteger Traffic in GB per billing cycle, -1 = unlimited.
waf_enhancedboolean 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.
websocketboolean Allows WebSocket.
DELETE/api/v2/packages/{id}Delete package

Authentication: Admin only

PUT/api/v2/packages/{id}/groupsSet package groups

Authentication: Admin only

Request body application/json

FieldTypeDescription
group_idsRequiredinteger[] Package groups it belongs to.
POST/api/v2/packages/{id}/syncsSync base package to purchased packages

Authentication: Admin only

Request body application/json

FieldTypeDescription
itemsRequiredPackageSyncField[] Fields to sync.

Packages object

FieldTypeDescription
backup_group_idinteger Backup node group; null = none.
bandwidth_mbpsinteger Bandwidth in Mbps, -1 = unlimited.
buy_limitinteger Maximum copies a tenant may hold, -1 = unlimited.
cname_domain_idinteger CNAME root domain; null = the package binds no lines.
cname_host_suffixstring Suffix for newly generated host records; empty = only the 8-character random name.
cname_modePackageCnameMode CNAME mode. site = one access name per site or stream; package = sites and streams of a purchased package share one access name.
Values ["site","package"]
connectionsinteger Concurrent connections, -1 = unlimited.
created_atstring Created at
read-only
custom_cc_ruleboolean Allows custom CC rules.
desstring Description
domainsinteger Number of domains (each IP site counts as 1), -1 = unlimited.
enabledboolean Whether enabled
errorsFieldError[] 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_atstring 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.
featuredboolean Featured (at most one; requires a tier, enabled, no owners and no sale end time).
group_idsinteger[] Package groups it belongs to.
http_portsinteger Number of non-standard HTTP/HTTPS ports (other than 80/443), -1 = unlimited.
idinteger Record ID
read-only
idsRequiredinteger[] IDs of the objects to change, at most 100.
ip_numinteger Number of selectable IPs ("My IPs"), -1 = unlimited.
ip_pool_idinteger IP pool used to provision IP sites (IP product line); null = not provisioned.
ip_siteboolean 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_portinteger 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.
itemsRequiredPackageSyncField[] Fields to sync.
l2boolean 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).
namestring Name
node_group_idinteger Primary node group; null = the package binds no lines.
origin_ip_limitstring[] 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.
ownersinteger[] Tenant ids allowed to buy; empty = no restriction.
price_month_centsinteger Monthly price in cents.
price_quarter_centsinteger Quarterly price in cents.
price_year_centsinteger Yearly price in cents.
pricesPackagePrice[] 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_idinteger Region; null = the package binds no lines.
renew_before_daysinteger Renewal is only allowed within this many days before expiry, -1 = unlimited.
replacedPackageReplaced Other packages displaced by this save (package names); a field is omitted when nothing was displaced.
require_verifiedboolean Real-name verification is required to purchase.
sale_untilstring Not sold after this time; omitted/null = no limit.
skippedinteger Number skipped because they do not follow the base package or individually edited at least one changed field (other fields are still synced).
skipped_idsinteger[] Ids of the skipped purchased packages.
sold_countinteger Units sold (purchased packages referencing it); only in the admin list and detail, not in the catalog.
read-only
sortinteger Display order (smaller first).
stream_portsinteger Number of TCP/UDP forwarding ports, -1 = unlimited.
syncPackageSyncResult Sync result.
syncedinteger Number of purchased packages synced (for automatic sync, those where every changed field was synced).
tierinteger Storefront tier, 0 = none, 1-4 = tier slot; unique across packages when above 0.
traffic_gbinteger Traffic in GB per billing cycle, -1 = unlimited.
updatedinteger[] IDs that were set (including those already in the target state), in request order.
updated_atstring Updated at
read-only
waf_enhancedboolean 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.
websocketboolean 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.

Success
{
  "id": 1,
  "name": "example"
}
List
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
Error
{
  "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"
}
Get started

Try the live demo

Open the live demo, or contact us for a quote and the install command