File Metadata

Metadata

Retrieve file metadata using HEAD requests against a container’s file root. The endpoint returns HTTP headers by default, and supports query parameters to switch the response into a JSON body describing file revisions, a point-in-time view, or a diff between versions.

Get file metadata

HEAD /{path}

Returns metadata for a file at the given path. Pass a query parameter such as history, at, revision, or diff to receive a JSON body describing the selected view; otherwise the response carries metadata in HTTP headers.

Parameters

Name	In	Type	Required	Description
path	path	string	Yes	URL-encoded file path relative to the container file root.
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

{
  "description": "File exists"
}

404

{
  "description": "File not found"
}

Examples

Default metadata fetch (path only):

cURL

curl -I 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/docs%2Freadme.md' \
  -H "Authorization: Bearer <token>"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.files.getMetadata('docs/readme.md');

Listing revisions via the history query option:

cURL

curl -I 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/docs%2Freadme.md?history=' \
  -H "Authorization: Bearer <token>"

TypeScript SDK

await client.files.files.getMetadata('docs/readme.md', { history: '' });

Computing a diff between a past revision and the current file:

cURL

curl -I 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/docs%2Freadme.md?diff=&from_seq=12' \
  -H "Authorization: Bearer <token>"

TypeScript SDK

await client.files.files.getMetadata('docs/readme.md', { diff: '', from_seq: 12 });