Download file

GET

/files/{id}

• Nhost Storage API Server

Retrieve and download the complete file content. Supports conditional requests, image transformations, and range requests for partial downloads.

Authorizations

• Authorization

Parameters

Path Parameters

id

required

string

Unique identifier of the file to download

Header Parameters

if-match

string

Only return the file if the current ETag matches one of the values provided

if-none-match

string

Only return the file if the current ETag does not match any of the values provided

if-modified-since

Date in RFC 2822 format

string

/^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{1,2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} \w+$/

Example

Tue, 12 Aug 2025 12:03:50 GMT

Only return the file if it has been modified after the given date

if-unmodified-since

Date in RFC 2822 format

string

/^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{1,2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} \w+$/

Example

Tue, 12 Aug 2025 12:03:50 GMT

Only return the file if it has not been modified after the given date

Range

string

/^bytes=(\d+-\d*|\d*-\d+)(,(\d+-\d*|\d*-\d+))*$/

Range of bytes to retrieve from the file. Format: bytes=start-end

Query Parameters

q

integer

>= 1 <= 100

Image quality (1-100). Only applies to JPEG, WebP, PNG and HEIC files

h

integer

>= 1

Maximum height to resize image to while maintaining aspect ratio. Only applies to image files

w

integer

>= 1

Maximum width to resize image to while maintaining aspect ratio. Only applies to image files

b

number

Blur the image using this sigma value. Only applies to image files

f

Output format for image files. Use ‘auto’ for content negotiation based on Accept header

string

default: same

Allowed values: auto same jpeg webp png avif heic

Example

same

Output format for image files. Use ‘auto’ for content negotiation based on Accept header

Responses

200

File content retrieved successfully

Headers

Cache-Control

string

Directives for caching mechanisms

Etag

string

Entity tag for cache validation

Content-Disposition

string

Indicates if the content should be displayed inline or as an attachment

Last-Modified

Date in RFC 2822 format

string

/^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{1,2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} \w+$/

Example

Tue, 12 Aug 2025 12:03:50 GMT

Date and time the file was last modified

Surrogate-Key

string

Cache key for surrogate caching

Surrogate-Control

string

Cache control directives for surrogate caching

Accept-Ranges

string

Always set to bytes. https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Ranges

206

Partial file content retrieved successfully

Headers

Cache-Control

string

Directives for caching mechanisms

Content-Range

string

Range of bytes returned in the response

Etag

string

Entity tag for cache validation

Content-Disposition

string

Indicates if the content should be displayed inline or as an attachment

Last-Modified

Date in RFC 2822 format

string

/^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{1,2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} \w+$/

Example

Tue, 12 Aug 2025 12:03:50 GMT

Date and time the file was last modified

Surrogate-Key

string

Cache key for surrogate caching

Surrogate-Control

string

Cache control directives for surrogate caching

304

File not modified since the condition specified in If-Modified-Since or If-None-Match headers

Headers

Cache-Control

string

Directives for caching mechanisms

Etag

string

Entity tag for cache validation

Surrogate-Control

string

Cache control directives for surrogate caching

412

Precondition failed for conditional request headers (If-Match, If-Unmodified-Since, If-None-Match)

Headers

Cache-Control

string

Directives for caching mechanisms

Etag

string

Entity tag for cache validation

Surrogate-Control

string

Cache control directives for surrogate caching

default

Error occurred

Headers

X-Error

string

Error message details