Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

List directory or download file

Section titled “List directory or download file”

The unversioned reader at /{path} returns directory listings in HTML by default, JSON when ?json is set, plain text when ?simple is set, or downloads the file as binary content. For files, append ?download to force Content-Disposition: attachment. Revision history (?history), point-in-time reads (?at, ?revision), and unified diffs (?diff) are all supported and are mutually exclusive on a single request.

GET /{path}

Section titled “GET /{path}”

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesFile or directory path
jsonquerystringNoReturn JSON format instead of HTML
simplequerystringNoReturn simple text listing
sortquerystringNoSort by field. One of: name, mtime, size
orderquerystringNoSort order. One of: asc, desc
hashquerystringNoGet SHA256 hash of file (returns plain text hash)
sha256querystringNoGet SHA256 hash of file (alias for hash)
base64querystringNoGet file content as base64 encoded string
editquerystringNoOpen file in Web UI editor (requires allow-upload permission)
viewquerystringNoView file in Web UI (read-only mode)
downloadquerystringNoFor file paths only: force browser download (Content-Disposition: attachment). Accepted values: empty (?download), 1, or true. For directory paths, ?download is the URL download-manager operation. One of: “, 1, true
content-typequerystringNoOverride Content-Type header for file downloads
historyquerystringNoList all revisions of a file. Returns JSON with revisions array, pagination via after_id. Mutually exclusive with at/revision/diff
atquerystringNoRead file content at a point in time. Accepts RFC3339 timestamp or Unix milliseconds. Mutually exclusive with history/revision/diff. Composable with ?lines, ?hash, ?base64
revisionqueryintegerNoRead file content by stable per-path sequence number. Mutually exclusive with history/at/diff. Composable with ?lines, ?hash, ?base64
diffquerystringNoCompute 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_seqqueryintegerNoSource revision seq number for ?diff. Mutually exclusive with from_ts
from_tsquerystringNoSource timestamp for ?diff (RFC3339 or Unix ms). Mutually exclusive with from_seq
to_seqqueryintegerNoTarget revision seq number for ?diff. Mutually exclusive with to_ts. Default: current file on disk
to_tsquerystringNoTarget timestamp for ?diff (RFC3339 or Unix ms). Mutually exclusive with to_seq
after_idqueryintegerNoCursor for ?history pagination. Returns entries with id > after_id
limitqueryintegerNoMax entries to return for ?history. Default: 100

Request Body

Section titled “Request Body”

This endpoint does not accept a request body.

Response

Section titled “Response”

Returns a directory listing in JSON, HTML, or simple text format, raw binary file content (application/octet-stream) for file paths, or revision history / historical content / unified diff when the corresponding query flags are used.

{
  "allow_archive": true,
  "allow_delete": false,
  "allow_search": true,
  "allow_upload": true,
  "auth": true,
  "dir_exists": true,
  "href": "/projects/abc/containers/xyz-1/",
  "kind": "Index",
  "paths": [
    {
      "mtime": 1714579200000,
      "name": "README.md",
      "path_type": "File",
      "revisions": 12,
      "size": 4096
    },
    {
      "mtime": 1714665600000,
      "name": "src",
      "path_type": "Dir",
      "revisions": null,
      "size": 14
    }
  ],
  "uri_prefix": "/",
  "user": "dev@example.com"
}

SDK and cURL

Section titled “SDK and cURL”
Terminal window
# Default HTML directory listing
curl "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.icu/projects/abc/containers/xyz-1/"


# JSON directory listing
curl "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.icu/projects/abc/containers/xyz-1/?json="


# Simple plain text listing
curl "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.icu/projects/abc/containers/xyz-1/?simple="


# Force a file download
curl "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.icu/projects/abc/containers/xyz-1/README.md?download"


# SHA256 hash of a file
curl "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.icu/projects/abc/containers/xyz-1/README.md?hash="


# File content as base64
curl "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.icu/projects/abc/containers/xyz-1/README.md?base64="


# Revision history with pagination
curl "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.icu/projects/abc/containers/xyz-1/README.md?history=&limit=50&after_id=1000"


# Historical content at a specific timestamp
curl "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.icu/projects/abc/containers/xyz-1/README.md?at=2024-05-01T12:00:00Z"


# Unified diff between two revisions
curl -G "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.icu/projects/abc/containers/xyz-1/README.md" \
  --data-urlencode "diff=" \
  --data-urlencode "from_seq=5" \
  --data-urlencode "to_seq=12"

List directory or download file (v1)

Section titled “List directory or download file (v1)”

GET /api/v1/files/{path}

Section titled “GET /api/v1/files/{path}”

