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.
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/node-groupsList node groups
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` |
ids | string | 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 |
/api/v2/node-groupsCreate node group
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
backup_interval_s | integer | Rotation interval in seconds in interval mode. |
backup_ip_num | integer | Number of backup IPs in use per rotation in interval mode. |
backup_min_online | integer | 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_order | BackupSwitchOrder | Rotation order in interval mode: seq picks the least recently used first; rand picks at random. |
backup_switch_type | BackupSwitchType | 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). |
cname_hostname | string | 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. |
des | string | Description |
nameRequired | string | Name |
region_id | integer | Region ID |
/api/v2/node-groups/{id}Get node group
Authentication: Admin only
/api/v2/node-groups/{id}Update node group
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
backup_interval_s | integer | Rotation interval in seconds in interval mode. |
backup_ip_num | integer | Number of backup IPs in use per rotation in interval mode. |
backup_min_online | integer | 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_order | BackupSwitchOrder | Rotation order in interval mode: seq picks the least recently used first; rand picks at random. |
backup_switch_type | BackupSwitchType | 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). |
cname_hostname | string | 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. |
des | string | Description |
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. Automatic switching to the backup group (backup_active) also changes updated_at. |
name | string | Name |
region_id | integer | Region ID |
/api/v2/node-groups/{id}Delete node group
Authentication: Admin only
/api/v2/node-groups/{id}/cname-domainsList node group access names
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
kind | NodeGroupCnameKind | Only access names of this owner kind; omit for all. |
q | string | Matches access names containing the term (case-insensitive). |
/api/v2/node-groups/{id}/line-coverageNode group resolution targets
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
item | string | Option merge key (options[].key of the response); the first option when omitted. |
/api/v2/node-groups/{id}/line-optionsNode group line options
Authentication: Admin only
/api/v2/node-groups/{id}/line-statusNode group line fallback status
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
lineRequired | string | Unified line code, such as default, isp:telecom, isp:telecom:11, pv:3:0. |
Node groups object
| Field | Type | Description |
|---|---|---|
backup_active | boolean | Automatically switched to the backup group by monitoring (switches back once usable lines recover to the threshold). |
backup_interval_s | integer | Rotation interval in seconds in interval mode. |
backup_ip_num | integer | Number of backup IPs in use per rotation in interval mode. |
backup_min_online | integer | 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_order | BackupSwitchOrder | Rotation order in interval mode: seq picks the least recently used first; rand picks at random. |
backup_switch_type | BackupSwitchType | 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). |
backup_switched | string | Time of the most recent automatic switch or switch-back. |
cells | LineCoverageCell[] | 279 cells when mode is grid (31 provinces x any carrier and 8 carriers); empty otherwise. |
cname_counts | NodeGroupCnameCounts | Number of access names whose primary group is this group, by owner kind; details via GET /node-groups/{id}/cname-domains. |
cname_hostname | string | 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_at | string | Created at |
des | string | Description |
dns_ready | boolean | Whether at least one DNS account has been added; when false, the default line fallback never switches. |
domains | LineOptionDomain[] | All domains of the group (bound as main or backup group). |
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. Automatic switching to the backup group (backup_active) also changes updated_at. |
fqdn | string | Access name (host record.root domain). |
id | integer | Record ID |
item | string | Key of the option this response is for; empty when the group has no domains. |
items | LineStatusItem[] | Items on this page |
kind | NodeGroupCnameKind | Access name owner kind: package = shared by a purchased package, site = website, stream = TCP/UDP forwarding. |
line | string | Unified line code queried. |
mode | string | grid=279 cells; none=no line split (Cloudflare); unpulled=lines not loaded. |
name | string | Name |
node_count | integer | Number of distinct node IPs referenced by the lines in this group. |
nodes | LineOptionNode[] | Union of unified lines (excluding default and provider-specific lines). |
options | LineCoverageOption[] | All line options of the node group (domains merged by option key). |
owner_id | integer | Owner id (purchased package, website or TCP/UDP forwarding id, by kind). |
private | LinePrivateGroup[] | Provider-specific lines grouped by domain; domains without any are omitted. |
pull_err | string | 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_id | integer | Region ID |
site_count | integer | 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. |
stream_count | integer | Number of TCP/UDP forwarding rules whose effective access name uses this group as primary group; same rule as site_count. |
updated_at | string | Updated at |
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"
}