IP pools ip-pools
IP pools and the IPs inside them, maintained by admins. A pool belongs to a region and its name is unique platform-wide.
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/ip-poolsList IP pools
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` |
region_id | integer | Filter by region. |
/api/v2/ip-poolsCreate IP pool
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
des | string | Description |
nameRequired | string | Name |
region_idRequired | integer | Region ID |
/api/v2/ip-pools/candidatesIP pool candidate node IPs
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
region_idRequired | integer | Region ID. |
/api/v2/ip-pools/{id}Get IP pool
Authentication: Admin only
/api/v2/ip-pools/{id}Update IP pool
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
des | string | Description |
nameRequired | string | Name |
region_idRequired | integer | Region ID |
/api/v2/ip-pools/{id}Delete IP pool
Authentication: Admin only
/api/v2/ip-pools/{id}/refsIP pool referencing sites
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
ip_id | integer | Show only this pool IP. |
limit | integer | Maximum number of sites listed per IP. |
/api/v2/ip-pools/{pool_id}/ipsList IPs in pool
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/ip-pools/{pool_id}/ipsAdd IP to pool
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
bind_addr | string | The local address the node actually listens on (NAT setups); null means use ip. |
node_idRequired | integer | Node ID |
/api/v2/ip-pools/{pool_id}/ips/{id}Update pool IP
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
bind_addr | string | The local address the node actually listens on (NAT setups); null means use ip. |
enabled | boolean | Whether enabled |
/api/v2/ip-pools/{pool_id}/ips/{id}Remove IP from pool
Authentication: Admin only
/api/v2/ip-pools/{pool_id}/ips/{id}/issue-certIssue platform certificate for pool IP
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
confirm | boolean | Confirm re-issuing when a valid certificate already exists. |
IP pools object
| Field | Type | Description |
|---|---|---|
bind_addr | string | The local address the node actually listens on (NAT setups); null means use ip. |
cert | IpCertState | Platform IP certificate status. |
confirm | boolean | Confirm re-issuing when a valid certificate already exists. |
created_at | string | Created at |
des | string | Description |
enabled | boolean | Whether enabled |
hints | string[] | Hints (e.g. the node reported no NIC addresses, so the pool entry was not verified). |
id | integer | Record ID |
ip | string | IP address. |
ip_count | integer | Number of IPs in the pool. |
ips | object[] | Pool IPs that have references, with their referencing sites. |
items | IpCandidate[] | Items on this page |
name | string | Name |
node_id | integer | Node ID |
node_name | string | Name of the node that owns the IP. |
node_state | IpNodeState | State of the owning primary node: disabled if the node is disabled; otherwise online if a heartbeat arrived in the last 2 minutes, else offline. |
pool_id | integer | ID of the IP pool it belongs to. |
region_id | integer | Region ID |
region_name | string | Region name. |
site_count | integer | Number of IP sites referencing IPs in the pool (deduplicated by site). |
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"
}