File Hashing

Hoody provides file hashing for integrity checking. Every file retrieved from the Files API can be hashed on the fly by appending a query parameter to the standard GET /api/v1/files/{path} request. The response body is a plain-text SHA256 hex digest that you can compare against a known-good value to verify that a file has not been corrupted or tampered with.

This page explains how to compute and verify file hashes using the Files API.

Supported Algorithm

The Files API supports exactly one hash algorithm: SHA256.

Any other algorithm (MD5, SHA-1, SHA-512, etc.) is intentionally not supported. If you need a hash in a different algorithm, compute the SHA256 digest returned by the API and then re-hash it locally with your preferred algorithm.

How Hashing Works

Hashing is not a separate endpoint. It is a query-parameter mode on the standard file retrieval endpoint:

GET /api/v1/files/{path}?hash=true

or, equivalently:

GET /api/v1/files/{path}?sha256=true

When either parameter is supplied, the server does not return the file’s binary contents. Instead, it streams a single plain-text line containing the SHA256 hex digest of the file. This means you can hash files of arbitrary size without downloading them in full.

Note

The two parameters are aliases of each other. hash and sha256 produce identical output. Use whichever reads more clearly in your code.

Query Parameters

The hashing behavior is controlled by the following query parameters on GET /api/v1/files/{path}.

Name	In	Type	Required	Description
hash	query	boolean	No	Get SHA256 hash of file (returns plain text hash).
sha256	query	boolean	No	Get SHA256 hash of file (alias for hash).

Only one of these parameters should be supplied per request. If both are present, the server uses the first one it recognizes and ignores the other.

Response Format

The response body is a single line of plain text — not JSON — containing the lowercase SHA256 hex digest of the file. For example:

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

The response uses Content-Type: text/plain rather than application/json. The Content-Length header reflects the byte length of the hash string (64 bytes for a SHA256 hex digest), not the size of the underlying file.

Tip

You can verify a downloaded file without re-downloading it by hashing the local copy with sha256sum (Linux/macOS) or Get-FileHash -Algorithm SHA256 (PowerShell) and comparing the value to one returned by the API at an earlier point in time.

Example: Compute a Hash

Request:

curl -X GET "https://api.hoody.com/api/v1/files/reports/2025/q1/financials.pdf?hash=true" \
  -H "Authorization: Bearer <token>"

Response:

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

The same request with the alias parameter:

curl -X GET "https://api.hoody.com/api/v1/files/reports/2025/q1/financials.pdf?sha256=true" \
  -H "Authorization: Bearer <token>"

Example: Verify an Existing Hash

If you already have a known-good hash for a file, you can confirm the file on the server still matches by issuing the hashing request and comparing the returned value byte-for-byte:

EXPECTED="e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
ACTUAL=$(curl -s -X GET "https://api.hoody.com/api/v1/files/reports/2025/q1/financials.pdf?hash=true" \
  -H "Authorization: Bearer <token>")

if [ "$EXPECTED" = "$ACTUAL" ]; then
  echo "Hash matches: file is intact."
else
  echo "Hash mismatch: file has been modified."
fi

Caution

Hashing a file still requires read permission on the file. A hashing request will fail with the same error status codes as a regular file retrieval if the caller is not authorized to access the path.

Practical Notes

• Streaming-friendly: Because the digest is computed during streaming, the hash request completes as quickly as the file can be read. You do not need to download the full file to obtain its hash.
• Idempotent: Hashing is a read-only operation. It never modifies the file, never creates a new revision, and never affects audit logs beyond a normal read entry.
• Case sensitivity: The API returns lowercase hex characters. Normalize your comparison value to lowercase before comparing.
• Fixed length: A SHA256 hex digest is always exactly 64 characters. Any other length in the response indicates a truncated or malformed response and should be treated as an error.