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.
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/streamsList streams
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 |
port | integer | Only list forwarding rules listening on this port. |
group_id | integer | Only list rules in this group. |
upid | integer | Only list rules under this user package. |
enabled | boolean | Filter by enabled state. |
id | integer | Filter by exact forwarding rule ID. |
origin | string | Filter by substring of the origin IP. |
protocol | string | Only list rules that have a listener with this protocol. |
stop_code | integer | Filter by stop code; 0 = normal. |
tenant_ids | string | 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 |
ids | string | 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 |
upids | string | 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 |
name | string | Filter by name substring (case-insensitive). |
group_ids | string | 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_id | integer | Filter by base package (the owning user package was bought from it). |
region_id | integer | 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_id | integer | Filter by line group (the CNAME's primary or backup line group). |
cname_domain_id | integer | Filter by CNAME root domain. |
package_ids | string | 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_ids | string | 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_ids | string | 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_ids | string | 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_hostname | string | Filter by CNAME host label, exact match (case-insensitive, without the root domain). |
sync_state | string | Filter by config sync state: behind = some online node has not yet installed the config version containing its latest change; |
/api/v2/streamsCreate stream
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
tenant_id | integer | 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
| Field | Type | Description |
|---|---|---|
acl | StreamAcl | 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. |
balance | StreamBalance | Load balancing method. rr is round robin, ip_hash hashes the source IP, least_conn picks the fewest connections, random picks at random. |
cname | CnameBinding | 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_limit | integer | Per-IP concurrent connection limit; 0 = unlimited. |
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; ignored on create. |
group_ids | integer[] | IDs of the forwarding groups this rule belongs to. |
listenRequired | StreamListen[] | Listener list. Each item is a port and a protocol. |
name | string | Name |
origin_portRequired | integer | Origin port to connect to. |
originsRequired | StreamOrigin[] | Origin list. Each item has an origin IP, a weight, and backup/down flags. |
proxy_protocol | boolean | Whether to send a PROXY protocol header to the origin. |
stop_code | integer | 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_responses | integer | 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. |
upid | integer | 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). |
/api/v2/streams/batchBatch operate streams
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
tenant_id | integer | 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
| Field | Type | Description |
|---|---|---|
actionRequired | string | 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). |
backup_group_id | integer | Used by set_lines: backup line group; 0 clears it, omitted leaves it unchanged. |
cname_domain_id | integer | Used by set_cname_domain: the new CNAME root domain. |
enabled | boolean | Whether enabled |
group_ids | integer[] | IDs of the forwarding groups this rule belongs to. |
ids | integer[] | IDs of the forwarding rules to operate on, at most 100 per call (required by every action except create). |
items | StreamWrite[] | Used by create: the forwarding rules to create (up to 100), each shaped like the POST /streams request body. |
node_group_id | integer | Used by set_lines: primary line group (required). |
patch | StreamPatch | For batch update. Fields that are given are applied to every rule, with the same rules as a single update. |
region_id | integer | Used by set_lines: region; when given, both line groups must belong to it. |
/api/v2/streams/{id}Get stream
Authentication: User (some parameters admin only)
/api/v2/streams/{id}Update stream
Authentication: User (some parameters admin only)
Request body application/json
| Field | Type | Description |
|---|---|---|
acl | StreamAcl | 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. |
balance | StreamBalance | Load balancing method. rr is round robin, ip_hash hashes the source IP, least_conn picks the fewest connections, random picks at random. |
cname | CnameBinding | 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_limit | integer | Per-IP concurrent connection limit; 0 = unlimited. |
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; ignored on create. |
group_ids | integer[] | IDs of the forwarding groups this rule belongs to. |
listenRequired | StreamListen[] | Listener list. Each item is a port and a protocol. |
name | string | Name |
origin_portRequired | integer | Origin port to connect to. |
originsRequired | StreamOrigin[] | Origin list. Each item has an origin IP, a weight, and backup/down flags. |
proxy_protocol | boolean | Whether to send a PROXY protocol header to the origin. |
stop_code | integer | 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_responses | integer | 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. |
upid | integer | 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). |
/api/v2/streams/{id}Delete stream
Authentication: User (some parameters admin only)
TCP/UDP forwarding object
| Field | Type | Description |
|---|---|---|
acl | StreamAcl | 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. |
actionRequired | string | 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). |
affected | integer | Number of affected records |
backup_group_id | integer | Used by set_lines: backup line group; 0 clears it, omitted leaves it unchanged. |
balance | StreamBalance | Load balancing method. rr is round robin, ip_hash hashes the source IP, least_conn picks the fewest connections, random picks at random. |
cname | CnameBinding | 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_id | integer | Used by set_cname_domain: the new CNAME root domain. |
conn_limit | integer | Per-IP concurrent connection limit; 0 = unlimited. |
created_at | string | Created at |
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; ignored on create. |
group_ids | integer[] | IDs of the forwarding groups this rule belongs to. |
id | integer | Record ID |
ids | integer[] | IDs of the forwarding rules to operate on, at most 100 per call (required by every action except create). |
items | StreamWrite[] | Used by create: the forwarding rules to create (up to 100), each shaped like the POST /streams request body. |
listen | StreamListen[] | Listener list. Each item is a port and a protocol. |
name | string | Name |
node_group_id | integer | Used by set_lines: primary line group (required). |
node_issues | NodeIssue[] | 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. |
origin_port | integer | Origin port to connect to. |
origins | StreamOrigin[] | Origin list. Each item has an origin IP, a weight, and backup/down flags. |
patch | StreamPatch | For batch update. Fields that are given are applied to every rule, with the same rules as a single update. |
proxy_protocol | boolean | Whether to send a PROXY protocol header to the origin. |
region_id | integer | Used by set_lines: region; when given, both line groups must belong to it. |
stop_code | integer | 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_id | integer | Owner tenant (user) ID |
udp_responses | integer | 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_at | string | Updated at |
upid | integer | 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.
{
"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"
}