#Upload a file

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

Writes a file to a BLACKHOLE server through the tunnel agent. Two source options: inline base64 content in the request body (up to 500 MB), or a URL from which the agent downloads the file itself (up to 500 MB). Automatic unpacking of tar.gz / tar.bz2 / zip archives is supported — the format is detected by the file signature (magic bytes) or by the URL extension.

#Parameters

#Request fields (body)

You must pass exactly one of: content or url.

#Examples

#curl — personal key

# Uploading a file by URL with automatic unpacking
curl -X POST https://vibecode.bitrix24.com/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"
  }'

# Inline base64 content — a small file (package.json)
CONTENT=$(echo '{"name":"my-app","version":"1.0.0"}' | base64)
curl -X POST https://vibecode.bitrix24.com/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 application

curl -X POST https://vibecode.bitrix24.com/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 — personal key

// Uploading and unpacking an archive
const res = await fetch(
  `https://vibecode.bitrix24.com/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(`Wrote ${data.size} bytes at ${data.path}${data.extracted ? ', unpacked' : ''}`)

#JavaScript — OAuth application

// Inline base64 content — a small config
const content = Buffer.from('NODE_ENV=production\n').toString('base64')
await fetch(
  `https://vibecode.bitrix24.com/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',
    }),
  }
)

#Response fields

#Response example

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

#Error response example

403 — path forbidden for upload:

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

#Errors

Full list of common API errors — Errors.

#Known specifics

• Automatic archive format detection with extract: true. The agent detects the format by the file signature (magic bytes, the detectArchiveExt() function): it supports .tar.gz, .zip, .tar.bz2. The format does not need to be specified explicitly. For a URL — the agent also checks the extension.
• macOS archives are cleaned automatically. If the archive contains AppleDouble sidecars (._*) or .DS_Store, the agent removes them after unpacking — this prevents false positives from scanners like Tailwind v4 oxide. When creating an archive on macOS we recommend using COPYFILE_DISABLE=1 tar -czf ... so that the sidecars never end up in the archive.
• Windows PowerShell ZIP — works on agent ≥ 1.2.3. Compress-Archive on Windows writes a ZIP with literal \ in file names. Since version 1.2.3 the agent automatically normalizes these paths via the normalize_windows_paths step. For older agent versions use tar.gz (via WSL / Git Bash) or host a ready-made tar archive and upload it via url.
• List of forbidden paths. The agent blocks uploads to: /root/.ssh/ (protecting SSH keys), /boot, /etc/shadow, /etc/passwd, system service files. For the application use /opt/<app>/ or /var/lib/<app>/.
• mode is applied to the archive, not to the unpacked files. With extract: true the permissions of the unpacked files are determined by the archive's contents, and mode is set only on the saved archive. If you need to change permissions inside — do it via /exec with chmod.
• 10-minute timeout for uploading via url. That should be enough for 500 MB. If the source is slow, preload the archive and host it on your own CDN.

#See also

• Full deploy — in a single request instead of the upload + exec chain.
• Run a command — after the upload you can unpack/install manually.
• Service logs — check that the service picked up the new files.