ENDPOINTS: | /roll | /statroll | /notation |
Welcome to the documentation for DiceForge! DiceForge is a powerful, easy-to-use API for rolling dice and generating random results for tabletop games, simulations, and other applications. With support for various dice configurations and roll types, DiceForge provides a flexible solution for your dice-rolling needs.
To get started with DiceForge, you will need to sign up for a FREE API key through RapidAPI. Once you have your API key, you can start making requests to the DiceForge endpoints.
I have provided a comfortable FREE tier so everyone can access this API! Paid plans are only needed if you want the advanced endpoints (notation and statrolls), or at production application levels (10k+ calls/mo).
DiceForge offers three main endpoints for rolling dice: /roll and /statroll which supports both GET and POST requests, as well as /notation which only supports POST requests.
All endpoints will return a JSON response body structured like the following:
{
"dice": [
{
"sides": 6,
"results": [
{
"rolls": [5, 2],
"selected_roll": 5
},
{
"rolls": [3, 1],
"selected_roll": 3
}
],
"modifier": 4,
"total": 12
},
{
"sides": 20,
"results": [
{
"rolls": [12, 5],
"selected_roll": 12
}
],
"modifier": 3,
"total": 15
}
],
"total_modifier": 4,
"advantage": true,
"total": 31
}The /roll endpoint allows you to roll one or more dice with various configurations, such as the number of sides, count, and modifiers. You can also apply advantage or disadvantage to the rolls.
To make a GET request, pass the following query parameters:
sides: An integer representing the number of sides for each die.count: (optional) An integer representing the number of times each die should be rolled.modifier: (optional) An integer representing the modifier to apply to the die total.total_modifier: (optional) An integer representing the modifier to apply to the overall total of all rolls.advantage: (optional) A boolean indicating whether advantage should be applied to the rolls (default: false).disadvantage: (optional) A boolean indicating whether disadvantage should be applied to the rolls (default: false).
The response will be a JSON object containing the results of the roll, including the dice configuration, individual roll results, and the total result.
GET /roll?sides=4&modifier=2&advantage=trueResponse:
{
"dice": [
{
"sides": 4,
"results": [
{
"rolls": [2, 2],
"selected_roll": 2
}
],
"modifier": 2,
"total": 4
}
],
"advantage": true,
"total": 4
}To make a POST request, send a JSON payload with the following structure:
{
"dice": [
{
"sides": int,
"count": int,
"modifier": int
},
...
],
"advantage": boolean,
"disadvantage": boolean
}The response format is the same as for the GET request.
The /statroll endpoint is designed for rolling character stats, rolling 4 six-sided dice and dropping the lowest result.
modifier: (optional) An integer representing the modifier to apply to the die total.
To make a GET request, pass the following query parameter:
modifier: An integer representing the modifier to apply to the stat roll (default: 0).
The response format is the same as for the /roll endpoint.
To make a POST request, send a JSON with the following structure:
*If you don't want to use a modifier you need to send an empty JSON body
{
"modifier": int
}The response format is the same as for the GET request.
The /notation endpoint allows users to pass a single input string in standard RPG Dice Notation format. It can contain several roll commands in one string, for example: "2d6+12 1d20 +2 !a".
Request a roll using the RPG Dice Notation format in the request body.
Supports multiple dice deefinitions separated by a space.
advantage and disadvantage flags are available by including !a or !d in your string. NOTE using both is invalid
To make a POST request, send a JSON payload with the following structure:
{
"notation": str
}The response format is the same as for the GET request.
In case of errors, DiceForge returns an HTTP status code of 400, along with a JSON object containing a descriptive error message. Common error cases include invalid parameter values, exceeding limits, or conflicting parameters.
GET /roll?sides=6Response:
{
"dice": [
{
"sides": 6,
"results": [3],
"modifier": 0,
"total": 3
}
],
"total": 3
}POST /roll
{
"dice": [
{
"sides": 20,
"count": 2
}
],
"advantage": true
}Response:
{
"dice": [
{
"sides": 20,
"results": [
{
"rolls": [13, 19],
"selected_roll": 19
},
{
"rolls": [7, 12],
"selected_roll": 12
}
],
"modifier": 0,
"total": 31
}
],
"total": 31
}GET /statrollResponse:
{
"dice": [
{
"sides": 6,
"results": [4, 5, 6, 1],
"modifier": 0,
"total": 15
}
],
"total": 15
}POST /notation
{
"notation":"2d6+12 1d20 !a"
}Response:
{
"dice": [
{
"sides": 6,
"results": [
{
"rolls": [6, 3],
"selected_roll": 6
},
{
"rolls": [6, 1],
"selected_roll": 6
}
],
"modifier": 12,
"total": 24
},
{
"sides": 20,
"results": [
{
"rolls": [19, 18],
"selected_roll": 19
}
],
"modifier": 0,
"total": 19
}
],
"total": 43
}DiceForge has rate limits in place to ensure fair usage among all users. Please refer to the RapidAPI platform for specific rate limits associated with your subscription tier.
For any questions or support requests, please contact Joe Peterson at https://joepeterson.work/contact.
