Tunnels
Create tunnels, change their configuration and choose which device runs them.
List tunnels
Returns tunnels newest first. Use limit and cursor for pagination.
curl "https://api.portwarp.com/v2/tunnels?limit=25" \
-H "Authorization: Bearer $PORTWARP_API_KEY"Create a tunnel
Creates a tunnel and returns it with status 201. Idempotency required.
| Field | Use |
|---|---|
| local_port | Required. Local service port, 1 to 65535. |
| protocol | tcp, udp, both or http. Default: tcp. |
| local_host | Local target visible to the client. Default: 127.0.0.1. |
| name | Optional display name. |
| region / country | Optional placement preference. |
| game_preset_id | Preset ID returned by GET /presets. |
| subdomain | Optional requested platform subdomain. |
| pro_network | Use PRO Network when true. Defaults to true for eligible accounts. |
| http_ssl_enabled | Enable managed HTTPS for HTTP tunnels. |
| http_basic_auth_* | Optional username and password protection for HTTP tunnels. |
| device_ids | Optional device allowlist. An empty array allows any authorized device. |
| extra_ports | Optional array of {label, local_port, protocol}. |
{
"name": "Minecraft",
"protocol": "tcp",
"local_port": 25565,
"device_ids": ["DEVICE_ID"],
"extra_ports": [{"label": "Query", "local_port": 25565, "protocol": "udp"}]
}Get, update or delete a tunnel
Returns one tunnel, including its public address, current device, authorized devices and extra ports.
Updates only supplied fields. Supported fields: name, local_host, local_port, http_ssl_enabled, HTTP basic-auth fields, idle_timeout, buffer_size and pro_network. Use the domain endpoints below for custom domains.
{"name":"Production API","local_port":8080}Permanently removes the tunnel. Idempotency required.
Choose allowed devices
Replaces the full device allowlist. Idempotency required.
| Body | Behavior |
|---|---|
{"device_ids":[]} | Any authorized device may run the tunnel. |
| One ID | Only that device may run it. |
| Several IDs | Any listed device may run it, but never simultaneously. |
Start, stop or restart
Starts the tunnel on device_id and returns a 202 operation. Set handoff to true only to stop the current executor and continue on another device. Idempotency required.
{"device_id":"DEVICE_ID","handoff":false}The device must be online, allowed by the tunnel and locally enabled for remote control. If another device is running the tunnel, start returns 409 tunnel_already_running unless handoff is true.
Stops the current executor and returns a 202 operation. Send an empty JSON object. Idempotency required.
Restarts the tunnel on its current executor and returns a 202 operation. Send an empty JSON object. Idempotency required.
Extra ports
Lists additional port mappings for the tunnel.
Adds one port mapping. Idempotency required.
{"label":"Query","local_port":25565,"protocol":"udp"}Removes one extra port. Idempotency required.
Custom domain
Returns the current custom-domain status and DNS information.
Checks whether the domain's CNAME is ready. Send {"domain":"play.example.com"}. Idempotency required.
Assigns a verified domain. Send {"domain":"play.example.com"}. Idempotency required.
Removes the custom domain. Idempotency required.
Firewall and GeoIP
Lists enabled IP allow/block rules.
Replaces every firewall rule. Send rules with rule_type (whitelist or blacklist), one of ip_address/ip_cidr, and optional description. Idempotency required.
{
"rules": [
{
"rule_type": "whitelist",
"ip_cidr": "203.0.113.0/24",
"description": "Office"
}
]
}Lists enabled country rules.
Replaces every country rule. Use two-letter ISO country codes and allow or block. Idempotency required.
{
"rules": [
{"country_code": "BR", "action": "allow"}
]
}Placement, usage and sessions
Moves the tunnel to a node returned by GET /nodes. Send {"node_id":"NODE_ID"}. Returns 202. Idempotency required.
Returns bandwidth totals for today and the current month.
Returns recent runtime sessions with device, timestamps, duration, traffic and end reason. Accepts limit from 1 to 100 and an opaque cursor.