The file metadata endpoint lets you check whether a file exists and retrieve its metadata headers using a lightweight HEAD request. Use it before downloading or transforming a file to verify availability without transferring the file body. This page documents the single HEAD /api/files/metadata/{path} operation.

Get file metadata

Returns metadata headers for a file at the specified path. Since this is a HEAD request, no response body is returned; the metadata is conveyed entirely through response headers. A 200 status indicates the file exists, while a 404 indicates it was not found.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	URL-encoded path to the file relative to the metadata root (e.g. folder/image.png)

Response

200

File exists at the requested path.

{
  "description": "File exists"
}

404

No file exists at the requested path.

{
  "description": "File not found"
}

SDK usage

const metadata = await client.files.getMetadata({
  path: "folder/image.png",
});