Dice Roll API: The Complete Guide

Need to roll dice in your application? This guide covers everything you need to know about dice rolling via API, including standard dice notation, modifiers, and implementation examples for games and simulations.

Understanding Dice Notation

Dice notation (also called dice algebra) uses the format NdX+M, where N is the number of dice, X is the number of sides, and M is an optional modifier. For example, "2d6+3" means roll two 6-sided dice and add 3 to the result.

This notation originated in tabletop RPGs and is now the standard way to express dice rolls in gaming and simulations.

Common Dice Types

Standard polyhedral dice used in gaming:

d4 - Tetrahedron

4-sided die. Often used for small damage or healing in RPGs.

d6 - Cube

The standard die. Used in countless board games and RPGs.

d8 - Octahedron

8-sided die. Common for weapon damage in D&D.

d10 - Pentagonal Trapezohedron

10-sided die. Used for percentile rolls (d100) with two d10s.

d12 - Dodecahedron

12-sided die. Great axe damage, among other uses.

d20 - Icosahedron

20-sided die. The iconic die for attack rolls and saving throws in D&D.

Using the Dice Roll API

TinyFn provides a simple endpoint to roll dice:

GET https://api.tinyfn.io/v1/random/dice?notation=2d6+3
Headers: X-API-Key: your-api-key

{
  "notation": "2d6+3",
  "total": 11,
  "rolls": [4, 4],
  "modifier": 3,
  "dice_count": 2,
  "dice_sides": 6,
  "min_possible": 5,
  "max_possible": 15
}

Parameters

Code Examples

JavaScript / Node.js

const response = await fetch(
  'https://api.tinyfn.io/v1/random/dice?notation=2d6+3',
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const { total, rolls } = await response.json();
console.log(`Rolled ${rolls.join(', ')} + 3 = ${total}`); // Rolled 4, 4 + 3 = 11

Python

import requests

response = requests.get(
    'https://api.tinyfn.io/v1/random/dice',
    params={'notation': '2d6+3'},
    headers={'X-API-Key': 'your-api-key'}
)
data = response.json()
print(f"Rolled {data['rolls']} + 3 = {data['total']}")

cURL

curl "https://api.tinyfn.io/v1/random/dice?notation=2d6%2B3" \
  -H "X-API-Key: your-api-key"

Common Use Cases

• Tabletop Games: Digital dice rollers for D&D, Pathfinder, etc.
• Video Games: Damage calculations, loot drops, random events
• Board Game Apps: Replace physical dice in digital versions
• Simulations: Statistical modeling with dice distributions
• Discord Bots: Dice commands for gaming servers

Best Practices

1. Show individual rolls: Players like to see each die result
2. Support standard notation: Use NdX format for compatibility
3. Display modifiers clearly: Show how the total was calculated
4. Include history: Let users see previous rolls

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.