ElaraShrink API Reference v2.0 · 2026-06-24

Python client: pip install elara-benchmark==1.2.0 — pypi.org/project/elara-benchmark
Source & benchmarks: elara-codec-bench, elara-codec-profile, elara-cert-report

Endpoint Policy

Endpoint	Status	Compression	Use
`/v1/elara_compress_stream`	PRIMARY	BEST — ratio 104.5 on logs	All production code. Try page. Python client.
`/v1/elara_pack`	DEPRECATED	~10% worse — ratio 95.1	Legacy only. Will be fixed to use same codec.
`/v1/elara_unpack`	STABLE	Decompress .elz2 → original	Round-trip verification. SHA-256 identity.

1. Compress — `/v1/elara_compress_stream`

POST /v1/elara_compress_stream
Content-Type: multipart/form-data
Body: file=<binary>

Returns NDJSON stream. Each line is a JSON object:

{"ev":"start",  "name":"sample.log", "raw":21432668}
{"ev":"codec",  "name":"gzip",  "bytes":402819, "pct":98}
{"ev":"codec",  "name":"zstd",  "bytes":225373, "pct":99}
{"ev":"codec",  "name":"lzma",  "bytes":205020, "pct":99}
{"ev":"codec",  "name":"brotli","bytes":206220, "pct":99}
{"ev":"elara",  "bytes":205065, "pct":99, "ratio":104.5, "vs_gzip":49,
               "verified":true, "name":"sample.log.elz2", "b64":"RUZaMk..."}
{"ev":"done"}

Event	Fields	Meaning
`start`	`name`, `raw`	File received
`codec`	`name`, `bytes`, `pct`	One competitive result
`elara`	`b64`, `bytes`, `ratio`, `vs_gzip`	The elz2 result. `b64` = base64 .elz2 file
`done`	—	Stream complete

Python Example

from elara_shrink_client import elara_compress

with open("myfile.log", "rb") as f:
    result = elara_compress(f.read(), filename="myfile.log")
# result = {"bytes": <compressed>, "size": 205065, "ratio": 104.52, "sha256": "..."}
with open("myfile.log.elz2", "wb") as f:
    f.write(result["bytes"])

2. Compress (Legacy) — `/v1/elara_pack`

DEPRECATED Produces ~10% worse compression. Use /v1/elara_compress_stream instead.

POST /v1/elara_pack
Content-Type: multipart/form-data
Body: file=<binary>

Response: application/octet-stream — the .elz2 binary directly

3. Decompress — `/v1/elara_unpack`

POST /v1/elara_unpack
Content-Type: multipart/form-data
Body: file=<binary .elz2>

→ 200 OK, application/octet-stream — original file, byte-for-byte identical

Response Headers (all endpoints)

Header	Value
`X-Elara-Raw`	Original byte count
`X-Elara-Packed`	Compressed byte count
`X-Elara-Pct`	Space saved (99 = 99% smaller)
`X-Elara-Verified`	`1` if SHA-256 round-trip verified
`X-Elara-Manifest`	Base64 JSON with per-file + blended sizes

Certified Performance

Metric	Value	Evidence
elz2 ratio (stream)	1:104.5	20.4 MB log sample
vs brotli -11	elz2 wins (+0.6%)	205 KB vs 206 KB
vs zstd -19	elz2 wins (+8.8%)	205 KB vs 223 KB
Round-trip	SHA-256 verified ✅	Identity confirmed
Concurrency	4 req → 41s, 100% success	Zero errors

Full audit report: PyPI · elara-benchmark v1.2.0

The .LEKOLA compression codec