Skip to main content

Random Picker & Shuffle API

MOCK DATA

Weighted random picks from your own options, unbiased list shuffles and tunable coin flips — every decision reproducible with a seed.

Generated test data for fixtures and development

Base URL
/api/random
Category
Numbers & Chance
Capabilities
3 routes Seedable
Last updated
July 29, 2026

GET /api/random/pick Pick one of your options (optionally weighted)

Uniform by default; pass weights (one positive number per option, any scale — 95,5 and 19,1 are equivalent) to bias the draw. count repeats the draw independently.

Live requestRuns against the public API
No key required
GET/api/random/pick?options=rock%2Cpaper%2Cscissors

Request parameters

Comma-separated options to pick from: 1–100 items, each at most 100 characters. Whitespace around commas is trimmed and empty entries are dropped.

Relative weights, one per option in the same order. Each must be a number > 0 (the scale is arbitrary — only ratios matter). Length must equal 'options'. Omit for a uniform pick.

Advanced response options7 options

How many records to generate (1–100).

Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

Return all fields except these (comma-separated).

Response format: json envelope, ndjson (one record per line) or csv.

Pretty-print the JSON response.

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples
Code samples Ready-to-copy requests in 4 languages
Choose a code sample language 
curl "https://randomapi.dev/api/random/pick?options=rock,paper,scissors"
const res = await fetch("https://randomapi.dev/api/random/pick?options=rock,paper,scissors");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/random/pick?options=rock,paper,scissors").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/random/pick?options=rock,paper,scissors"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 2
options list required

Comma-separated options to pick from: 1–100 items, each at most 100 characters. Whitespace around commas is trimmed and empty entries are dropped.

example: options=rock,paper,scissors
weights list

Relative weights, one per option in the same order. Each must be a number > 0 (the scale is arbitrary — only ratios matter). Length must equal 'options'. Omit for a uniform pick.

example: weights=5,3,2
Universal parameters Shared response and formatting options 7
count int

How many records to generate (1–100).

default: 1
allowed: 1 – 100
example: count=3
seed int

Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).

example: seed=42
fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=index,value
exclude list

Return all fields except these (comma-separated).

example: exclude=value
format enum

Response format: json envelope, ndjson (one record per line) or csv.

default: json
allowed: json | ndjson | csv
example: format=csv
pretty boolean

Pretty-print the JSON response.

default: false
example: pretty=true
unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false
example: unwrap=true
Response schema Fields returned in each record 2
index integer

Zero-based position of this independent draw in the returned batch.

example: 0

value string

The picked option — always one of the provided 'options'.

example: rock

Documented examples

