Version 2.4.7.20261116085428 · latest

Tiered origin (L2) l2

Edges fetch through L2 nodes in their region first, so cached content no longer hits the origin. Paid feature l2; inactive when not licensed.

Pick an endpoint to see its example call on the right.

Tiered originAuthentication: Admin only25 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.

POST/api/v2/l2/enable-batchAdd L2 nodes in batch

Authentication: Admin only

Request body application/json

FieldTypeDescription
apply_sitesboolean Also enable on existing sites (only those never set; sites turned off manually, or whose tenant package does not include tiered origin, stay unchanged).
node_idsRequiredinteger[] Edge node IDs to turn into L2.
GET/api/v2/l2/groupsList L2 groups

Authentication: Admin only

POST/api/v2/l2/groupsCreate L2 group

Authentication: Admin only

Request body application/json

FieldTypeDescription
all_regionsboolean Serve all regions (requires cross_region).
balancestring Distribution: url_hash pins by URL, rr round-robin.
Values ["url_hash","rr"]
cross_regionboolean Allow cross-region use (required for nodes outside the regions or all regions; adds about 50-200 ms).
nameRequiredstring Group name, unique platform-wide.
node_idsinteger[] Edge node IDs to turn into L2.
regionsinteger[] Served region IDs; ignored when all_regions is true.
rulesL2Rule[] Group rules (saved with the group).
GET/api/v2/l2/groups/{id}Get L2 group

Authentication: Admin only

PATCH/api/v2/l2/groups/{id}Update L2 group

Authentication: Admin only

Request body application/json

FieldTypeDescription
all_regionsboolean Serve all regions (requires cross_region).
balancestring Distribution: url_hash pins by URL, rr round-robin.
Values ["url_hash","rr"]
cross_regionboolean Allow cross-region use (required for nodes outside the regions or all regions; adds about 50-200 ms).
namestring Group name, unique platform-wide.
node_idsinteger[] Edge node IDs to turn into L2.
regionsinteger[] Served region IDs; ignored when all_regions is true.
rulesL2Rule[] Group rules (saved with the group).
DELETE/api/v2/l2/groups/{id}Delete L2 group

Authentication: Admin only

POST/api/v2/l2/groups/{id}/copyCopy L2 group

Authentication: Admin only

Request body application/json

FieldTypeDescription
nameRequiredstring Group name, unique platform-wide.
POST/api/v2/l2/groups/{id}/reset-sitesReset sites of a group to region default

Authentication: Admin only

GET/api/v2/l2/nodesList L2 nodes

Authentication: Admin only

PATCH/api/v2/l2/nodes/{id}Update L2 node

Authentication: Admin only

Request body application/json

FieldTypeDescription
access_addrstring Private address edges use to reach it (IP only, no port; IPv4-mapped IPv6 is stored as IPv4); empty means the public IP.
rolestring Primary or backup: backups stand by while a primary in the same group is up.
Values ["primary","backup"]
weightinteger Weight 1-100; multiple primaries share URLs by weight.
POST/api/v2/l2/nodes/{id}/disableDisable L2 node

Authentication: Admin only

Request body application/json

FieldTypeDescription
reasonstring Reason for disabling.
POST/api/v2/l2/nodes/{id}/enableEnable L2 node

Authentication: Admin only

POST/api/v2/l2/nodes/{id}/mark-allowedMark origins as allowing the node

Authentication: Admin only

POST/api/v2/l2/nodes/{id}/probe-accessCheck whether origins allow the node

Authentication: Admin only

POST/api/v2/l2/nodes/{id}/revertRevert to edge node

Authentication: Admin only

POST/api/v2/l2/pausePause tiered origin network-wide

Authentication: Admin only

Request body application/json

FieldTypeDescription
auto_resume_atstring Automatic resume time (must be in the future); omit for manual resume.
POST/api/v2/l2/resumeResume tiered origin network-wide

Authentication: Admin only

GET/api/v2/l2/revoke-impactLicense loss impact and fallback window

Authentication: Admin only

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
GET/api/v2/l2/statsTiered origin statistics

Authentication: Admin only

Query parameters

FieldTypeDescription
startRequiredstring Start time (inclusive), RFC 3339
endRequiredstring End time (exclusive), RFC 3339
GET/api/v2/l2/stats/nodesStatistics by L2 node

Authentication: Admin only

Query parameters

FieldTypeDescription
startRequiredstring Start time (inclusive), RFC 3339
endRequiredstring End time (exclusive), RFC 3339
GET/api/v2/l2/stats/sitesTiered origin statistics by site

Authentication: Admin only

Query parameters

