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 96 MB, which is about 72 MB of the file itself — or a URL from which the agent downloads the file on its own, up to 500 MB. On servers enrolled in the resilient URL-download rollout, the agent makes up to four attempts with backoff inside a shared five-minute budget; before enrollment, the existing URL-download behavior is preserved. 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 — the path is not allowed for upload:

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

Errors

For the full list of common API errors, see Errors.

When resilient URL mode is enabled, request validation and the blocking VM wake finish before the response opens and retain the HTTP statuses from the table. Before the long download, the platform opens HTTP 200 and keeps the JSON response alive with whitespace; determine the download's final outcome from success and error.code in the body. Agent/Gateway failures from an already started URL upload therefore arrive under HTTP 200 rather than 500/502/503. The HTTP-status contract is unchanged for content, URLs before enrollment, and failures before the long phase.

Known specifics

• A sleeping standalone virtual machine is woken by the upload itself. If the server (kind: "STANDALONE") is in sleeping status, the platform starts the wake and waits for it within the same request — up to 6.5 minutes — and only then writes the file. A separate /wake call is not needed, but the client's request timeout must be longer than that window. If the server does not come up, 503 WAKE_TIMEOUT arrives and the server returns to sleeping — the file was not written, so a repeat request is safe. A sleeping server with a live plan-change operation (resize) returns 409 EXEC_BUSY before waking; wait for that operation to finish.
• 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 your 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.
• The client VM itself downloads url; resilient mode is rolled out gradually. This route intentionally does not use the full /deploy platform relay. On enrolled servers, the agent makes up to four attempts with backoff inside a shared five-minute budget: DNS/TCP/TLS/header/body interruptions and transient HTTP statuses are retried, while permanent URL-policy, HTTP, size, integrity, and extraction errors end the download immediately. Before enrollment, the server keeps the existing URL contract and timeout. In either mode the path still depends on that VM's egress or NAT. To deploy application source without depending on VM networking, use full deploy with source.url. In resilient mode the client timeout must be longer than the server wake plus the five-minute budget.

See also

• Full deploy
• Run a command
• Service logs