Skip to main content

Dice API

The Dice API is a quick way to get a dice roll when you need one.

The front page enables anyone to roll using simple form input. Savvy developers might also find ways to leverage HTTP or curl requests into their own apps.

Roll some dice!

GET /dice/{roll} - Get the results of a roll as json.

Syntax

{dice}d{sides}(+/-){mod}b(+/-){buff}

All variables are 1 or 2 digit numbers and must appear in this order.

variable required description note example
dice number of dice to roll if blank, defaults to 1 2
d ✅ separates dice and sides d
sides ✅ number of sides on each dice 10
mod modifier for each dice -1
buff modifier for total requires b before it 3

Here's the regex for my fellow enthusiasts...

Example

curl "https://api.starlord.zip/dice/2d10-1b+3" | jq

{
  "dice": 2,
  "sides": 10,
  "mod": -1,
  "buff": 3,
  "faces": [
    4,
    3
  ],
  "total": 10
}

faces is an array result of all dice with mod applied to each, and total should be obvious.

Save a roll!

POST /dice/{roll} - Roll and save the results for later!

Everything is the same as above, but you get three extra fields back:

  • id - a UUID of the roll
    • this is what you wanna save!
  • epoch - a timestamp of when the roll happened
    • for proving when the roll happened
  • recall - a URL to bring up the roll again
    • or save this instead!

Recall a roll!

GET /dice/id/{id} - Retrieve a previous roll as json.

Use the id from a previous roll to get all its data and prove to someone that the roll did actually occur!

If you saved the recall URL from a previously recorded roll, you don't need this!

Back to top