#Set the application port

PATCH /v1/infra/servers/:id/port

Sets the TCP port to which the tunnel agent proxies incoming HTTPS requests from the subdomain. By default the tunnel goes to :3000 — this is the platform standard, and most applications should listen on exactly that. This endpoint is needed in rare cases: the application works on a different port for historical reasons, or you want 0 (auto-detect) so the agent finds the listening port itself. Ports 1–1023 are forbidden — these are system ports (SSH, HTTP, HTTPS, SQL), and using them would create a risk of redirecting traffic to service processes.

#Parameters

#Request fields (body)

#Examples

#curl — personal key

# Set port 8080
curl -X PATCH https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/port \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port": 8080}'

# Automatic detection
curl -X PATCH https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/port \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port": 0}'

#curl — OAuth application

curl -X PATCH https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/port \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"port": 8080}'

#JavaScript — personal key

const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/port`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ port: 8080 }),
  }
)
const { data } = await res.json()
console.log(`Application port: ${data.port}`)

#JavaScript — OAuth application

await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/port`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ port: 0 }),
  }
)

#Response fields

#Response example

{
  "success": true,
  "data": { "port": 8080, "mode": "manual", "verified": true }
}

#Error response example

400 — a system port is forbidden:

{
  "success": false,
  "error": {
    "code": "PORT_RESTRICTED",
    "message": "System ports (1-1023) are not allowed. Use port >= 1024 or 0 for auto-detect"
  }
}

409 — the agent rejected the port change (fixed-port mode / outdated binary):

{
  "success": false,
  "error": {
    "code": "PORT_NOT_APPLIED",
    "message": "The server agent runs in fixed-port mode and cannot change its port at runtime. Repair the server (POST /v1/infra/servers/:id/repair) to switch the agent to port auto-detection, then retry.",
    "agentError": "NO_SCANNER"
  }
}

#Errors

Full list of common API errors — Errors.

#Known specifics

• System ports (1–1023) are forbidden for a reason. SSH (22), HTTP (80), HTTPS (443), DNS (53), PostgreSQL (5432), MySQL (3306) — opening a tunnel on them would create a risk of redirecting external traffic to service processes inside the virtual machine.
• How port: 0 works. The agent scans /proc/net/tcp and /proc/net/tcp6, finds the process listening on an application port (≥1024), and proxies there. Useful for applications that pick a port dynamically at startup.
• The value is preserved across agent restarts. The platform writes localPort to the server's database — after /repair or a reboot the agent will use the same value. On a /deploy with an explicit port the value is overwritten.
• port: 0 is returned in the response as 3000. This is not an error: "on auto-detect we return 3000 if nothing suitable was found". Check the actual listening port via /exec with the command ss -tlnp.
• The platform confirms the port change (data.verified). After set_port the platform probes the agent and checks the tunnel actually proxies to the requested port. verified: true — routing is ready. verified: false + data.warning — the port was saved but the agent hasn't converged yet (the auto-detector picks it up within ~30s); if the app stays unavailable longer, run /repair. 409 PORT_NOT_APPLIED — the agent did not accept the change at all: with agentError: NO_SCANNER the server runs in fixed-port mode (run your app on the current port, or /repair to switch to auto-detection); with a different agentError the agent is outdated (/repair updates it).

#See also

• Full deploy — the port field in /deploy also configures the tunnel.
• Tunnel metrics — whether there are HTTP connections and lastRequestAt.
• Run a command — ss -tlnp to check the listening ports.