Dice Roll API

Q: Can I roll in bulk?

count repeats the same notation up to 100 times in one call — handy for statistics or bulk simulation.

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.

Generated test data for fixtures and development

Base URL: /api/dice
Category: Numbers & Chance
Capabilities: 1 route Seedable
Last updated: July 29, 2026

GET /api/dice/roll Roll dice in NdS+M notation Returns a list

Each record is one independent roll of the whole notation; count rolls it several times. 2d6+3, 2d6%2B3 and 2d6 3 are all the same roll (a raw + decodes to a space).

Live requestRuns against the public API

No key required

GET/api/dice/roll?notation=2d6%2B3

Request parameters

notationdefault 1d6

Dice notation NdS+M (case-insensitive): N dice (1-100, default 1) with S sides (2-1000) and an optional modifier M (-1000..+1000), e.g. 2d6+3, d20, 4d8-2. A raw '+' decodes to a space in query strings, so '2d6+3', '2d6%2B3' and '2d6 3' are all read as 2d6+3.

Advanced response options7 options

countdefault 1

How many records to generate (1–100).

seed

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

fields

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

exclude

Return all fields except these (comma-separated).

formatdefault json

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

prettydefault false

Pretty-print the JSON response.

unwrapdefault false

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 8 params · 5 fields · 4 examples

Code samples Ready-to-copy requests in 4 languages

curl JavaScript Python PHP

curl "https://randomapi.dev/api/dice/roll?notation=2d6%2B3"

const res = await fetch("https://randomapi.dev/api/dice/roll?notation=2d6%2B3");
const { data, meta } = await res.json();

import requests

data = requests.get("https://randomapi.dev/api/dice/roll?notation=2d6%2B3").json()["data"]

$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/dice/roll?notation=2d6%2B3"
), true);
$data = $json["data"];

Parameters Route-specific request inputs 1

Parameter	Type	Default & allowed	Description
`notation`	string	default: 1d6 example: 2d6+3	Dice notation NdS+M (case-insensitive): N dice (1-100, default 1) with S sides (2-1000) and an optional modifier M (-1000..+1000), e.g. 2d6+3, d20, 4d8-2. A raw '+' decodes to a space in query strings, so '2d6+3', '2d6%2B3' and '2d6 3' are all read as 2d6+3.

notation string

default: 1d6

example: notation=2d6+3

Universal parameters Shared response and formatting options 7

Parameter	Type	Default & allowed	Description
`count`	int	default: 1 allowed: 1 – 100 example: 3	How many records to generate (1–100).
`seed`	int	example: 42	Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).
`fields`	list	example: index,notation	Return only these fields (comma-separated). Mutually exclusive with 'exclude'.
`exclude`	list	example: total	Return all fields except these (comma-separated).
`format`	enum	default: json allowed: json \| ndjson \| csv example: csv	Response format: json envelope, ndjson (one record per line) or csv.
`pretty`	boolean	default: false example: true	Pretty-print the JSON response.
`unwrap`	boolean	default: false example: true	Drop the envelope: return the raw array/object without data/meta wrapper.

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,notation

exclude list

Return all fields except these (comma-separated).

example: exclude=total

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 5

Field	Type	Description	Example
`index`	integer	Zero-based position of this independent roll in the returned batch.	0
`notation`	string	Canonical lowercase echo of the roll: explicit dice count ('d20' → '1d20'), zero modifier omitted.	2d6+3
`dice`	integer[]	Each individual die result in roll order — exactly N values, every one between 1 and S.	[4,2]
`modifier`	integer	The flat modifier from the notation (0 when it has none).	3
`total`	integer	Sum of all dice plus the modifier.	9

index integer

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

example: 0

notation string

Canonical lowercase echo of the roll: explicit dice count ('d20' → '1d20'), zero modifier omitted.

example: 2d6+3

dice integer[]

Each individual die result in roll order — exactly N values, every one between 1 and S.

example: [4,2]

modifier integer

The flat modifier from the notation (0 when it has none).

example: 3

total integer

Sum of all dice plus the modifier.

example: 9

Documented examples

Build-generated requests and complete responses 4

One 2d6+3 roll /api/dice/roll?notation=2d6%2B3

GET /api/dice/roll?notation=2d6%2B3

