Nodes nodes
Approved edge nodes and sub-IPs; primary nodes self-enroll with an enrollment token, while sub-IPs are added manually by an admin.
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/nodesList nodes
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/nodesCreate node
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
area | string | Area (display only, never sent to nodes); empty = not set. Sub-IPs take the primary node's value. |
bandwidth_mbps | integer | Node bandwidth in Mbps (display only, unrelated to monitor.bw_limit_mbps); 0 = not set. Sub-IPs take the primary node's value. |
des | string | Description |
enabled | boolean | Whether enabled |
ip | string | Node IP address (IPv4 or IPv6). |
monitor | NodeMonitor | Node monitor probe settings (the control plane probes this IP at the interval configured in monitor.node). |
nameRequired | string | Name |
parent_id | integer | Primary node that owns this sub-IP; null = primary node. |
region_id | integer | Region ID |
service_expire | string | Server service expiry date YYYY-MM-DD (used for the home-page expiry reminder; never auto-disables); null = not set, no reminder. Sub-IPs take the primary node's value. |
service_start | string | Server service start date YYYY-MM-DD (display only); null = not set. Sub-IPs take the primary node's value. |
/api/v2/nodes/{id}Get node
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
capacity | boolean | When true, include capacity (primary nodes only; null when no system info is available). |
/api/v2/nodes/{id}Update node
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
area | string | Area (display only, never sent to nodes); empty = not set. Sub-IPs take the primary node's value. |
bandwidth_mbps | integer | Node bandwidth in Mbps (display only, unrelated to monitor.bw_limit_mbps); 0 = not set. Sub-IPs take the primary node's value. |
des | string | Description |
enabled | boolean | Whether enabled |
expected_updated_at | string | Optimistic lock (used on update) - the updated_at of the resource as the caller read it. If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check. Heartbeats do not change updated_at; monitoring auto enable/disable, HTTP/3 and TFO probe switching, L2 assignment/removal and node replacement do. |
ip | string | Node IP address (IPv4 or IPv6). |
monitor | NodeMonitor | Node monitor probe settings (the control plane probes this IP at the interval configured in monitor.node). |
name | string | Name |
parent_id | integer | Primary node that owns this sub-IP; null = primary node. |
region_id | integer | Region ID |
service_expire | string | Server service expiry date YYYY-MM-DD (used for the home-page expiry reminder; never auto-disables); null = not set, no reminder. Sub-IPs take the primary node's value. |
service_start | string | Server service start date YYYY-MM-DD (display only); null = not set. Sub-IPs take the primary node's value. |
/api/v2/nodes/{id}Delete node
Authentication: Admin only
/api/v2/nodes/{id}/config-readmitRe-push the config a node rolled back
Authentication: Admin only
/api/v2/nodes/{id}/line-tagsSet node line tags
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
domain_idRequired | integer | Access root domain id; 0 clears the tag. |
linesRequired | string[] | Unified line codes taken from the domain's line options. |
/api/v2/nodes/{id}/local-addrsNode NIC addresses
Authentication: Admin only
/api/v2/nodes/{id}/revoke-certRevoke the node's current certificate
Authentication: Admin only
/api/v2/nodes/{id}/to-pendingMove node back to pending
Authentication: Admin only
Nodes object
| Field | Type | Description |
|---|---|---|
area | string | Area (display only, never sent to nodes); empty = not set. Sub-IPs take the primary node's value. |
bandwidth_mbps | integer | Node bandwidth in Mbps (display only, unrelated to monitor.bw_limit_mbps); 0 = not set. Sub-IPs take the primary node's value. |
capacity | NodeCapacity | Node memory capacity (read-only, only returned by GET /nodes/{id}?capacity=true): per-site resident cost = locations × 28.1KB + HTTPS ratio × 25.5KB, budget = memory MiB × 0.25 / 2 − 28MiB, limit = budget / per-site cost. null = no system info for the node or memory total missing. |
cert_expiry | string | Expiry time of the most recently issued certificate; null = no certificate issued yet (or a sub-IP). |
created_at | string | Created at |
des | string | Description |
disable_by | string | Disable source (manual = admin; monitor = auto-disabled by node monitoring and re-enabled once probes recover; bandwidth = auto-disabled when outbound bandwidth exceeds monitor.bw_limit_mbps and re-enabled when it drops back; license = license revoked by the provider; trial = trial ended and the node stopped serving, restored automatically after purchase; drain = the node asked to be removed from DNS before restarting nginx for an upgrade, added back automatically once its self-check passes or reclaimed by the master on timeout); empty when enabled. |
domain | string | Access root domain; empty when there is no tag. |
domain_idRequired | integer | Access root domain id; 0 clears the tag. |
enabled | boolean | Whether enabled |
enrolled_at | string | Time the node enrolled; null for a manually added sub-IP. |
expected_updated_at | string | Optimistic lock (used on update) - the updated_at of the resource as the caller read it. If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check. Heartbeats do not change updated_at; monitoring auto enable/disable, HTTP/3 and TFO probe switching, L2 assignment/removal and node replacement do. |
hints | string[] | Hints (e.g. NIC addresses could not be obtained). |
hostname | string | Node hostname, reported at enrollment. |
id | integer | Record ID |
ip | string | Node IP address (IPv4 or IPv6). |
linesRequired | string[] | Unified line codes taken from the domain's line options. |
monitor | NodeMonitor | Node monitor probe settings (the control plane probes this IP at the interval configured in monitor.node). |
name | string | Name |
node_id | integer | Primary node id (sub-IP tags are stored on the primary node). |
ops | NodeOps | Node operations status (read-only, from heartbeats): online, whether the config lags behind the latest published version, and clock sync. Sub-IPs follow their primary node. |
parent_id | integer | Primary node that owns this sub-IP; null = primary node. |
region_id | integer | Region ID |
role | string | Node role: edge for an edge node, l2 for a second-tier cache node. |
service_expire | string | Server service expiry date YYYY-MM-DD (used for the home-page expiry reminder; never auto-disables); null = not set, no reminder. Sub-IPs take the primary node's value. |
service_start | string | Server service start date YYYY-MM-DD (display only); null = not set. Sub-IPs take the primary node's value. |
status | string | ok = result available; pending = command queued, fetch again later; unknown = node offline. |
updated_at | string | Updated at |
v4 | string[] | IPv4 addresses on the node's NICs. |
v6 | string[] | IPv6 addresses on the node's NICs. |
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"
}