HTTP API endpoints

GET /raw

Returns a binary buffer of random bytes from the central entropy pool. The default size is 64 KB, with an optional `bytes` parameter from 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 an open HTTP socket. Designed 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` binary file with a `Content-Disposition: attachment` header for convenient browser or scripted downloads.

GET /healthz

Returns operational node status as JSON: available byte pool, SDR receiver 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

To protect the infrastructure from entropy pool exhaustion, Nginx enforces request rate limiting. Standard endpoints allow 10 req/s, while heavier /raw downloads are limited to 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.