Uploads

Some endpoints in the Build API let you upload a file to VU.CITY - for example, syncing an external file's contents to VU.CITY Drive. None of these endpoints accept the file's bytes directly. Instead, they all follow the same two-step pattern:

1. Call the endpoint as normal. Instead of the file, it returns an upload URL.
2. Upload your file's bytes directly to that URL, in a separate request.

This page explains that second step, which is the same for every upload endpoint in the API. For what a specific endpoint returns and any limits it applies (upload URL expiry, maximum file size), see that endpoint's own page in the API reference.

Why a separate upload step?

The upload URL points directly at the storage that will hold your file, rather than at the Build API itself. Your file's bytes go straight there instead of passing through the API.

The upload URL is what's usually called a signed URL (or "presigned URL"): a normal-looking URL with a long, random-looking query string attached. That query string is your permission to upload - it's cryptographically signed, and it only works for a short time (typically an hour; check the specific endpoint's docs for the exact figure). You don't need any of your usual API credentials to use it.

Uploading your file

Send an HTTP PUT request to the upload URL, with your file's raw bytes as the entire request body - not wrapped in JSON, and not sent as an HTML form (multipart/form-data).

With curl:

curl -X PUT "$UPLOAD_URL" --data-binary @/path/to/your/file

--data-binary sends the file exactly as-is. Don't substitute -d/--data for a binary file (an image, a zip, anything that isn't plain text) - it can alter line endings and corrupt the upload.

In JavaScript, using fetch:

await fetch(uploadUrl, {
  method: 'PUT',
  body: fileContents, // e.g. a Blob, a File, or a Buffer
})

A successful upload responds with a 2xx status code and an empty body. There's nothing else to check: once that request succeeds, VU.CITY has the file.

Things that trip people up

• Using POST instead of PUT. The upload URL only accepts PUT.
• Sending JSON or form data. The request body must be the raw file - nothing wrapping it.
• Waiting too long. Upload URLs expire (see the issuing endpoint's docs for how long). If yours expires before you upload, call the endpoint again for a fresh one.
• Reusing an upload URL for a different file, or a second time. Request a new upload URL for each file you upload.