File Metadata

Retrieve metadata for a file using a HEAD request. This endpoint returns file existence and headers (such as Content-Length, Content-Type, Last-Modified, and ETag) without transferring the file body. Use this when you need to check whether a file exists, get its size, or inspect caching headers before deciding to download.

The endpoint is exposed under the WebDAV-style file root, so requests are made to HEAD /{path} where {path} is the URL-encoded file path within the workspace.

HEAD /{path}

Get file metadata.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	URL-encoded path to the file (e.g. docs/readme.md).
history	query	string	No	List all revisions of a file. Returns JSON with revisions array, pagination via after_id. Mutually exclusive with at / revision / diff.
at	query	string	No	Read file content at a point in time. Accepts RFC3339 timestamp or Unix milliseconds. Mutually exclusive with history / revision / diff. Composable with ?lines, ?hash, ?base64.
revision	query	integer	No	Read file content by stable per-path sequence number. Mutually exclusive with history / at / diff. Composable with ?lines, ?hash, ?base64.
diff	query	string	No	Compute unified diff between two versions. Requires from_seq or from_ts. Optional to_seq or to_ts (defaults to current file). Mutually exclusive with history / at / revision.
from_seq	query	integer	No	Source revision seq number for ?diff. Mutually exclusive with from_ts.
from_ts	query	string	No	Source timestamp for ?diff (RFC3339 or Unix ms). Mutually exclusive with from_seq.
to_seq	query	integer	No	Target revision seq number for ?diff. Mutually exclusive with to_ts. Default: current file on disk.
to_ts	query	string	No	Target timestamp for ?diff (RFC3339 or Unix ms). Mutually exclusive with to_seq.
after_id	query	integer	No	Cursor for ?history pagination. Returns entries with id > after_id.
limit	query	integer	No	Max entries to return for ?history. Default: 100.

This endpoint accepts no request body.

Responses

200

Returns 200 OK with headers describing the file when the file exists.

HTTP/1.1 200 OK
Content-Length: 2048
Content-Type: text/markdown
Last-Modified: Wed, 15 Jan 2025 09:12:34 GMT
ETag: "a1b2c3d4e5f6"
X-File-Path: docs/readme.md

{
  "description": "File exists"
}

404

Returns 404 Not Found when the file does not exist at the requested path.

HTTP/1.1 404 Not Found
Content-Length: 0

{
  "description": "File not found"
}

SDK Usage

const metadata = await client.files.files.getMetadata({
  path: "docs/readme.md",
});

Note

The getMetadata method lives on the files service of the files namespace, so the accessor is client.files.files.getMetadata(...). Do not collapse the namespace.

To retrieve revision history instead of just the current file metadata, pass the history query parameter:

const history = await client.files.files.getMetadata({
  path: "docs/readme.md",
  history: "",
  limit: 50,
});

To compute a diff between two revisions:

const diff = await client.files.files.getMetadata({
  path: "docs/readme.md",
  diff: "",
  from_seq: 12,
  to_seq: 18,
});