Skip to content

Download an asset's original file

GET
/assets/{id}/file

Returns the asset’s original file, as uploaded, if you may see its content. HEAD returns the same headers without the body.

The check follows the asset’s sensitivity: its owner, system.admin and accounts with content.read.all get the file at any tier, members of its team get a team asset, and anyone gets a public one, including anonymous visitors when the instance allows anonymous browsing (otherwise a request with no session or token gets 401). A mature-rated file also needs a signed-in viewer who has opted in, on an instance that allows mature content, unless they’re the owner or system.admin; content.read.all doesn’t cover that. The asset’s status doesn’t matter: a draft or archived asset is served on the same terms. If you may not have the file, an ordinary request gets 404, the same as for an asset that doesn’t exist, was deleted or has no file.

To get part of the file, send one range in Range: bytes=start-end, bytes=start- or bytes=-count for the last bytes. You get 206 with Content-Range; an end past the end of the file is cut to it. Only the first range of a list is used, and If-Range isn’t supported. A range that starts at or past the end of the file, or a value that isn’t a byte range, gets 416 with Content-Range: bytes */size. HEAD ignores Range.

The Content-Type is the type the storage backend reports. When it reports none, or only application/octet-stream, some audio and video extensions get a type of their own instead, such as audio/mpeg for .mp3 or video/mp4 for .mp4; anything else is sent as application/octet-stream. A media type doesn’t mean a browser can play the file. No Content-Disposition is sent, so a browser may show the file instead of saving it.

Successful responses carry Accept-Ranges: bytes, an ETag and Cache-Control: public, max-age=60, must-revalidate, so browsers and shared caches may keep a copy for up to 60 seconds before checking again. Send the ETag back in If-None-Match and you get 304 with no body while it still matches; a match doesn’t prove the bytes are unchanged. A matching conditional request is answered before access is checked, so a 304 doesn’t confirm that you may still have the file.

Errors from this route are plain text, not the JSON shown below, except the 401: the 404 body is “404 page not found”, and an id that isn’t a UUID gets 400, a range that can’t be served 416, and a storage failure 500.

id
required
string format: uuid

The asset’s id.

Range
string

Optional. One byte range, such as bytes=0-1023, bytes=1024- or bytes=-1024 (the last 1024 bytes). A value that isn’t a byte range this file can serve gets 416.

The whole file. A HEAD request gets the same headers and no body.

string format: binary

The requested range, with Content-Range giving its position and the file’s full size.

string format: binary

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed