HTTP API endpoints

GET /raw

Returns binary random bytes from the central entropy pool. Default size is 64 KB; `bytes` can request 1 to 1,048,576 B.

curl -s "https://entropy.sparksome.pl/raw?bytes=32" | xxd -p

GET /raw/stream

Continuous binary random byte streaming over HTTP for services with high entropy demand.

curl -N -s "https://entropy.sparksome.pl/raw/stream?bytes=65536" > entropy_stream.bin

GET /download/entropy

Returns a `.bin` file with `Content-Disposition: attachment` for browser or scripted downloads.

GET /healthz

Returns JSON status: available pool, SDR state, rejection indicators, and response timings.

Integration examples

> Python (requests / urllib)

import requests

response = requests.get("https://entropy.sparksome.pl/raw", params={"bytes": 64})
if response.status_code == 200:
    random_bytes = response.content
    print("Pobrano bytes:", random_bytes.hex())

> JavaScript (Node.js fetch)

const res = await fetch("https://entropy.sparksome.pl/raw?bytes=32");
const buffer = await res.arrayBuffer();
const bytes = new Uint8Array(buffer);
console.log("Random Bytes:", bytes);

> Shell / cURL

# Fetch 16 random bytes as hex
curl -s "https://entropy.sparksome.pl/raw?bytes=16" | xxd -p

Limits and overload protection

Nginx rate limiting protects the entropy pool: standard endpoints allow 10 req/s, heavier /raw downloads 2-3 req/s per IP.

HTTP 429 Too Many Requests — w przypadku przekroczenia limitu odczekaj zadaną liczbę sekund podaną w nagłówku Retry-After.