Version 2.4.7.20261116085428 · latest

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.

Node schedulingAuthentication: Admin only10 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/nodesList nodes

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/nodesCreate node

Authentication: Admin only

Request body application/json

FieldTypeDescription
areastring Area (display only, never sent to nodes); empty = not set. Sub-IPs take the primary node's value.
bandwidth_mbpsinteger Node bandwidth in Mbps (display only, unrelated to monitor.bw_limit_mbps); 0 = not set. Sub-IPs take the primary node's value.
desstring Description
enabledboolean Whether enabled
ipstring Node IP address (IPv4 or IPv6).
monitorNodeMonitor Node monitor probe settings (the control plane probes this IP at the interval configured in monitor.node).
nameRequiredstring Name
parent_idinteger Primary node that owns this sub-IP; null = primary node.
region_idinteger Region ID
service_expirestring 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_startstring Server service start date YYYY-MM-DD (display only); null = not set. Sub-IPs take the primary node's value.
GET/api/v2/nodes/{id}Get node

Authentication: Admin only

Query parameters

FieldTypeDescription
capacityboolean When true, include capacity (primary nodes only; null when no system info is available).
PUT/api/v2/nodes/{id}Update node

Authentication: Admin only

Request body application/json

FieldTypeDescription
areastring Area (display only, never sent to nodes); empty = not set. Sub-IPs take the primary node's value.
bandwidth_mbpsinteger Node bandwidth in Mbps (display only, unrelated to monitor.bw_limit_mbps); 0 = not set. Sub-IPs take the primary node's value.
desstring Description
enabledboolean Whether enabled
expected_updated_atstring 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.
ipstring Node IP address (IPv4 or IPv6).
monitorNodeMonitor Node monitor probe settings (the control plane probes this IP at the interval configured in monitor.node).
namestring Name
parent_idinteger Primary node that owns this sub-IP; null = primary node.
region_idinteger Region ID
service_expirestring 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_startstring Server service start date YYYY-MM-DD (display only); null = not set. Sub-IPs take the primary node's value.
DELETE/api/v2/nodes/{id}Delete node

Authentication: Admin only

POST/api/v2/nodes/{id}/config-readmitRe-push the config a node rolled back

Authentication: Admin only

PUT/api/v2/nodes/{id}/line-tagsSet node line tags

Authentication: Admin only

Request body application/json

FieldTypeDescription
domain_idRequiredinteger Access root domain id; 0 clears the tag.
linesRequiredstring[] Unified line codes taken from the domain's line options.
POST/api/v2/nodes/{id}/revoke-certRevoke the node's current certificate

Authentication: Admin only

POST/api/v2/nodes/{id}/to-pendingMove node back to pending

Authentication: Admin only

Nodes object

FieldTypeDescription
areastring Area (display only, never sent to nodes); empty = not set. Sub-IPs take the primary node's value.
bandwidth_mbpsinteger Node bandwidth in Mbps (display only, unrelated to monitor.bw_limit_mbps); 0 = not set. Sub-IPs take the primary node's value.
capacityNodeCapacity 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.
read-only
cert_expirystring Expiry time of the most recently issued certificate; null = no certificate issued yet (or a sub-IP).
created_atstring Created at
read-only
desstring Description
disable_bystring 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.
domainstring Access root domain; empty when there is no tag.
domain_idRequiredinteger Access root domain id; 0 clears the tag.
enabledboolean Whether enabled
enrolled_atstring Time the node enrolled; null for a manually added sub-IP.
expected_updated_atstring 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.
hintsstring[] Hints (e.g. NIC addresses could not be obtained).
hostnamestring Node hostname, reported at enrollment.
idinteger Record ID
read-only
ipstring Node IP address (IPv4 or IPv6).
linesRequiredstring[] Unified line codes taken from the domain's line options.
monitorNodeMonitor Node monitor probe settings (the control plane probes this IP at the interval configured in monitor.node).
namestring Name
node_idinteger Primary node id (sub-IP tags are stored on the primary node).
opsNodeOps 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.
read-only
parent_idinteger Primary node that owns this sub-IP; null = primary node.
region_idinteger Region ID
rolestring Node role: edge for an edge node, l2 for a second-tier cache node.
Values ["edge","l2"]
service_expirestring 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_startstring Server service start date YYYY-MM-DD (display only); null = not set. Sub-IPs take the primary node's value.
statusstring ok = result available; pending = command queued, fetch again later; unknown = node offline.
Values ["ok","pending","unknown"]
updated_atstring Updated at
read-only
v4string[] IPv4 addresses on the node's NICs.
v6string[] 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.

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