Configure Dedicated Ports

PUT /v1/endpoints/{uuid}/ports

Assign dedicated TCP/UDP ports to an endpoint. By default, TCP and UDP endpoints share the platform's port pool — clients connect to tunnel-server:443 with SNI/ALPN to route. With dedicated ports, the endpoint is reachable directly at tunnel-server:<port>, no SNI required. Useful for databases, game servers, MUDs, or any TCP/UDP client that doesn't speak SNI.

This is a plan-gated feature — your plan must include the dedicated_ports entitlement, and you may have a per-plan max-count cap (-1 means unlimited). Some plans also require an extra verification gate (email verified, payment method on file, ID verified) before dedicated ports are usable.

Pass null for either field to clear that port assignment. If the requested port is already in use by another endpoint on that protocol you'll get a 409 — pick a different port. Ports are per protocol: another endpoint may hold the same number over the other protocol (for example TCP 5000 on one endpoint and UDP 5000 on another), and one endpoint may use the same number for both. The platform stores exactly the ports you request (it does not silently reassign).

Path parameters

uuid string (uuid) Req
Endpoint UUID.

Request body

dedicated_tcp_port int | null
TCP port to assign. Range: 1024–65535. Pass null to clear.
dedicated_udp_port int | null
UDP port to assign. Range: 1024–65535. Pass null to clear.

Response (200 OK)

ok boolean
Always true on success.
dedicated_tcp_port int | null
The assigned TCP port (echo of the request), or null if cleared.
dedicated_udp_port int | null
The assigned UDP port (echo of the request), or null if cleared.

Errors

400 Bad Request
Unknown fields, invalid JSON, port outside 1024–65535.
401 Unauthorized
Missing auth.
403 Forbidden
Plan doesn't include the dedicated_ports entitlement, max-count limit reached, or verification gate not satisfied. Verification failures return JSON with error: "verification_required" + gate_type.
404 Not Found
Endpoint doesn't exist or belongs to another user.
409 Conflict
Requested port is already in use by another endpoint on that protocol (the message names it, e.g. "UDP port 20004 is already in use"). Pick a different port or omit the field to let the platform assign one.
Request
curl -X PUT "https://api.ngris.com/v1/endpoints/<uuid>/ports" \ -H "X-API-KEY: <your_api_key>" \ -H "Content-Type: application/json" \ -d '{ "dedicated_tcp_port": 25565, "dedicated_udp_port": null }'
Python
from ngris import Ngris client = Ngris(api_key="<your_api_key>") client._put_raw("/endpoints/<endpoint_uuid>/ports", { "dedicated_tcp_port": 25565, "dedicated_udp_port": None, })
Response — 200 OK
{ "ok": true, "dedicated_tcp_port": 25565, "dedicated_udp_port": null }
Error — verification gate
{ "error": "verification_required", "gate_type": "payment_method", "feature": "dedicated_ports", "message": "Dedicated ports require a payment method on file." }
Was this helpful?
On this page
Configure Dedicated Ports
Was this helpful?
Homepage Docs Dashboard Docs API Docs nvelox Dashboard