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.
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/l2/enable-batchAdd L2 nodes in batch
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
apply_sites | boolean | 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_idsRequired | integer[] | Edge node IDs to turn into L2. |
/api/v2/l2/groupsList L2 groups
Authentication: Admin only
/api/v2/l2/groupsCreate L2 group
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
all_regions | boolean | Serve all regions (requires cross_region). |
balance | string | Distribution: url_hash pins by URL, rr round-robin. |
cross_region | boolean | Allow cross-region use (required for nodes outside the regions or all regions; adds about 50-200 ms). |
nameRequired | string | Group name, unique platform-wide. |
node_ids | integer[] | Edge node IDs to turn into L2. |
regions | integer[] | Served region IDs; ignored when all_regions is true. |
rules | L2Rule[] | Group rules (saved with the group). |
/api/v2/l2/groups/{id}Get L2 group
Authentication: Admin only
/api/v2/l2/groups/{id}Update L2 group
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
all_regions | boolean | Serve all regions (requires cross_region). |
balance | string | Distribution: url_hash pins by URL, rr round-robin. |
cross_region | boolean | Allow cross-region use (required for nodes outside the regions or all regions; adds about 50-200 ms). |
name | string | Group name, unique platform-wide. |
node_ids | integer[] | Edge node IDs to turn into L2. |
regions | integer[] | Served region IDs; ignored when all_regions is true. |
rules | L2Rule[] | Group rules (saved with the group). |
/api/v2/l2/groups/{id}Delete L2 group
Authentication: Admin only
/api/v2/l2/groups/{id}/copyCopy L2 group
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
nameRequired | string | Group name, unique platform-wide. |
/api/v2/l2/groups/{id}/reset-sitesReset sites of a group to region default
Authentication: Admin only
/api/v2/l2/nodesList L2 nodes
Authentication: Admin only
/api/v2/l2/nodes/{id}Update L2 node
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
access_addr | string | Private address edges use to reach it (IP only, no port; IPv4-mapped IPv6 is stored as IPv4); empty means the public IP. |
role | string | Primary or backup: backups stand by while a primary in the same group is up. |
weight | integer | Weight 1-100; multiple primaries share URLs by weight. |
/api/v2/l2/nodes/{id}/disableDisable L2 node
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
reason | string | Reason for disabling. |
/api/v2/l2/nodes/{id}/enableEnable L2 node
Authentication: Admin only
/api/v2/l2/nodes/{id}/impactImpact before revert or disable
Authentication: Admin only
/api/v2/l2/nodes/{id}/mark-allowedMark origins as allowing the node
Authentication: Admin only
/api/v2/l2/nodes/{id}/probe-accessCheck whether origins allow the node
Authentication: Admin only
/api/v2/l2/nodes/{id}/revertRevert to edge node
Authentication: Admin only
/api/v2/l2/pausePause tiered origin network-wide
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
auto_resume_at | string | Automatic resume time (must be in the future); omit for manual resume. |
/api/v2/l2/recommendOne-click enable recommendation
Authentication: Admin only
/api/v2/l2/resumeResume tiered origin network-wide
Authentication: Admin only
/api/v2/l2/revoke-impactLicense loss impact and fallback window
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
/api/v2/l2/statsTiered origin statistics
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
startRequired | string | Start time (inclusive), RFC 3339 |
endRequired | string | End time (exclusive), RFC 3339 |
/api/v2/l2/stats/nodesStatistics by L2 node
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
startRequired | string | Start time (inclusive), RFC 3339 |
endRequired | string | End time (exclusive), RFC 3339 |
/api/v2/l2/stats/sitesTiered origin statistics by site
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
startRequired | string | Start time (inclusive), RFC 3339 |
endRequired | string | End time (exclusive), RFC 3339 |
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
domain | string | Substring of the primary domain, case-insensitive. |
/api/v2/l2/statusTiered origin overview
Authentication: Admin only
/api/v2/l2/tasks/{id}Get L2 task progress
Authentication: Admin only
Tiered origin (L2) object
| Field | Type | Description |
|---|---|---|
access_addr | string | Private address edges use to reach it (IP only, no port; IPv4-mapped IPv6 is stored as IPv4); empty means the public IP. |
all_regions | boolean | Serve all regions (requires cross_region). |
allow | string | Origin allowlisting: empty if not applicable, pending (cacheable requests only), or allowed. |
allow_since | string | Pending since; turns allowed after 24 hours. |
apply_sites | boolean | 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_at | string | Automatic resume time (must be in the future); omit for manual resume. |
balance | string | Distribution: url_hash pins by URL, rr round-robin. |
checked_at | string | Checked at. |
created_at | string | Started at. |
cross_region | boolean | Allow cross-region use (required for nodes outside the regions or all regions; adds about 50-200 ms). |
defaults | L2Defaults | Defaults (change via PUT /configs/l2.defaults). |
disabled_at | string | Disabled at. |
disabled_reason | string | Reason for disabling. |
edge_origin_requests | integer | Edge origin requests (hit rate denominator). |
empty_group | integer[] | Groups left without a serving L2 (their sites will bypass temporarily). |
enabled | boolean | Enabled; a disabled node stays L2 and keeps its cache. |
feature | string | 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). |
finished_at | string | Finished at. |
groups | integer[] | IDs of L2 groups containing it. |
hit_rate | number | Hit rate 0-1; 0 when there were no origin requests. |
host | string | Primary domain of the site. |
id | integer | Group ID. |
ip | string | Public IP. |
is_region_default | boolean | Region default group (one per region; cannot be deleted, only its distribution can change). |
items | L2Group[] | L2 groups. |
kind | string | Task kind: enable adds L2, revert returns to edge. |
l2_group_id | integer | L2 group chosen by the site; null means region default. |
l2_group_name | string | L2 group name; empty for region default. |
l2_hit_requests | integer | Origin requests served by L2 (hit rate numerator). |
l2_pick | string | Effective L2 pick method (site value, else the default): region or near. |
low_hit | boolean | Hit rate below 30% with at least 1000 origin requests (mostly dynamic content; consider turning L2 off). |
manual_off_sites | integer | Sites whose tiered origin was turned off manually (left alone when enabling on existing sites; IP sites excluded). |
nameRequired | string | Group name, unique platform-wide. |
node_id | integer | Node ID. |
node_idsRequired | integer[] | Edge node IDs to turn into L2. |
nodes_pending | integer | L2 nodes awaiting origin allowlisting. |
nodes_serving | integer | L2 nodes serving (enabled and not reverting). |
nodes_total | integer | Total L2 nodes (including disabled and reverting). |
online | boolean | Online (heartbeat within 2 minutes). |
only_block | boolean | Some sites allow only L2 at the origin (revoke its allowlisting after revert). |
only_block_sites | integer | Sites with origin allowing only L2 (greater than 0 when only_block is true). |
origin_l2_only | boolean | Origin allows only L2; after the window ends the site goes down unless the origin allows edge nodes. |
origin_requests | integer | Requests that reached the origin. |
origin_requests_est | integer | Estimate without tiering (= edge origin requests). |
owner_id | integer | Owner user ID. |
owner_name | string | Owner username. |
paused | boolean | Paused network-wide. |
paused_at | string | Paused at. |
progress | integer | Progress 0-100. |
reason | string | Reason for disabling. |
region_id | integer | Region of a region default group; 0 for custom groups. |
region_last | boolean | It is the last enabled L2 in its region. |
regions | integer[] | Served region IDs; ignored when all_regions is true. |
revert_at | string | Revert started at. |
role | string | Primary or backup: backups stand by while a primary in the same group is up. |
rules | L2Rule[] | Group rules (saved with the group). |
saved_bytes | integer | Origin traffic saved (bytes served from L2 cache). |
site_id | integer | Site ID. |
sites | integer | 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_l2 | integer | Sites with origin allowing only L2 (shown in the pause and add-node warnings). |
state | string | State: active, or reverting to edge. |
thresholds | L2Thresholds | Detection thresholds (read-only). |
updated_at | string | Last modified time. |
weight | integer | 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.
{
"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"
}