Для AI-агентов: markdown этой страницы — /docs-content/infra/deploy/port.md индекс документации — /llms.txt

Задать порт приложения

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

Задаёт TCP-порт, на который агент туннеля проксирует входящие HTTPS-запросы с субдомена. По умолчанию туннель идёт на :3000 — это стандарт платформы, большинство приложений должны слушать именно его. Этот эндпоинт нужен в редких случаях: приложение по историческим причинам работает на другом порту или вы хотите 0 (автоопределение), чтобы агент сам нашёл слушающий порт. Порты 1–1023 запрещены — это системные (SSH, HTTP, HTTPS, SQL), их использование создало бы риск перенаправления трафика на служебные процессы.

Параметры

Параметр	В	Тип	Обяз.	Описание
`id`	path	string (UUID)	да	ID BLACKHOLE-сервера, `status: running`, `blackholeStatus: CONNECTED`

Поля запроса (body)

Поле	Тип	Обяз.	Описание
`port`	number	да	`0` (автоопределение) или `1024–65535`. Порты 1–1023 отклоняются с `PORT_RESTRICTED`

Примеры

curl — личный ключ

Terminal

# Установить порт 8080
curl -X PATCH https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/port \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port": 8080}'

# Автоматическое определение
curl -X PATCH https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/port \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port": 0}'

curl — OAuth-приложение

Terminal

curl -X PATCH https://vibecode.bitrix24.tech/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 — личный ключ

javascript

const res = await fetch(
  `https://vibecode.bitrix24.tech/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(`Порт приложения: ${data.port}`)

JavaScript — OAuth-приложение

javascript

await fetch(
  `https://vibecode.bitrix24.tech/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 }),
  }
)

Поля ответа

Поле	Тип	Описание
`success`	boolean	Всегда `true` при успехе
`data.port`	number	Итоговый порт. При `port: 0` вернётся `3000` (значение по умолчанию при автоопределении)
`data.mode`	string	`manual` (задан конкретный порт) или `auto` (`port: 0`)
`data.verified`	boolean	`true` — платформа подтвердила, что агент проксирует на этот порт (опросом агента, а у закреплённого сервера — чтением настроек на машине плюс опросом после перезапуска). `false` — порт сохранён, но маршрутизация ещё не подтверждена (см. `data.warning` и раздел «Известные особенности»)
`data.warning`	string	Присутствует только при `verified: false`. Три состояния с разными действиями: агент остался в режиме автоопределения (закрепление не применилось — работает сканер), агент порт принял, а подтверждение не пришло (повторите запрос), либо порт записан в настройки закреплённого сервера, но агент ещё не подтвердил перезапуск. В первых двух случаях `/repair` не помогает и вредит, в третьем — наоборот, применит сохранённый порт. Текст предупреждения говорит, что делать
`data.pinned`	boolean	Закреплён ли порт в настройках агента на машине. `true` — переживёт пробуждение и ремонт, `false` — живёт только в памяти агента до ближайшего перезапуска

Пример ответа

JSON

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

Пример ответа при ошибке

409 — агент отклонил смену порта: