Check file information

HEAD

/files/{id}

• Nhost Storage API Server

Retrieve file metadata headers without downloading the file content. Supports conditional requests and provides caching information.

Authorizations

• Authorization

Parameters

Path Parameters

id

required

string

Unique identifier of the file to check

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

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 information headers retrieved successfully

Headers

Cache-Control

string

Directives for caching mechanisms

Content-Length

integer

Size of the file in bytes

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

Accept-Ranges

string

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

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)

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