Version 2.4.8 · latest

TCP/UDP forwarding streams

TCP/UDP port forwarding rules. Each rule has listen ports and protocols, an origin list and a balancing method; (protocol, port) is unique platform-wide.

Pick an endpoint to see its example call on the right.

TCP/UDP forwardingAuthentication: User (some parameters admin only)6 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/streamsList streams

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
portinteger Only list forwarding rules listening on this port.
group_idinteger Only list rules in this group.
upidinteger Only list rules under this user package.
enabledboolean Filter by enabled state.
idinteger Filter by exact forwarding rule ID.
originstring Filter by substring of the origin IP.
protocolstring Only list rules that have a listener with this protocol.
Values ["tcp","udp"]
stop_codeinteger Filter by stop code; 0 = normal.
tenant_idsstring Admin only: only these tenants, comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too. Filters only and does not switch the request scope; combined with tenant_id and other filters as an intersection. A tenant credential sending a non-empty value gets 403
idsstring 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
upidsstring Filter by user packages: comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too; combined with other filters as an intersection
namestring Filter by name substring (case-insensitive).
group_idsstring Comma-separated group IDs (positive integers, at most 200 after deduplication; more, or a malformed value, returns 422); a rule in any of them matches. May be combined with group_id (both must hold).
package_idinteger Filter by base package (the owning user package was bought from it).
region_idinteger Filter by region (the CNAME's primary line group belongs to it); owners without their own CNAME use their user package's shared one.
node_group_idinteger Filter by line group (the CNAME's primary or backup line group).
cname_domain_idinteger Filter by CNAME root domain.
package_idsstring Filter by base packages, same meaning as package_id: comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too; combined with other filters as an intersection
region_idsstring Filter by regions, same meaning as region_id: comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too; combined with other filters as an intersection
node_group_idsstring Filter by line groups, same meaning as node_group_id: comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too; combined with other filters as an intersection
cname_domain_idsstring Filter by CNAME root domains, same meaning as cname_domain_id: comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too; combined with other filters as an intersection
cname_hostnamestring Filter by CNAME host label, exact match (case-insensitive, without the root domain).
sync_statestring Filter by config sync state: behind = some online node has not yet installed the config version containing its latest change;
Values ["behind","synced"]
POST/api/v2/streamsCreate stream

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
tenant_idinteger Owner tenant when an admin creates on behalf of a tenant (required); ignored for tenant callers, where the owner is always the caller.

Request body application/json

FieldTypeDescription
aclStreamAcl Layer-4 access control. Rules match the source IP or CIDR in order and the first hit decides; if none match, default_action applies; deny drops the connection immediately.
balanceStreamBalance Load balancing method. rr is round robin, ip_hash hashes the source IP, least_conn picks the fewest connections, random picks at random.
Values ["rr","ip_hash","least_conn","random"]
cnameCnameBinding Access name (CNAME). Users point their domain to fqdn with a CNAME record; the platform generates its DNS records from the node group. null when there is no access name.
conn_limitinteger Per-IP concurrent connection limit; 0 = unlimited.
enabledboolean Whether enabled
expected_updated_atstring 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; ignored on create.
group_idsinteger[] IDs of the forwarding groups this rule belongs to.
listenRequiredStreamListen[] Listener list. Each item is a port and a protocol.
namestring Name
origin_portRequiredinteger Origin port to connect to.
originsRequiredStreamOrigin[] Origin list. Each item has an origin IP, a weight, and backup/down flags.
proxy_protocolboolean Whether to send a PROXY protocol header to the origin.
stop_codeinteger 0 = normal; non-zero = new connections are dropped immediately (set by admin or billing; 512 in the snapshot when the user package has expired).
udp_responsesinteger UDP responses. 1-100 = end each UDP session after this many packets from the origin (instead of waiting for the UDP idle timeout); 0 = not set. Only for request/response traffic (DNS, probes); do not set it for games or voice that send many replies per request, or their sessions get cut short.
upidinteger User package ID (if omitted on create/update, auto-assigned when the tenant has exactly one package, expired ones included, and then checked for expiry as usual (a create gets 422 package_expired); 422 no_package when there is none, 422 required when there are several; empty falls back to tenant_id in the snapshot).
POST/api/v2/streams/batchBatch operate streams

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
tenant_idinteger Owner tenant when an admin creates on behalf of a tenant (required); ignored for tenant callers, where the owner is always the caller.

Request body application/json

FieldTypeDescription
actionRequiredstring Operation. set_enabled toggles enabled state, delete removes, set_groups replaces groups, update edits fields in bulk, create adds new ones, set_lines changes the CNAME's primary/backup line groups (admin only), set_cname_domain changes the CNAME root domain (admin only, host label kept).
Values ["set_enabled","delete","set_groups","update","create","set_lines","set_cname_domain"]
backup_group_idinteger Used by set_lines: backup line group; 0 clears it, omitted leaves it unchanged.
cname_domain_idinteger Used by set_cname_domain: the new CNAME root domain.
enabledboolean Whether enabled
group_idsinteger[] IDs of the forwarding groups this rule belongs to.
idsinteger[] IDs of the forwarding rules to operate on, at most 100 per call (required by every action except create).
itemsStreamWrite[] Used by create: the forwarding rules to create (up to 100), each shaped like the POST /streams request body.
node_group_idinteger Used by set_lines: primary line group (required).
patchStreamPatch For batch update. Fields that are given are applied to every rule, with the same rules as a single update.
region_idinteger Used by set_lines: region; when given, both line groups must belong to it.
GET/api/v2/streams/{id}Get stream

Authentication: User (some parameters admin only)

PUT/api/v2/streams/{id}Update stream

Authentication: User (some parameters admin only)

Request body application/json

FieldTypeDescription
aclStreamAcl Layer-4 access control. Rules match the source IP or CIDR in order and the first hit decides; if none match, default_action applies; deny drops the connection immediately.
balanceStreamBalance Load balancing method. rr is round robin, ip_hash hashes the source IP, least_conn picks the fewest connections, random picks at random.
Values ["rr","ip_hash","least_conn","random"]
cnameCnameBinding Access name (CNAME). Users point their domain to fqdn with a CNAME record; the platform generates its DNS records from the node group. null when there is no access name.
conn_limitinteger Per-IP concurrent connection limit; 0 = unlimited.
enabledboolean Whether enabled
expected_updated_atstring 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; ignored on create.
group_idsinteger[] IDs of the forwarding groups this rule belongs to.
listenRequiredStreamListen[] Listener list. Each item is a port and a protocol.
namestring Name
origin_portRequiredinteger Origin port to connect to.
originsRequiredStreamOrigin[] Origin list. Each item has an origin IP, a weight, and backup/down flags.
proxy_protocolboolean Whether to send a PROXY protocol header to the origin.
stop_codeinteger 0 = normal; non-zero = new connections are dropped immediately (set by admin or billing; 512 in the snapshot when the user package has expired).
udp_responsesinteger UDP responses. 1-100 = end each UDP session after this many packets from the origin (instead of waiting for the UDP idle timeout); 0 = not set. Only for request/response traffic (DNS, probes); do not set it for games or voice that send many replies per request, or their sessions get cut short.
upidinteger User package ID (if omitted on create/update, auto-assigned when the tenant has exactly one package, expired ones included, and then checked for expiry as usual (a create gets 422 package_expired); 422 no_package when there is none, 422 required when there are several; empty falls back to tenant_id in the snapshot).
DELETE/api/v2/streams/{id}Delete stream

Authentication: User (some parameters admin only)

TCP/UDP forwarding object

FieldTypeDescription
aclStreamAcl Layer-4 access control. Rules match the source IP or CIDR in order and the first hit decides; if none match, default_action applies; deny drops the connection immediately.
actionRequiredstring Operation. set_enabled toggles enabled state, delete removes, set_groups replaces groups, update edits fields in bulk, create adds new ones, set_lines changes the CNAME's primary/backup line groups (admin only), set_cname_domain changes the CNAME root domain (admin only, host label kept).
Values ["set_enabled","delete","set_groups","update","create","set_lines","set_cname_domain"]
affectedinteger Number of affected records
backup_group_idinteger Used by set_lines: backup line group; 0 clears it, omitted leaves it unchanged.
balanceStreamBalance Load balancing method. rr is round robin, ip_hash hashes the source IP, least_conn picks the fewest connections, random picks at random.
Values ["rr","ip_hash","least_conn","random"]
cnameCnameBinding Access name (CNAME). Users point their domain to fqdn with a CNAME record; the platform generates its DNS records from the node group. null when there is no access name.
cname_domain_idinteger Used by set_cname_domain: the new CNAME root domain.
conn_limitinteger Per-IP concurrent connection limit; 0 = unlimited.
created_atstring Created at
read-only
enabledboolean Whether enabled
expected_updated_atstring 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; ignored on create.
group_idsinteger[] IDs of the forwarding groups this rule belongs to.
idinteger Record ID
read-only
idsinteger[] IDs of the forwarding rules to operate on, at most 100 per call (required by every action except create).
itemsStreamWrite[] Used by create: the forwarding rules to create (up to 100), each shaped like the POST /streams request body.
listenStreamListen[] Listener list. Each item is a port and a protocol.
namestring Name
node_group_idinteger Used by set_lines: primary line group (required).
node_issuesNodeIssue[] Ports or reasons for which the forward is not fully in effect on online nodes (in the list and the detail); omitted when everything is in effect.
read-only
origin_portinteger Origin port to connect to.
originsStreamOrigin[] Origin list. Each item has an origin IP, a weight, and backup/down flags.
patchStreamPatch For batch update. Fields that are given are applied to every rule, with the same rules as a single update.
proxy_protocolboolean Whether to send a PROXY protocol header to the origin.
region_idinteger Used by set_lines: region; when given, both line groups must belong to it.
stop_codeinteger 0 = normal; non-zero = new connections are dropped immediately (set by admin or billing; 512 in the snapshot when the user package has expired).
tenant_idinteger Owner tenant (user) ID
read-only
udp_responsesinteger UDP responses. 1-100 = end each UDP session after this many packets from the origin (instead of waiting for the UDP idle timeout); 0 = not set. Only for request/response traffic (DNS, probes); do not set it for games or voice that send many replies per request, or their sessions get cut short.
updated_atstring Updated at
read-only
upidinteger User package ID (if omitted on create/update, auto-assigned when the tenant has exactly one package, expired ones included, and then checked for expiry as usual (a create gets 422 package_expired); 422 no_package when there is none, 422 required when there are several; empty falls back to tenant_id in the snapshot).

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