Random Choice API: The Complete Guide

Need to pick random items from a list in your application? This guide covers everything you need to know about random selection via API, including weighted choices, multiple picks, and implementation examples.

Understanding Random Selection

Random selection picks items from a list without predictable bias. It's fundamental to fair decision-making, sampling, and creating variety in applications. True random selection gives each item an equal probability of being chosen.

The API can handle simple uniform selection or weighted selection where some items have higher probability than others.

Selection Types

Different types of random selection:

Uniform Selection

Each item has equal probability. If you have 10 items, each has a 10% chance of being selected.

Weighted Selection

Items have different probabilities based on assigned weights. Useful for loot drops, raffles, or probability experiments.

Selection with Replacement

After picking an item, it goes "back in the pool" and can be picked again. Allows duplicates.

Selection without Replacement

Once picked, an item cannot be selected again. Ensures unique selections.

Using the Random Choice API

TinyFn provides a simple endpoint to pick random items:

POST https://api.tinyfn.io/v1/random/choice
Headers: X-API-Key: your-api-key
Content-Type: application/json

{
  "items": ["pizza", "burger", "sushi", "tacos", "salad"],
  "count": 2,
  "unique": true
}

{
  "choices": ["sushi", "tacos"],
  "count": 2,
  "unique": true,
  "total_items": 5
}

Parameters

Code Examples

JavaScript / Node.js

const response = await fetch('https://api.tinyfn.io/v1/random/choice', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    items: ['pizza', 'burger', 'sushi', 'tacos', 'salad'],
    count: 1
  })
});
const { choices } = await response.json();
console.log(`Let's eat: ${choices[0]}`); // Let's eat: sushi

Python

import requests

response = requests.post(
    'https://api.tinyfn.io/v1/random/choice',
    json={'items': ['pizza', 'burger', 'sushi', 'tacos', 'salad'], 'count': 2},
    headers={'X-API-Key': 'your-api-key'}
)
choices = response.json()['choices']
print(f"Selected: {choices}")

cURL

curl -X POST "https://api.tinyfn.io/v1/random/choice" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"items": ["pizza", "burger", "sushi"], "count": 1}'

Common Use Cases

• Decision Making: Random restaurant picker, movie selector
• Giveaways: Random winner selection from participant list
• Gaming: Loot drops, random encounters, card draws
• Testing: Random test case selection, A/B assignment
• Content Rotation: Random ad selection, featured content

Best Practices

1. Use unique when needed: For raffles, prevent duplicate winners
2. Document weights: If using weighted selection, make probabilities clear
3. Validate inputs: Ensure items array is not empty
4. Handle edge cases: What if count > items length with unique=true?

Use via MCP

Your AI agent can call this tool directly via Model Context Protocol — no HTTP code needed. Add TinyFn to Claude Desktop, Cursor, or any MCP client:

{
  "mcpServers": {
    "tinyfn-random": {
      "url": "https://api.tinyfn.io/mcp/random/",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

See all random tools available via MCP in our Random MCP Tools for AI Agents guide.