Version 2.4.7.20261116085428 · latest

Node groups node-groups

Groups lines under one access name; a backup threshold can switch to the backup group automatically when usable lines run low.

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

Node schedulingAuthentication: Admin only9 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/node-groupsList node groups

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`
idsstring Only list these IDs: comma-separated positive integers, at most 200 after deduplication (same as the page_size limit; more, or a malformed value, returns 422); an empty value is the same as omitting it. Combined with other filters as an intersection; IDs you cannot see are silently left out. Pagination is unchanged: set page_size to at least the number of IDs to get them in one page
POST/api/v2/node-groupsCreate node group

Authentication: Admin only

Request body application/json

FieldTypeDescription
backup_interval_sinteger Rotation interval in seconds in interval mode.
backup_ip_numinteger Number of backup IPs in use per rotation in interval mode.
backup_min_onlineinteger When usable lines in the group drop below this, access names referencing the group are switched to their own backup groups; 0 = never switch automatically, default 1 (switch when none is usable).
backup_switch_orderBackupSwitchOrder Rotation order in interval mode: seq picks the least recently used first; rand picks at random.
Values ["seq","rand"]
backup_switch_typeBackupSwitchType Backup IP switch mode. master_down: bring in as many backup IPs as there are unavailable primary IPs on the same DNS line; gt_online_ip: when online primary IPs are fewer than backup IPs, bring in backups to make up the difference (at most the number of unavailable primary IPs); interval: every IP in the group is a backup and they rotate on a timer (the group must have no primary IPs before switching to interval).
Values ["master_down","gt_online_ip","interval"]
cname_hostnamestring Host record part of the access name (for example www); lowercase letters, digits, hyphens, dot-separated labels; unique across groups (409 cname_hostname_taken); empty on create generates 8 random characters, empty on update keeps the current value.
desstring Description
nameRequiredstring Name
region_idinteger Region ID
GET/api/v2/node-groups/{id}Get node group

Authentication: Admin only

PUT/api/v2/node-groups/{id}Update node group

Authentication: Admin only

Request body application/json

FieldTypeDescription
backup_interval_sinteger Rotation interval in seconds in interval mode.
backup_ip_numinteger Number of backup IPs in use per rotation in interval mode.
backup_min_onlineinteger When usable lines in the group drop below this, access names referencing the group are switched to their own backup groups; 0 = never switch automatically, default 1 (switch when none is usable).
backup_switch_orderBackupSwitchOrder Rotation order in interval mode: seq picks the least recently used first; rand picks at random.
Values ["seq","rand"]
backup_switch_typeBackupSwitchType Backup IP switch mode. master_down: bring in as many backup IPs as there are unavailable primary IPs on the same DNS line; gt_online_ip: when online primary IPs are fewer than backup IPs, bring in backups to make up the difference (at most the number of unavailable primary IPs); interval: every IP in the group is a backup and they rotate on a timer (the group must have no primary IPs before switching to interval).
Values ["master_down","gt_online_ip","interval"]
cname_hostnamestring Host record part of the access name (for example www); lowercase letters, digits, hyphens, dot-separated labels; unique across groups (409 cname_hostname_taken); empty on create generates 8 random characters, empty on update keeps the current value.
desstring Description
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. Automatic switching to the backup group (backup_active) also changes updated_at.
namestring Name
region_idinteger Region ID
GET/api/v2/node-groups/{id}/cname-domainsList node group access names

Authentication: Admin only

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
kindNodeGroupCnameKind Only access names of this owner kind; omit for all.
Values ["package","site","stream"]
qstring Matches access names containing the term (case-insensitive).
GET/api/v2/node-groups/{id}/line-coverageNode group resolution targets

Authentication: Admin only

Query parameters

FieldTypeDescription
itemstring Option merge key (options[].key of the response); the first option when omitted.
GET/api/v2/node-groups/{id}/line-statusNode group line fallback status

Authentication: Admin only

Query parameters

FieldTypeDescription
lineRequiredstring Unified line code, such as default, isp:telecom, isp:telecom:11, pv:3:0.

Node groups object

FieldTypeDescription
backup_activeboolean Automatically switched to the backup group by monitoring (switches back once usable lines recover to the threshold).
read-only
backup_interval_sinteger Rotation interval in seconds in interval mode.
backup_ip_numinteger Number of backup IPs in use per rotation in interval mode.
backup_min_onlineinteger When usable lines in the group drop below this, access names referencing the group are switched to their own backup groups; 0 = never switch automatically, default 1 (switch when none is usable).
backup_switch_orderBackupSwitchOrder Rotation order in interval mode: seq picks the least recently used first; rand picks at random.
Values ["seq","rand"]
backup_switch_typeBackupSwitchType Backup IP switch mode. master_down: bring in as many backup IPs as there are unavailable primary IPs on the same DNS line; gt_online_ip: when online primary IPs are fewer than backup IPs, bring in backups to make up the difference (at most the number of unavailable primary IPs); interval: every IP in the group is a backup and they rotate on a timer (the group must have no primary IPs before switching to interval).
Values ["master_down","gt_online_ip","interval"]
backup_switchedstring Time of the most recent automatic switch or switch-back.
read-only
cellsLineCoverageCell[] 279 cells when mode is grid (31 provinces x any carrier and 8 carriers); empty otherwise.
cname_countsNodeGroupCnameCounts Number of access names whose primary group is this group, by owner kind; details via GET /node-groups/{id}/cname-domains.
read-only
cname_hostnamestring Host record part of the access name (for example www); lowercase letters, digits, hyphens, dot-separated labels; unique across groups (409 cname_hostname_taken); empty on create generates 8 random characters, empty on update keeps the current value.
created_atstring Created at
read-only
desstring Description
dns_readyboolean Whether at least one DNS account has been added; when false, the default line fallback never switches.
domainsLineOptionDomain[] All domains of the group (bound as main or backup group).
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. Automatic switching to the backup group (backup_active) also changes updated_at.
fqdnstring Access name (host record.root domain).
idinteger Record ID
read-only
itemstring Key of the option this response is for; empty when the group has no domains.
itemsLineStatusItem[] Items on this page
kindNodeGroupCnameKind Access name owner kind: package = shared by a purchased package, site = website, stream = TCP/UDP forwarding.
Values ["package","site","stream"]
linestring Unified line code queried.
modestring grid=279 cells; none=no line split (Cloudflare); unpulled=lines not loaded.
Values ["grid","none","unpulled"]
namestring Name
node_countinteger Number of distinct node IPs referenced by the lines in this group.
read-only
nodesLineOptionNode[] Union of unified lines (excluding default and provider-specific lines).
optionsLineCoverageOption[] All line options of the node group (domains merged by option key).
owner_idinteger Owner id (purchased package, website or TCP/UDP forwarding id, by kind).
privateLinePrivateGroup[] Provider-specific lines grouped by domain; domains without any are omitted.
pull_errstring Reason when mode is unpulled - no_credentials (account has no credentials), not_pulled (credentials present but never pulled) or the last pull error text (including unreadable credentials, naming the account); empty otherwise.
region_idinteger Region ID
site_countinteger Number of websites whose effective access name uses this group as primary group. A website with its own access name counts by that name's group, otherwise by the shared access name of its purchased package (same rule for both CNAME modes); only primary groups count, backup groups do not.
read-only
stream_countinteger Number of TCP/UDP forwarding rules whose effective access name uses this group as primary group; same rule as site_count.
read-only
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