API / v1 · stable

API reference

One endpoint to draw random numbers from code: key in the header, JSON responses, no SDK. Draws use the operating system CSPRNG, not a seeded generator.

BASE URL https://pseudocodice.it/random/api/v1

Authentication

Every /api/v1 request carries the key in the X-API-Key header. For quick tests it also accepts a key query parameter, discouraged in production because it ends up in logs. Keys are rnd_ followed by 40 hex characters and are revoked server-side without downtime.

curl -s -H "X-API-Key: rnd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://pseudocodice.it/random/api/v1/random?min=1&max=6&n=2"

Endpoint

GET /random Uniform integers

Draws n integers from the closed range [min, max]. Every value is independent and uniform: no modulo bias, because the draw uses rejection sampling over PHP random_int(), which reads the OS entropy pool.

PARAM	TIPO	DEFAULT	DESCRIPTION
min	int	1	Inclusive lower bound. Negatives allowed.
max	int	100	Inclusive upper bound. If min > max they are reordered.
n	int	1	How many values to return, 1 to 100 per request.
unique	0 \| 1	0	With 1 the draw is without replacement: no repeated values in the response.
key	string	—	Alternative to the header, for quick tests. Do not use in production.

REQUEST

curl -s -H "X-API-Key: rnd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://pseudocodice.it/random/api/v1/random?min=1&max=90&n=6&unique=1"

200 OK

{
  "ok": true,
  "values": [7, 23, 41, 58, 69, 82],
  "range": [1, 90],
  "bits": 38,
  "quota": { "limit": 10000, "remaining": 9994 },
  "source": "php-random_int (CSPRNG)"
}

values is always an array, even with n=1. bits is the entropy of the whole response: log2(range) × n. On forever plans quota.remaining is null and quota.unlimited is true.

Errors

STATUS	CODE	MEANING
401	invalid_key	Missing, malformed or revoked key.
400	bad_range	min and max do not define a valid range.
400	range_too_small	More unique values requested than the range contains.
429	quota_exceeded	Monthly quota exhausted; the body reports quota.limit.
503	stripe_disabled	Checkout not configured (only /api/checkout).
404	not_found	Unknown endpoint.

Examples

JavaScript

const res = await fetch(
  "https://pseudocodice.it/random/api/v1/random?min=1&max=100&n=5&unique=1",
  { headers: { "X-API-Key": process.env.RANDOM_KEY } }
);
const data = await res.json();
if (!data.ok) throw new Error(data.error);
console.log(data.values); // [17, 4, 88, 42, 63]

PHP

$ch = curl_init('https://pseudocodice.it/random/api/v1/random?min=1&max=100&n=5');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-Key: ' . getenv('RANDOM_KEY')],
    CURLOPT_TIMEOUT        => 10,
]);
$data = json_decode((string) curl_exec($ch), true);
print_r($data['values'] ?? []);

Python

import os, requests

r = requests.get(
    "https://pseudocodice.it/random/api/v1/random",
    params={"min": 1, "max": 100, "n": 5, "unique": 1},
    headers={"X-API-Key": os.environ["RANDOM_KEY"]},
    timeout=10,
)
print(r.json()["values"])

Quota and limits

Paid plans: 10,000 draws per month, counter reset on the first of the month. Forever plans: unlimited, the counter is kept for statistics only. n is capped at 100 per request: split larger batches. There is no rate limit on the keyed API; telemetry endpoints allow 120 requests per hour per IP.

Getting a key

The key comes with a Pro licence, issued after payment. On another device you restore it by pasting the licence key on the Pro page. There is no sign-up: the licence is the credential, and it is revoked server-side.

See plans

Internal endpoints

Used by the site itself. Not meant for public use: they can change without notice and some only accept same-origin requests.

POST	/api/hit	Browser draw telemetry: {tool, n, bits}. Rate limited per IP.
GET	/api/stats	Aggregate totals: generations, bits, tools.
POST	/api/checkout	Creates a Stripe Checkout Session: {plan, lang} → {url}.
POST	/api/stripe/webhook	Stripe events with HMAC signature verification, 5 minute tolerance.

The API does not store returned values: the server generates the response and forgets it, exactly like the in-browser tools. Version v1: no breaking changes planned, fields are added, not removed.