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

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

Записывает файл на BLACKHOLE-сервер через агент туннеля. Два варианта источника: встроенное base64-содержимое в теле запроса (до 500 МБ) или URL, с которого агент скачает файл сам (до 500 МБ). Поддерживается автоматическая распаковка архивов 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 — Ошибки.

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

• Автоопределение формата архива при 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.
• Таймаут 10 минут на загрузку через url. Для 500 МБ должно уложиться. Если источник медленный — предзагрузите архив, положите на свой CDN.

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

• Полный деплой — за один запрос вместо цепочки upload + exec.
• Выполнить команду — после загрузки можно распаковать/установить вручную.
• Логи сервиса — проверить, что сервис применил новые файлы.