Upload a file

Writes a file inside the guest. The request body is the file itself, raw — not multipart, not JSON — and the destination is the path query parameter.

One upload is at most 64 MiB. A larger one is a 413 — refused on its Content-Length before any bytes move when the length is declared, and stopped at the limit otherwise. There is no ranged or append upload on this endpoint. Use PUT /computers/{id}/files/uploads for resumable files up to 2 GiB on Linux.

By default an existing file at path is replaced. Send overwrite=false to create the file only if nothing is there: a path that is taken answers 409 with reason: "exists" and nothing is written. The body is written beside the destination first and published only once it is complete, so incomplete contents are never published at path. A failure while publishing, or while answering, can still leave the complete file there: after an error, inspect path before retrying or overwriting, since what is there may be your own upload. Linux computers only: overwrite=false on Windows is a 400. A computer whose host is too old to do a create-only upload answers 409 with reason: "unsupported" and nothing is sent; one whose host could not be asked answers 503, and the same request can be sent again, since nothing was sent. Neither of those means the path is free.

A computer suspended for being idle just as the upload arrived answers 409 with resume_required and reason: "contention": send the entire upload again, and it resumes the computer first.

Requires the member role or higher.