IP sites ip-sites
Sites served on IPs with custom ports; the IPs must first be selected in the user package.
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-sitesList IP sites
Authentication: User (some parameters 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` |
tenant_id | integer | Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data |
upid | integer | Filter by user package. |
/api/v2/ip-sitesCreate IP site
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
tenant_id | integer | Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data |
Request body application/json
| Field | Type | Description |
|---|---|---|
config | object | Node configuration fields (same as the site config; kind is always ip, and listen_addrs is derived from the bindings at publish time). |
enabled | boolean | Whether enabled |
ip_ids | integer[] | IDs of the bound pool IPs, in order. |
name | string | Name |
origins | IpSiteOrigin[] | Origin servers. |
stop_code | integer | 0 = normal; non-zero = every request returns this status code (set by admins or billing). |
upid | integer | User package ID. |
/api/v2/ip-sites/available-ipsIP site available IPs
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
upidRequired | integer | User package ID. |
scope | string | pool = the whole pool; mine = only the IPs already selected. |
tenant_id | integer | Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data |
/api/v2/ip-sites/port-checkIP site port pre-check
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
tenant_id | integer | Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data |
Request body application/json
| Field | Type | Description |
|---|---|---|
http_ports | integer[] | HTTP ports to check; ports outside 1-65535 are not rejected but reported as range. |
https_ports | integer[] | HTTPS ports to check; ports outside 1-65535 are not rejected but reported as range. |
ip_idsRequired | integer[] | IDs of the bound pool IPs, in order. |
site_id | integer | Pass when editing a site: ports held by this site itself are not counted as occupied. |
upidRequired | integer | User package ID. |
/api/v2/ip-sites/{id}Get IP site
Authentication: User (some parameters admin only)
/api/v2/ip-sites/{id}Update IP site
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
config | object | Node configuration fields (same as the site config; kind is always ip, and listen_addrs is derived from the bindings at publish time). |
enabled | boolean | Whether enabled |
ip_ids | integer[] | IDs of the bound pool IPs, in order. |
name | string | Name |
origins | IpSiteOrigin[] | Origin servers. |
stop_code | integer | 0 = normal; non-zero = every request returns this status code (set by admins or billing). |
upid | integer | User package ID. |
/api/v2/ip-sites/{id}Delete IP site
Authentication: User (some parameters admin only)
/api/v2/ip-sites/{id}/healthIP site origin health status
Authentication: User (some parameters admin only)
IP sites object
| Field | Type | Description |
|---|---|---|
access_addrs | string[] | Access address in ip:port form. |
checked_at | string | Time the details were requested from the nodes. |
config | object | Node configuration fields (same as the site config; kind is always ip, and listen_addrs is derived from the bindings at publish time). |
created_at | string | Created at |
enabled | boolean | Whether enabled |
hints | string[] | Hints (e.g. the node reported no listening ports, so that check was skipped). |
http_ports | integer[] | HTTP ports to check; ports outside 1-65535 are not rejected but reported as range. |
https_ports | integer[] | HTTPS ports to check; ports outside 1-65535 are not rejected but reported as range. |
id | integer | Record ID |
ip_ids | integer[] | IDs of the bound pool IPs, in order. |
ips | IpSiteIp[] | Details of the bound pool IPs. |
items | AvailableIp[] | Items on this page |
name | string | Name |
nodes | SiteHealthNode[] | Details from each active node, ordered by node id. |
origins | IpSiteOrigin[] | Origin servers. |
ports | object[] | Per-port check results. |
site_id | integer | Pass when editing a site: ports held by this site itself are not counted as occupied. |
status | string | disabled = active health checks are off; unknown = no node returned details; healthy = all origins up on the nodes that answered; unhealthy = some origin is removed. |
stop_code | integer | 0 = normal; non-zero = every request returns this status code (set by admins or billing). |
tenant_id | integer | Owner tenant (user) ID |
updated_at | string | Updated at |
upid | integer | User package ID. |
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"
}