Загрузить файл

POST /v1/infra/servers/:id/upload

Записывает файл на BLACKHOLE-сервер через агент туннеля. Два варианта источника: встроенное base64-содержимое в теле запроса — до 96 МБ тела, то есть около 72 МБ самого файла, — или URL, с которого агент скачает файл сам, до 500 МБ. На серверах, включённых в rollout надёжной URL-загрузки, агент выполняет до четырёх попыток с backoff в общем бюджете пяти минут. До включения сохраняется прежнее поведение URL-загрузки. Поддерживается автоматическая распаковка архивов tar.gz / tar.bz2 / zip — формат определяется по сигнатуре файла (magic bytes) или по расширению URL.

Параметры

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

Нужно передать ровно одно из: content или url.

Примеры

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

# Загрузка файла по URL с автоматической распаковкой
curl -X POST https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/upload \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://github.com/user/repo/archive/main.tar.gz",
    "path": "/opt/app/source.tar.gz",
    "extract": true,
    "extractTo": "/opt/app"
  }'

# Встроенное base64-содержимое — маленький файл (package.json)
CONTENT=$(echo '{"name":"my-app","version":"1.0.0"}' | base64)
curl -X POST https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/upload \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"content\":\"$CONTENT\",\"path\":\"/opt/app/package.json\",\"mode\":\"0644\"}"

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

curl -X POST https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/upload \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/config.json","path":"/etc/myapp/config.json"}'

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

// Загрузка архива и распаковка
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/upload`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      url: 'https://github.com/user/app/archive/main.tar.gz',
      path: '/opt/app/source.tar.gz',
      extract: true,
      extractTo: '/opt/app',
    }),
  }
)
const { data } = await res.json()
console.log(`Записано ${data.size} байт по пути ${data.path}${data.extracted ? ', распаковано' : ''}`)

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

// Встроенное base64-содержимое — маленький конфиг
const content = Buffer.from('NODE_ENV=production\n').toString('base64')
await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/upload`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      content,
      path: '/opt/app/.env',
      mode: '0600',
    }),
  }
)

Поля ответа

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

{
  "success": true,
  "data": {
    "path": "/opt/app/source.tar.gz",
    "size": 1048576,
    "extracted": true
  }
}

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

403 — путь запрещён для загрузки:

{
  "success": false,
  "error": {
    "code": "UPLOAD_PATH_DENIED",
    "message": "Upload to system path is not allowed"
  }
}

Ошибки

Полный список общих ошибок API — Ошибки.

При включённом отказоустойчивом URL-режиме проверки запроса и пробуждение VM завершаются до открытия ответа и сохраняют HTTP-коды из таблицы. Перед долгой загрузкой платформа открывает HTTP 200 и поддерживает JSON-ответ keepalive-пробелами. Её конечный исход определяется по success и error.code в теле. Поэтому ошибки агента/Gateway из уже запущенной URL-загрузки приходят под HTTP 200, а не под 500/502/503. Для content, URL до включения режима и отказов до начала долгой фазы контракт HTTP-статусов не меняется.

Известные особенности

• Спящую отдельную виртуальную машину загрузка будит сама. Если сервер (kind: "STANDALONE") в статусе sleeping, платформа запускает пробуждение и ждёт его в том же запросе — до 6.5 минут, и только потом записывает файл. Отдельный вызов /wake не нужен, но клиентский таймаут запроса это время обязан пережить. Если сервер не поднялся, приходит 503 WAKE_TIMEOUT и сервер возвращается в sleeping — файл не записан, повторный запрос безопасен.
• Автоопределение формата архива при extract: true. Агент определяет формат по сигнатуре файла (magic bytes, функция detectArchiveExt()): поддерживает .tar.gz, .zip, .tar.bz2. Формат можно не указывать явно. Для URL — агент также проверяет расширение.
• macOS-архивы чистятся автоматически. Если архив содержит AppleDouble-сайдкары (._*) или .DS_Store, агент удаляет их после распаковки — это предотвращает ложные срабатывания сканеров вроде Tailwind v4 oxide. При создании архива на macOS советуем использовать COPYFILE_DISABLE=1 tar -czf ... чтобы сайдкары вообще не попадали в архив.
• Windows PowerShell ZIP — работает на агенте ≥ 1.2.3. Compress-Archive в Windows пишет ZIP с литеральными \ в именах файлов. Агент с версии 1.2.3 автоматически нормализует эти пути через шаг normalize_windows_paths. Для старых версий агента используйте tar.gz (через WSL / Git Bash) либо выкладывайте готовый tar-архив и загружайте через url.
• Список запрещённых путей. Агент блокирует загрузку в: /root/.ssh/ (защита SSH-ключей), /boot, /etc/shadow, /etc/passwd, системные сервис-файлы. Для приложения используйте /opt/<app>/ или /var/lib/<app>/.
• mode применяется к архиву, не к распакованным файлам. При extract: true права распакованных файлов определяются содержимым архива, а mode задаётся только сохранённому архиву. Если нужно изменить права внутри — сделайте через /exec c chmod.
• url скачивает сама клиентская VM, надёжный режим включается поэтапно. Этот маршрут намеренно не использует платформенный relay полного /deploy. На серверах в rollout агент выполняет до четырёх попыток с backoff в общем бюджете пяти минут: DNS/TCP/TLS/header/body-обрывы и временные HTTP-статусы повторяются, а постоянные URL-policy, HTTP, size, integrity и extraction-ошибки завершаются сразу. До включения сервер сохраняет прежний URL-контракт и таймаут. Путь в любом режиме зависит от egress/NAT этой VM. Для доставки исходников приложения, независимой от сети VM, используйте source.url полного деплоя. В надёжном режиме клиентский timeout должен выдерживать пробуждение сервера плюс пятиминутный бюджет.

Смотрите также

• Полный деплой
• Выполнить команду
• Логи сервиса