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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The asset’s id.
Header Parameters
Section titled “Header Parameters ”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.
Responses
Section titled “ Responses ”The whole file. A HEAD request gets the same headers and no body.
The requested range, with Content-Range giving its position and the file’s full size.
Authentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Resource not found
object
Human-readable error summary
Example
the request could not be completed