Documentation — conventions, parameters & formats

Requests

The basics

Everything is a GET request under https://randomapi.dev/api/…. No authentication, no API keys, CORS open to every origin. Pick an endpoint from the catalog, add query parameters, fetch.

terminal

curl "https://randomapi.dev/api/holidays/check?country=DK"

Responses

The response envelope

JSON responses wrap your records in data plus a meta block. meta.params echoes every resolved parameter — defaults filled in — so you can always see exactly what the API honored. Lists return data as an array; lookups and computed answers return a single object.

GET /api/users?count=1&seed=42&fields=fullName,email

{
  "data": [
    { "fullName": "Emily Carter", "email": "emily.carter@example.com" }
  ],
  "meta": {
    "endpoint": "users",
    "count": 1,
    "seed": 42,
    "params": { "minAge": 18, "maxAge": 80 },
    "generatedAt": "2026-06-11T21:00:00.000Z"
  }
}

Parameters

Universal parameters

These behave consistently wherever they apply. Each endpoint page lists its exact supported set.

count: How many records (list endpoints). Default 10, max 100. On reference lists it acts as a limit: most default to all matches, and the large datasets state their own default (each route's params table shows the real one).
seed: Deterministic output for mock endpoints: same seed ⇒ byte-identical data, and count=N always gives N distinct records. Omit for random — the seed used is echoed in meta.seed so you can reproduce any response.
locale: Data locale for people-ish generators: en (default), da, de, fr, es, it, pt, ja.
fields / exclude: Project the response: fields=fullName,email returns only those keys; exclude drops keys instead. Unknown names produce a warning, never an error.
format: json (default), ndjson (one record per line) or csv — on list endpoints.
pretty: Pretty-print the JSON.
unwrap: Drop the envelope and return the raw array/object.

Route-specific date parameters accept exact YYYY-MM-DD values or the API's millisecond timestamp profile: YYYY-MM-DDTHH:mm:ss[.SSS]Z (an explicit numeric offset is also allowed). A timezone is required, seconds are 00–59, and more than three fractional digits are rejected instead of truncated.

Reproducibility

Determinism & seeding

Mock endpoints accept seed (any integer). The same seed plus the same resolved parameters always produces the same records — across deploys and machines. Each record in a list gets its own derived stream, so count=10&seed=1 returns ten different records, stably.

Time-based endpoints such as /api/time and bare /api/holidays/check read the real clock by design. Mock routes whose omitted date window resolves from today echo that resolved window in meta.params; send those values back with the seed for an exact replay on another day.

Failure modes

Errors & warnings

Invalid input fails loudly, lookup misses stay honest, and typoed parameter names produce a useful suggestion.

400 — the message tells you the fix

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "'minAge' (50) must be ≤ 'maxAge' (20).",
    "status": 400
  }
}

typos get caught

{
  "data": [ "…" ],
  "meta": {
    "…": "…",
    "warnings": [
      "Unknown parameter 'contry' — did you mean 'country'? It was ignored."
    ]
  }
}

Output

Formats

json: The default data and meta envelope.
ndjson: One record per line for pipelines.
csv: Tabular output with nested dot-keys.

Formats apply to list endpoints. Add unwrap=true to drop the JSON envelope and return only the raw array or object.

Usage

Rate limits

Per IP, per minute: 60
Per IP, per day: 10,000

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 includes Retry-After. Batch up to 100 records with count when you need fewer requests.

Data provenance

Mock vs real data

MOCK DATA

Generated fake data for fixtures and demos. Mock endpoints are deterministic when you provide a seed.

REAL DATA

Curated reference facts and standards computations such as currencies, holidays, timezones, HTTP fields and CIDR tools. Real data is sourced, never seeded.