Archive and File Transfer

Use archive upload when you need to sync many files at once. Use the single-file route when you need a small, precise write.

Archive upload routes:

POST /api/containers/<container_id>/archive
POST /api/volumes/<name>/archive

Archive request shape:

Content-Type: application/gzip or application/x-tar
Query: ?path=/app&strip_components=1
Body: raw tar or tar.gz bytes

Single-file volume write:

POST /api/volumes/<name>/files

Payload:

{
  "path": "/remote.txt",
  "content": "<base64>",
  "mode": 644
}

Notes

• archive uploads are operation-driven
• single-file volume reads and writes are synchronous
• volume file download returns raw bytes, not a JSON base64 envelope
• volume file listing supports page and page_size
• mode is an octal permission encoded as an integer like 644 or 755

Rule of Thumb

Archive upload is the normal shape for syncing a codebase or bundle into a target filesystem.