Skip to main content

​
Tag-based version lookup rules

  • You can manage multiple versions for one filename using an optional tag.
  • Example:
    • Items.json (no tag)
    • Items.json (tag = v1)
    • Items.json (tag = v2)
Lookup behavior:
  • If tag is provided, it resolves an exact filename(key) + tag match.
  • If tag is omitted, it resolves the untagged object first.
  • If no untagged object exists, it resolves the most recently updated tagged object for that filename.

​
Get file metadata

import requests

BASE_URL = "https://core.hyperx.dev"
PROJECT_CODE = "your-project-code"

resp = requests.get(
    f"{BASE_URL}/v1/storage/lookup",
    params={
        "key": "images/logo.png",
        # "tag": "v2",  # Use when requesting a specific version
    },
    headers={"x-project-code": PROJECT_CODE},
    timeout=10,
)
resp.raise_for_status()

meta = resp.json()
print("hash:", meta["hash"])
print("type:", meta["type"])
print("size:", meta["size"])
print("updatedAt(ms):", meta["updatedAt"])

​
Get file hash

/v1/storage/hash returns 8-byte little-endian binary data. 
import requests

BASE_URL = "https://core.hyperx.dev"
PROJECT_CODE = "your-project-code"

resp = requests.get(
    f"{BASE_URL}/v1/storage/hash",
    params={"key": "images/logo.png"},
    headers={"x-project-code": PROJECT_CODE},
    timeout=10,
)
resp.raise_for_status()

hash_bytes = resp.content  # exactly 8 bytes
hash_value = int.from_bytes(hash_bytes, byteorder="little", signed=False)
hash_hex = format(hash_value, "x")

print("hash bytes length:", len(hash_bytes))
print("hash (hex):", hash_hex)

​
Download file

First generate a temporary URL via /v1/storage/download-url, then download the actual file with that URL. 
import requests

BASE_URL = "https://core.hyperx.dev"
PROJECT_CODE = "your-project-code"

# 1) Generate pre-signed download URL
url_resp = requests.get(
    f"{BASE_URL}/v1/storage/download-url",
    params={
        "filename": "images/logo.png",
        # "tag": "v2",
    },
    headers={"x-project-code": PROJECT_CODE},
    timeout=10,
)
url_resp.raise_for_status()

download_url = url_resp.json()["url"]
print("download_url:", download_url)

# 2) Download actual file
file_resp = requests.get(download_url, timeout=30)
file_resp.raise_for_status()

with open("logo.png", "wb") as f:
    f.write(file_resp.content)

print("saved:", "logo.png", "bytes=", len(file_resp.content))

​
Error response

On errors, the API returns JSON in this format. 
{
  "error": "storage object not found"
}