V1 variant of the directory/file reader. Returns directory listings, file content, grep matches, glob results, line-range slices, revision history, and unified diffs. Supports an optional backend query parameter for remote file backends, and ?zip for streaming a directory as a zip archive. Depending on the query flags used, the response may be application/json, application/octet-stream (binary file content), or application/zip (a streamed directory archive).

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesFile or directory path
backendquerystringNoBackend ID for remote file access
hashquerystringNoGet SHA256 hash of file
sha256querystringNoGet SHA256 hash of file (alias for hash)
base64querystringNoGet file content as base64
previewquerystringNoPreview archive contents (for zip/tar files). Alias: ?contents
contentsquerystringNoAlias for ?preview - list archive contents
statquerystringNoGet file/directory metadata (stat) without downloading content
thumbnailquerystringNoReturn a processed image (resize, format convert, blur, grayscale). Requires the service to be started with --allow-thumbnails; returns 403 when disabled
grepquerystringNoSearch file/directory contents for regex pattern (or literal if fixed_string=true). Requires --allow-grep
ignore_casequerybooleanNoCase-insensitive grep matching. Default: false
fixed_stringquerybooleanNoTreat grep pattern as literal string, not regex. Default: false
globquerystringNoFind files matching glob pattern (e.g. **/*.rs, src/**/*.{ts,tsx}). Requires --allow-search. Directory paths only
contextqueryintegerNoNumber of context lines before/after each grep match. Default: 0
max_countqueryintegerNoMax matches per file for grep. Default: 50
max_matchesqueryintegerNoTotal max matches across all files for grep. Default: 500
max_depthqueryintegerNoDirectory recursion depth for grep. Default: 50
max_filesizequeryintegerNoSkip files larger than this (bytes) during grep. Default: 10485760
timeoutqueryintegerNoGrep timeout in seconds. Default: 30
no_ignorequerybooleanNoBypass .gitignore filtering during grep. Default: false
max_resultsqueryintegerNoMax entries returned for glob search. Default: 1000
max_files_scannedqueryintegerNoMax filesystem entries scanned during glob search. Default: 100000
sortquerystringNoSort glob results by: mtime (default), name, or size. One of: mtime, name, size
orderquerystringNoSort order for glob results. Default: desc for mtime, asc for name/size. One of: asc, desc
linesquerystringNoExtract specific lines from a file. Formats: 10-50 (range, 1-indexed inclusive), 100 (single line), -20 (last 20 lines / tail), 50- (line 50 to end). Returns text/plain with X-Line-Range header. X-Total-Lines header included when naturally known (scan reached EOF). Max 100,000 lines or 64MB per request
historyquerystringNoList all revisions of a file. Returns JSON with revisions array, pagination via after_id. Mutually exclusive with at/revision/diff
atquerystringNoRead file content at a point in time. Accepts RFC3339 timestamp or Unix milliseconds. Mutually exclusive with history/revision/diff. Composable with ?lines, ?hash, ?base64
revisionqueryintegerNoRead file content by stable per-path sequence number. Mutually exclusive with history/at/diff. Composable with ?lines, ?hash, ?base64
diffquerystringNoCompute 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_seqqueryintegerNoSource revision seq number for ?diff. Mutually exclusive with from_ts
from_tsquerystringNoSource timestamp for ?diff (RFC3339 or Unix ms). Mutually exclusive with from_seq
to_seqqueryintegerNoTarget revision seq number for ?diff. Mutually exclusive with to_ts. Default: current file on disk
to_tsquerystringNoTarget timestamp for ?diff (RFC3339 or Unix ms). Mutually exclusive with to_seq
after_idqueryintegerNoCursor for ?history pagination. Returns entries with id > after_id
limitqueryintegerNoMax entries to return for ?history. Default: 100
zipquerystringNoDownload a directory as a streaming zip archive (bare flag, e.g. ?zip). Local directories only; requires --allow-archive. Same behavior as the WebDAV-style /{directory}?zip

Request Body

Section titled “Request Body”

This endpoint does not accept a request body.

Response

Section titled “Response”

Returns a DirectoryListing, GrepResults, or GlobResults JSON object when the request is for listings/searches, raw binary (application/octet-stream) when downloading file content, or application/zip when streaming a directory via ?zip.

{
  "allow_archive": true,
  "allow_delete": false,
  "allow_search": true,
  "allow_upload": true,
  "auth": true,
  "dir_exists": true,
  "href": "/api/v1/files/projects/abc/containers/xyz-1/",
  "kind": "Index",
  "paths": [
    {
      "mtime": 1714579200000,
      "name": "README.md",
      "path_type": "File",
      "revisions": 12,
      "size": 4096
    },
    {
      "mtime": 1714665600000,
      "name": "src",
      "path_type": "Dir",
      "revisions": null,
      "size": 14
    }
  ],
  "uri_prefix": "/api/v1/files",
  "user": "dev@example.com"
}

SDK and cURL

Section titled “SDK and cURL”
Terminal window
# JSON directory listing
curl "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.icu/api/v1/files/projects/abc/containers/xyz-1/"


# File metadata (stat) only
curl "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.icu/api/v1/files/projects/abc/containers/xyz-1/README.md?stat="


# Grep search across a directory
curl -G "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.icu/api/v1/files/projects/abc/containers/xyz-1/src/" \
  --data-urlencode "grep=TODO" \
  --data-urlencode "ignore_case=true" \
  --data-urlencode "max_count=10"