FieldTypeDescription
startRequiredstring Start time (inclusive), RFC 3339
endRequiredstring End time (exclusive), RFC 3339
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
domainstring Substring of the primary domain, case-insensitive.
GET/api/v2/l2/statusTiered origin overview

Authentication: Admin only

Tiered origin (L2) object

FieldTypeDescription
access_addrstring Private address edges use to reach it (IP only, no port; IPv4-mapped IPv6 is stored as IPv4); empty means the public IP.
all_regionsboolean Serve all regions (requires cross_region).
allowstring Origin allowlisting: empty if not applicable, pending (cacheable requests only), or allowed.
allow_sincestring Pending since; turns allowed after 24 hours.
apply_sitesboolean Also enable on existing sites (only those never set; sites turned off manually, or whose tenant package does not include tiered origin, stay unchanged).
auto_resume_atstring Automatic resume time (must be in the future); omit for manual resume.
balancestring Distribution: url_hash pins by URL, rr round-robin.
Values ["url_hash","rr"]
checked_atstring Checked at.
created_atstring Started at.
cross_regionboolean Allow cross-region use (required for nodes outside the regions or all regions; adds about 50-200 ms).
defaultsL2Defaults Defaults (change via PUT /configs/l2.defaults).
disabled_atstring Disabled at.
disabled_reasonstring Reason for disabling.
edge_origin_requestsinteger Edge origin requests (hit rate denominator).
empty_groupinteger[] Groups left without a serving L2 (their sites will bypass temporarily).
enabledboolean Enabled; a disabled node stays L2 and keeps its cache.
featurestring Paid feature l2 level: on; limited when frozen, being revoked, or in the fallback window after the license lapses (still pushed, management only; see GET /l2/revoke-impact); off when not licensed (not pushed).
Values ["on","limited","off"]
finished_atstring Finished at.
groupsinteger[] IDs of L2 groups containing it.
hit_ratenumber Hit rate 0-1; 0 when there were no origin requests.
hoststring Primary domain of the site.
idinteger Group ID.
ipstring Public IP.
is_region_defaultboolean Region default group (one per region; cannot be deleted, only its distribution can change).
itemsL2Group[] L2 groups.
kindstring Task kind: enable adds L2, revert returns to edge.
Values ["enable","revert"]
l2_group_idinteger L2 group chosen by the site; null means region default.
l2_group_namestring L2 group name; empty for region default.
l2_hit_requestsinteger Origin requests served by L2 (hit rate numerator).
l2_pickstring Effective L2 pick method (site value, else the default): region or near.
Values ["region","near"]
low_hitboolean Hit rate below 30% with at least 1000 origin requests (mostly dynamic content; consider turning L2 off).
manual_off_sitesinteger Sites whose tiered origin was turned off manually (left alone when enabling on existing sites; IP sites excluded).
nameRequiredstring Group name, unique platform-wide.
node_idinteger Node ID.
node_idsRequiredinteger[] Edge node IDs to turn into L2.
nodes_pendinginteger L2 nodes awaiting origin allowlisting.
nodes_servinginteger L2 nodes serving (enabled and not reverting).
nodes_totalinteger Total L2 nodes (including disabled and reverting).
onlineboolean Online (heartbeat within 2 minutes).
only_blockboolean Some sites allow only L2 at the origin (revoke its allowlisting after revert).
only_block_sitesinteger Sites with origin allowing only L2 (greater than 0 when only_block is true).
origin_l2_onlyboolean Origin allows only L2; after the window ends the site goes down unless the origin allows edge nodes.
origin_requestsinteger Requests that reached the origin.
origin_requests_estinteger Estimate without tiering (= edge origin requests).
owner_idinteger Owner user ID.
owner_namestring Owner username.
pausedboolean Paused network-wide.
paused_atstring Paused at.
progressinteger Progress 0-100.
reasonstring Reason for disabling.
region_idinteger Region of a region default group; 0 for custom groups.
region_lastboolean It is the last enabled L2 in its region.
regionsinteger[] Served region IDs; ignored when all_regions is true.
revert_atstring Revert started at.
rolestring Primary or backup: backups stand by while a primary in the same group is up.
Values ["primary","backup"]
rulesL2Rule[] Group rules (saved with the group).
saved_bytesinteger Origin traffic saved (bytes served from L2 cache).
site_idinteger Site ID.
sitesinteger Number of sites using this group; for a region default group, the sites with L2 enabled and no group chosen (same number for every region default group).
sites_only_l2integer Sites with origin allowing only L2 (shown in the pause and add-node warnings).
statestring State: active, or reverting to edge.
Values ["active","reverting"]
thresholdsL2Thresholds Detection thresholds (read-only).
updated_atstring Last modified time.
weightinteger Weight 1-100; multiple primaries share URLs by weight.

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