Build-generated requests and complete responses 3
Rock, paper or scissors?
GET /api/random/pick?options=rock,paper,scissors 
{
  "data": [
    {
      "index": 0,
      "value": "paper"
    }
  ],
  "meta": {
    "endpoint": "random",
    "route": "/pick",
    "count": 1,
    "seed": 42,
    "params": {
      "options": [
        "rock",
        "paper",
        "scissors"
      ]
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
5% critical hits, 20 rolls
GET /api/random/pick?options=hit,critical&weights=95,5&count=20&seed=7 
{
  "data": [
    {
      "index": 0,
      "value": "hit"
    },
    {
      "index": 1,
      "value": "hit"
    },
    {
      "index": 2,
      "value": "hit"
    },
    {
      "index": 3,
      "value": "hit"
    },
    {
      "index": 4,
      "value": "hit"
    },
    {
      "index": 5,
      "value": "hit"
    },
    {
      "index": 6,
      "value": "critical"
    },
    {
      "index": 7,
      "value": "hit"
    },
    {
      "index": 8,
      "value": "hit"
    },
    {
      "index": 9,
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Bucket 100 users 50/30/20
GET /api/random/pick?options=A,B,C&weights=50,30,20&count=100&seed=42 
{
  "data": [
    {
      "index": 0,
      "value": "A"
    },
    {
      "index": 1,
      "value": "A"
    },
    {
      "index": 2,
      "value": "C"
    },
    {
      "index": 3,
      "value": "A"
    },
    {
      "index": 4,
      "value": "C"
    },
    {
      "index": 5,
      "value": "A"
    },
    {
      "index": 6,
      "value": "A"
    },
    {
      "index": 7,
      "value": "C"
    },
    {
      "index": 8,
      "value": "A"
    },
    {
      "index": 9,
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

GET /api/random/shuffle Shuffle a list into a random order

An unbiased Fisher–Yates permutation of your items. count returns several independent shuffles of the same list.

Live requestRuns against the public API
No key required
GET/api/random/shuffle?items=alice%2Cbob%2Ccarol%2Cdave

Request parameters

Comma-separated items to shuffle: 2–100 items. Whitespace around commas is trimmed and empty entries are dropped.

Advanced response options7 options

How many records to generate (1–100).

Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

Return all fields except these (comma-separated).

Response format: json envelope, ndjson (one record per line) or csv.

Pretty-print the JSON response.

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples
Code samples Ready-to-copy requests in 4 languages
Choose a code sample language 
curl "https://randomapi.dev/api/random/shuffle?items=alice,bob,carol,dave"
const res = await fetch("https://randomapi.dev/api/random/shuffle?items=alice,bob,carol,dave");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/random/shuffle?items=alice,bob,carol,dave").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/random/shuffle?items=alice,bob,carol,dave"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 1
items list required

Comma-separated items to shuffle: 2–100 items. Whitespace around commas is trimmed and empty entries are dropped.

example: items=alice,bob,carol,dave
Universal parameters Shared response and formatting options 7
count int

How many records to generate (1–100).

default: 1
allowed: 1 – 100
example: count=3
seed int

Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).

example: seed=42
fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=index,items
exclude list

Return all fields except these (comma-separated).

example: exclude=shuffled
format enum

Response format: json envelope, ndjson (one record per line) or csv.

default: json
allowed: json | ndjson | csv
example: format=csv
pretty boolean

Pretty-print the JSON response.

default: false
example: pretty=true
unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false
example: unwrap=true
Response schema Fields returned in each record 3
index integer

Zero-based position of this independent shuffle in the returned batch.

example: 0

items string[]

The input items in their original order, echoed for easy comparison.

example: ["alice","bob","carol","dave"]

shuffled string[]

The same items in random order — an unbiased Fisher–Yates permutation.

example: ["carol","alice","dave","bob"]

Documented examples

Build-generated requests and complete responses 3
Random standup order
GET /api/random/shuffle?items=alice,bob,carol,dave 
{
  "data": [
    {
      "index": 0,
      "items": [
        "alice",
        "bob",
        "carol",
        "dave"
      ],
      "shuffled": [
        "alice",
        "dave",
        "carol",
        "bob"
      ]
    }
  ],
  "meta": {
    "endpoint": "random",
    "route": "/shuffle",
    "count": 1,
    "seed": 42,
    "params": {
      "items": [
        "alice",
        "bob",
        "carol",
        "dave"
      ]
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Reproducible quiz-answer order
GET /api/random/shuffle?items=paris,london,berlin,madrid&seed=7 
{
  "data": [
    {
      "index": 0,
      "items": [
        "paris",
        "london",
        "berlin",
        "madrid"
      ],
      "shuffled": [
        "paris",
        "london",
        "madrid",
        "berlin"
      ]
    }
  ],
  "meta": {
    "endpoint": "random",
    "route": "/shuffle",
    "count": 1,
    "seed": 7,
    "params": {
      "items": [
        "paris",
        "london",
        "berlin",
        "madrid"
      ]
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Five deals of the same hand
GET /api/random/shuffle?items=ace,king,queen,jack,ten&count=5&seed=3 
{
  "data": [
    {
      "index": 0,
      "items": [
        "ace",
        "king",
        "queen",
        "jack",
        "ten"
      ],
      "shuffled": [
        "ten",
        "queen",
        "jack",
        "ace",
        "king"
      ]
    },
    {
      "index": 1,
      "items": [
        "ace",
        "king",
        "queen",
        "jack",
        "ten"
      ],
      "shuffled": [
        "queen",
        "ace",
        "king",
        "jack",
        "ten"
      ]
    },
    {
      "index": 2,
      "items": [
        "ace",
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

GET /api/random/boolean Flip a (possibly biased) coin

Returns true with the given probability — 0 is never, 1 is always, 0.5 is a fair coin. count gives independent flips.

Live requestRuns against the public API
No key required
GET/api/random/boolean

Request parameters

Probability that the result is true, from 0 (never) to 1 (always).

Advanced response options7 options

How many records to generate (1–100).

Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

Return all fields except these (comma-separated).

Response format: json envelope, ndjson (one record per line) or csv.

Pretty-print the JSON response.

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples
Code samples Ready-to-copy requests in 4 languages
Choose a code sample language 
curl "https://randomapi.dev/api/random/boolean"
const res = await fetch("https://randomapi.dev/api/random/boolean");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/random/boolean").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/random/boolean"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 1
probability float

Probability that the result is true, from 0 (never) to 1 (always).

default: 0.5
allowed: 0 – 1
example: probability=0.7
Universal parameters Shared response and formatting options 7
count int

How many records to generate (1–100).

default: 1
allowed: 1 – 100
example: count=3
seed int

Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).

example: seed=42
fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=index,value
exclude list

Return all fields except these (comma-separated).

example: exclude=probability
format enum

Response format: json envelope, ndjson (one record per line) or csv.

default: json
allowed: json | ndjson | csv
example: format=csv
pretty boolean

Pretty-print the JSON response.

default: false
example: pretty=true
unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false
example: unwrap=true
Response schema Fields returned in each record 3
index integer

Zero-based position of this independent trial in the returned batch.

example: 0

value boolean

The flip result — true with the requested probability.

example: true

probability float

Echo of the probability that produced this flip (default 0.5).

example: 0.7

Documented examples

Build-generated requests and complete responses 3
Fair coin flip
GET /api/random/boolean 
{
  "data": [
    {
      "index": 0,
      "value": true,
      "probability": 0.5
    }
  ],
  "meta": {
    "endpoint": "random",
    "route": "/boolean",
    "count": 1,
    "seed": 42,
    "params": {
      "probability": 0.5
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
70% likely to be true
GET /api/random/boolean?probability=0.7&seed=11 
{
  "data": [
    {
      "index": 0,
      "value": true,
      "probability": 0.7
    }
  ],
  "meta": {
    "endpoint": "random",
    "route": "/boolean",
    "count": 1,
    "seed": 11,
    "params": {
      "probability": 0.7
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
10% error injection, 50 trials
GET /api/random/boolean?probability=0.1&count=50&seed=2 
{
  "data": [
    {
      "index": 0,
      "value": false,
      "probability": 0.1
    },
    {
      "index": 1,
      "value": false,
      "probability": 0.1
    },
    {
      "index": 2,
      "value": false,
      "probability": 0.1
    },
    {
      "index": 3,
      "value": false,
      "probability": 0.1
    },
    {
      "index": 4,
      "value": false,
      "probability": 0.1
    },
    {
      "index": 5,
      "value": false,
      "probability": 0.1
    },
    {
      "index": 6,
      "value": false,
      "probability": 0.1
    },
    {
      "index": 7,
      "value": false,
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

About this API

Coverage, behavior and common use cases

Coverage & behavior

Three tiny decide-for-me tools driven entirely by your own values — the API contributes only the randomness:

  • /api/random/pick — draw one of your comma-separated options. Add weights (one number > 0 per option, same order, any scale) to bias the draw: options=hit,critical&weights=95,5 makes critical roughly a 1-in-20 result. Omit weights for a uniform draw.
  • /api/random/shuffle — your items in a random order via an unbiased Fisher–Yates permutation, with the original order echoed alongside for easy diffing.
  • /api/random/boolean — a coin flip where probability sets the chance of true (0 = never, 1 = always, default 0.5).

Each route returns a single answer by default (count=1); raise count (up to 100) for repeated independent draws — e.g. ?count=100 on /pick buckets a whole batch in one request. Every record carries a zero-based index, so repeated outcomes remain distinct trials. Pin a seed and the same request returns the same decisions forever, so raffles, A/B assignments and test fixtures stay auditable and reproducible.

Bad input never degrades silently: mismatched weights/options lengths, zero/negative/non-numeric weights, out-of-range probabilities and over-long option lists are all rejected with a 400 that names the offending parameter.

Use it for

  • Weighted A/B/C bucket assignment for experiments and staged feature rollouts
  • Draw a raffle or giveaway winner verifiably — publish the seed so anyone can re-run the draw
  • Shuffle quiz answers, standup order or playlists server-side
  • Inject failures at a tunable rate when testing retry and fallback logic

Frequently asked questions

Practical answers about this endpoint 3
Can choices be weighted?

Yes — /pick accepts options=a,b,c with weights=5,3,1, making the first option five times likelier than the last.

Is the shuffle reproducible?

/shuffle returns your items in random order — same seed, same order, forever; omit the seed for a fresh permutation.

How do I flip a biased coin?

/boolean?probability=0.8 returns true 80% of the time — perfect for feature-flag and A/B fixtures.

Related APIs

Useful next tools in the catalog
Dice Roll API MOCK DATA

Roll dice in standard NdS+M notation (2d6+3, d20, 4d8-2) — get each die result, the modifier and the total, with seedable, reproducible rolls.
Random Number Generator API MOCK DATA

Random integers or floats in any range — control decimal precision, draw guaranteed-unique values, and pin a seed for reproducible sequences.
Random Word API MOCK DATA

Random English words by part of speech — nouns, verbs, adjectives or adverbs — with working length filters, seedable output and honest 400s when nothing fits.
UUID & ID Generator API MOCK DATA

Generate seed-reproducible UUIDs and compact IDs, or inspect any canonical UUID's RFC 9562 variant, version and UUIDv7 timestamp fields.