{
  "data": [
    {
      "index": 0,
      "notation": "2d6+3",
      "dice": [
        3,
        5
      ],
      "modifier": 3,
      "total": 11
    }
  ],
  "meta": {
    "endpoint": "dice",
    "route": "/roll",
    "count": 1,
    "seed": 42,
    "params": {
      "notation": "2d6+3"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

A raw '+' works too (decodes as a space) /api/dice/roll?notation=2d6+3

GET /api/dice/roll?notation=2d6+3

{
  "data": [
    {
      "index": 0,
      "notation": "2d6+3",
      "dice": [
        3,
        5
      ],
      "modifier": 3,
      "total": 11
    }
  ],
  "meta": {
    "endpoint": "dice",
    "route": "/roll",
    "count": 1,
    "seed": 42,
    "params": {
      "notation": "2d6+3"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

Five d20 rolls /api/dice/roll?notation=d20&count=5

GET /api/dice/roll?notation=d20&count=5

{
  "data": [
    {
      "index": 0,
      "notation": "1d20",
      "dice": [
        10
      ],
      "modifier": 0,
      "total": 10
    },
    {
      "index": 1,
      "notation": "1d20",
      "dice": [
        1
      ],
      "modifier": 0,
      "total": 1
    },
    {
      "index": 2,
      "notation": "1d20",
      "dice": [
        18
      ],
      "modifier": 0,
      "total": 18
    },
    {
      "index": 3,
      "notation": "1d20",
      "dice": [
        4
      ],
      "modifier": 0,
      "total": 4
    },
    {
      "index": 4,
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

Reproducible 4d8-2 batch /api/dice/roll?notation=4d8-2&count=3&seed=42

GET /api/dice/roll?notation=4d8-2&count=3&seed=42

{
  "data": [
    {
      "index": 0,
      "notation": "4d8-2",
      "dice": [
        4,
        6,
        5,
        3
      ],
      "modifier": -2,
      "total": 16
    },
    {
      "index": 1,
      "notation": "4d8-2",
      "dice": [
        1,
        1,
        4,
        5
      ],
      "modifier": -2,
      "total": 9
    },
    {
      "index": 2,
      "notation": "4d8-2",
      "dice": [
        7,
        1,
        3,
        4
      ],
      "modifier": -2,
      "total": 13
    }
  ],
  "meta": {
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

About this API

Coverage, behavior and common use cases

Coverage & behavior

Rolls standard tabletop dice notation NdS+M: N dice with S sides each, plus an optional flat modifier M. N defaults to 1 (d20 = 1d20), the modifier may be + or -, and case doesn't matter (2D10-2 works). Limits: 1–100 dice, 2–1000 sides, modifier −1000…+1000 — anything else is a clear 400 that repeats the format (Use NdS+M, e.g. 2d6+3, d20, 4d8-2).

The + gotcha: in a raw URL query string a literal + decodes to a space, so this endpoint treats internal whitespace as the + you typed. notation=2d6+3 and notation=2d6%2B3 both work and mean the same roll — no silent "modifier lost" surprises.

Each record is one independent, indexed roll of the whole notation: ?notation=2d6%2B3&count=10 returns ten separate 2d6+3 rolls, each with its zero-based index, individual die results (dice), modifier, and total (sum of dice + modifier — verifiable per record). The index keeps repeated outcomes distinguishable; notation echoes the canonical lowercase form (D20 → 1d20), and a pinned seed makes every roll byte-identical forever.

Use it for

Power a Discord/Slack dice bot without writing your own notation parser
Roll D&D damage and ability checks server-side so clients can't tamper with results
Reproducible game-logic tests: seed + count=100 gives a fixed batch of rolls in every CI run

Frequently asked questions

Practical answers about this endpoint 3

What notation is supported?

Classic tabletop notation — NdS with an optional modifier, like 2d6+3 or 1d20-1. The response shows each individual die plus the modifier and total.

Are the rolls fair?

Each die is uniform over its sides via the seeded PRNG; pass seed to replay an exact session or omit it for fresh rolls per request.

Can I roll in bulk?

count repeats the same notation up to 100 times in one call — handy for statistics or bulk simulation.

Useful next tools in the catalog

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.

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.

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.