File Metadata

Use a HEAD request against any file path to retrieve its metadata without downloading the file body. The response headers describe the file’s size, content type, modification time, and ETag, while a successful empty body confirms that the file exists. This is the fastest way to check whether a file is present, compare ETags for caching, or inspect version-history and time-travel options before issuing a full read.

The endpoint lives at the WebDAV-style file root of the container, not under an /api/files/metadata/ prefix — every path you want to inspect is appended directly to the files service host.

`HEAD /{path}`

Returns headers describing the file at the given path. The body of a successful response is empty; metadata is conveyed entirely through response headers (for example Content-Length, Content-Type, ETag, Last-Modified).

The query parameters below enable version-history listing (history), point-in-time reads (at), stable-revision reads (revision), and unified diffs (diff). These are mutually exclusive — pick one mode per request.

Parameters

Name	In	Type	Required	Description
`path`	path	string	Yes	URL-encoded absolute path of the file (e.g. `docs/readme.md`)
`history`	query	string	No	List all revisions of a file. Pass an empty string. 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. Pass an empty string. 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.

// Plain existence check
const res = await client.files.files.getMetadata({ path: "docs/readme.md" });

// List revisions (use ?history)
await client.files.files.getMetadata({ path: "docs/readme.md", history: "" });

// Read at a point in time
await client.files.files.getMetadata({
  path: "docs/readme.md",
  at: "2025-01-15T10:30:00Z",
});

// Read by revision seq
await client.files.files.getMetadata({ path: "docs/readme.md", revision: 42 });

// Diff between two revisions
await client.files.files.getMetadata({
  path: "docs/readme.md",
  diff: "",
  from_seq: 40,
  to_seq: 42,
});

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

The method lives on the files service of the files namespace (client.files.files.getMetadata). The path is required and goes inside the trailing options object alongside any query parameters (history, at, revision, diff, from_seq, from_ts, to_seq, to_ts, after_id, limit).

# Existence check
curl -I -X HEAD \
  "https://acme-prod-cnt123-files-1.eu-west-1.containers.hoody.icu/docs/readme.md"

# List revisions
curl -I -X HEAD \
  "https://acme-prod-cnt123-files-1.eu-west-1.containers.hoody.icu/docs/readme.md?history=&limit=50"

# Diff between two revisions
curl -I -X HEAD \
  "https://acme-prod-cnt123-files-1.eu-west-1.containers.hoody.icu/docs/readme.md?diff=&from_seq=40&to_seq=42"

Responses

The file exists. The body is empty; inspect response headers for Content-Length, Content-Type, ETag, and Last-Modified.

{
  "description": "File exists"
}

The file does not exist at the given path.

{
  "description": "File not found"
}