Version 2.4.8 · latest

Pending nodes pending-nodes

Nodes that have enrolled with a token and await admin approval; once approved they become regular nodes.

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

Node schedulingAuthentication: Admin only3 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/pending-nodesList pending 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/pending-nodes/{id}/approveApprove pending node

Authentication: Admin only

Request body application/json

FieldTypeDescription
desstring Description
ipstring Source address of the registration connection.
namestring Name
region_idinteger Region ID
replace_node_idinteger Replace an existing primary node (new machine takes over the old one): the new node inherits the old node's lines, IP pool IP, region (when region_id is omitted), monitor settings, service period and area/bandwidth; the old node is disabled and removed from DNS, all in the approval transaction. The old node's sub IPs move to the new node by default (lines, pool IPs and monitor settings kept); see replace_sub_ips for new addresses or opting out. The old node must be an approved primary node with the same role; 409 ip_in_use when its pool IP is bound to IP sites and the IP changes.
replace_sub_ipsReplaceSubIp[] Per-sub-IP handling of the old node when replacing (only with replace_node_id); unlisted sub IPs move to the new node keeping their address. ip switches to a new address (422 conflict if another node uses it); skip=true leaves the sub IP and its lines on the old node, disabled.

Pending 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.
enabledboolean Whether enabled
enrolled_atstring Time the node registered.
hostnamestring Host name reported by the node.
idinteger Record ID
read-only
ipstring Source address of the registration connection.
monitorNodeMonitor Node monitor probe settings (the control plane probes this IP at the interval configured in monitor.node).
namestring Name
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
replace_node_idinteger Replace an existing primary node (new machine takes over the old one): the new node inherits the old node's lines, IP pool IP, region (when region_id is omitted), monitor settings, service period and area/bandwidth; the old node is disabled and removed from DNS, all in the approval transaction. The old node's sub IPs move to the new node by default (lines, pool IPs and monitor settings kept); see replace_sub_ips for new addresses or opting out. The old node must be an approved primary node with the same role; 409 ip_in_use when its pool IP is bound to IP sites and the IP changes.
replace_sub_ipsReplaceSubIp[] Per-sub-IP handling of the old node when replacing (only with replace_node_id); unlisted sub IPs move to the new node keeping their address. ip switches to a new address (422 conflict if another node uses it); skip=true leaves the sub IP and its lines on the old node, disabled.
rolestring Node role: edge or l2.
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.
updated_atstring Updated at
read-only

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