Lines lines
A resolution record in a node group, showing which DNS line and weight a node appears with; a line must be disabled before it can be deleted.
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/linesList lines
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/linesCreate line
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
dns_line | string | DNS resolution line code (default = default line; carrier/region line codes are mapped by the DNS domain). |
enabled | boolean | Whether enabled |
force | boolean | Force the write and skip two safeguards (requires a second confirmation): when the line becomes an enabled primary line, its node must have applied its configuration and be at most one release behind (otherwise 422 node_config_behind); disabling the last enabled primary line of the node group or making it a backup (otherwise 422 last_primary_line). |
is_backup | boolean | Backup IP; kept out of DNS normally and brought in or taken out automatically according to the node group's backup IP switch mode. |
is_backup_default | boolean | Default line fallback; when the node group's default line has no usable IP, this line's IP is automatically resolved on the default line instead (its own line stops using it meanwhile), and switched back once the default line recovers. |
node_group_idRequired | integer | ID of the node group this line belongs to. |
node_idRequired | integer | Node ID |
weight | integer | Weight, 1 to 100; a larger weight receives a larger share of resolutions. |
/api/v2/lines/{id}Get line
Authentication: Admin only
/api/v2/lines/{id}Update line
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
dns_line | string | DNS resolution line code (default = default line; carrier/region line codes are mapped by the DNS domain). |
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. The scheduled jobs bringing backup IPs or the default line fallback in or out, and monitoring enabling or disabling the line, also change updated_at. |
force | boolean | Force the write and skip two safeguards (requires a second confirmation): when the line becomes an enabled primary line, its node must have applied its configuration and be at most one release behind (otherwise 422 node_config_behind); disabling the last enabled primary line of the node group or making it a backup (otherwise 422 last_primary_line). |
is_backup | boolean | Backup IP; kept out of DNS normally and brought in or taken out automatically according to the node group's backup IP switch mode. |
is_backup_default | boolean | Default line fallback; when the node group's default line has no usable IP, this line's IP is automatically resolved on the default line instead (its own line stops using it meanwhile), and switched back once the default line recovers. |
node_group_id | integer | ID of the node group this line belongs to. |
node_id | integer | Node ID |
weight | integer | Weight, 1 to 100; a larger weight receives a larger share of resolutions. |
/api/v2/lines/{id}Delete line
Authentication: Admin only
Lines object
| Field | Type | Description |
|---|---|---|
backup_default_on | boolean | Whether the default line fallback is currently in use and this IP is resolved on the default line (read-only, maintained by the scheduled job). |
backup_on | boolean | Whether this backup IP is currently in DNS (read-only, maintained by the scheduled job). |
created_at | string | Created at |
disable_by | string | Disable source (manual by admin, monitor by node monitoring, bandwidth for bandwidth limit, license for provider revocation, trial for trial ended, drain for node self-removal before a restart, etc.); empty when enabled. |
dns_line | string | DNS resolution line code (default = default line; carrier/region line codes are mapped by the DNS domain). |
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. The scheduled jobs bringing backup IPs or the default line fallback in or out, and monitoring enabling or disabling the line, also change updated_at. |
force | boolean | Force the write and skip two safeguards (requires a second confirmation): when the line becomes an enabled primary line, its node must have applied its configuration and be at most one release behind (otherwise 422 node_config_behind); disabling the last enabled primary line of the node group or making it a backup (otherwise 422 last_primary_line). |
id | integer | Record ID |
is_backup | boolean | Backup IP; kept out of DNS normally and brought in or taken out automatically according to the node group's backup IP switch mode. |
is_backup_default | boolean | Default line fallback; when the node group's default line has no usable IP, this line's IP is automatically resolved on the default line instead (its own line stops using it meanwhile), and switched back once the default line recovers. |
node_group_id | integer | ID of the node group this line belongs to. |
node_id | integer | Node ID |
updated_at | string | Updated at |
weight | integer | Weight, 1 to 100; a larger weight receives a larger share of resolutions. |
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"
}