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.

IP product lineAuthentication: User (some parameters admin only)8 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/ip-sitesList IP sites

Authentication: User (some parameters 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`
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
upidinteger Filter by user package.
POST/api/v2/ip-sitesCreate IP site

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
tenant_idinteger 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

FieldTypeDescription
configobject Node configuration fields (same as the site config; kind is always ip, and listen_addrs is derived from the bindings at publish time).
enabledboolean Whether enabled
ip_idsinteger[] IDs of the bound pool IPs, in order.
namestring Name
originsIpSiteOrigin[] Origin servers.
stop_codeinteger 0 = normal; non-zero = every request returns this status code (set by admins or billing).
upidinteger User package ID.
GET/api/v2/ip-sites/available-ipsIP site available IPs

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
upidRequiredinteger User package ID.
scopestring pool = the whole pool; mine = only the IPs already selected.
Values ["pool","mine"]Default "pool"
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
POST/api/v2/ip-sites/port-checkIP site port pre-check

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
tenant_idinteger 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

FieldTypeDescription
http_portsinteger[] HTTP ports to check; ports outside 1-65535 are not rejected but reported as range.
https_portsinteger[] HTTPS ports to check; ports outside 1-65535 are not rejected but reported as range.
ip_idsRequiredinteger[] IDs of the bound pool IPs, in order.
site_idinteger Pass when editing a site: ports held by this site itself are not counted as occupied.
upidRequiredinteger User package ID.
GET/api/v2/ip-sites/{id}Get IP site

Authentication: User (some parameters admin only)

PUT/api/v2/ip-sites/{id}Update IP site

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
configobject Node configuration fields (same as the site config; kind is always ip, and listen_addrs is derived from the bindings at publish time).
enabledboolean Whether enabled
ip_idsinteger[] IDs of the bound pool IPs, in order.
namestring Name
originsIpSiteOrigin[] Origin servers.
stop_codeinteger 0 = normal; non-zero = every request returns this status code (set by admins or billing).
upidinteger User package ID.
DELETE/api/v2/ip-sites/{id}Delete IP site

Authentication: User (some parameters admin only)

GET/api/v2/ip-sites/{id}/healthIP site origin health status

Authentication: User (some parameters admin only)

IP sites object

FieldTypeDescription
access_addrsstring[] Access address in ip:port form.
read-only
checked_atstring Time the details were requested from the nodes.
configobject Node configuration fields (same as the site config; kind is always ip, and listen_addrs is derived from the bindings at publish time).
created_atstring Created at
read-only
enabledboolean Whether enabled
hintsstring[] Hints (e.g. the node reported no listening ports, so that check was skipped).
read-only
http_portsinteger[] HTTP ports to check; ports outside 1-65535 are not rejected but reported as range.
https_portsinteger[] HTTPS ports to check; ports outside 1-65535 are not rejected but reported as range.
idinteger Record ID
read-only
ip_idsinteger[] IDs of the bound pool IPs, in order.
ipsIpSiteIp[] Details of the bound pool IPs.
read-only
itemsAvailableIp[] Items on this page
namestring Name
nodesSiteHealthNode[] Details from each active node, ordered by node id.
originsIpSiteOrigin[] Origin servers.
portsobject[] Per-port check results.
site_idinteger Pass when editing a site: ports held by this site itself are not counted as occupied.
statusstring 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_codeinteger 0 = normal; non-zero = every request returns this status code (set by admins or billing).
tenant_idinteger Owner tenant (user) ID
read-only
updated_atstring Updated at
read-only
upidinteger 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.

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