Making a call

Rollful is a dice-rolling API over plain JSON and HTTP. There is no key, no signup and no account, so a call is a request and nothing else — every language can make one.

The base URL is https://api.rollful.dev, and the rolling itself is OpenDice. In JavaScript you can skip the network and use the package directly.

Your first roll

Send a formula, get back every die it rolled.

curl

curl 'https://api.rollful.dev/v1/roll?formula=4d6kh3'

JavaScript

const response = await fetch('https://api.rollful.dev/v1/roll?formula=4d6kh3')
const result = await response.json()

console.log(result.total) // 14

Python

import requests

result = requests.get(
    'https://api.rollful.dev/v1/roll',
    params={'formula': '4d6kh3'},
).json()

print(result['total'])  # 14

PHP

$query = http_build_query(['formula' => '4d6kh3']);
$result = json_decode(
    file_get_contents("https://api.rollful.dev/v1/roll?$query"),
    true,
);

echo $result['total']; // 14

Go

url := "https://api.rollful.dev/v1/roll?formula=" + url.QueryEscape("4d6kh3")

response, err := http.Get(url)
if err != nil {
  return err
}
defer response.Body.Close()

var result struct {
  Total int `json:"total"`
}
if err := json.NewDecoder(response.Body).Decode(&result); err != nil {
  return err
}

fmt.Println(result.Total) // 14

Ruby

require 'json'
require 'net/http'

uri = URI('https://api.rollful.dev/v1/roll')
uri.query = URI.encode_www_form(formula: '4d6kh3')
result = JSON.parse(Net::HTTP.get(uri))

puts result['total'] # 14

Every call answers with the same shape:

{
  "formula": "4d6kh3",
  "dice": [
    {
      "sides": 6,
      "results": [5, 4, 5, 3],
      "kept": [5, 5, 4],
      "keptFlags": [true, true, true, false],
      "total": 14
    }
  ],
  "total": 14
}

results holds every die, including the one that was dropped, and keptFlags lines up with it so an interface can dim that die rather than hide it. Reading a result walks through each field.

Encode the formula

+ means a space in a query string, so 2d6+3 has to be sent as 2d6%2B3 or it arrives as 2d6 3 and fails to parse. Every client above escapes it for you except curl, where you write it yourself. Or send the formula in a POST body, where it is just JSON.

Bonuses, tags and advantage

GET takes a formula and little else. For anything more, POST the same roll as JSON.

curl

curl -X POST https://api.rollful.dev/v1/roll \
  -H 'content-type: application/json' \
  -d '{"formula":"1d20+7","advantage":"advantage"}'

JavaScript

const response = await fetch('https://api.rollful.dev/v1/roll', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ formula: '1d20+7', advantage: 'advantage' }),
})
const result = await response.json()

Python

result = requests.post(
    'https://api.rollful.dev/v1/roll',
    json={'formula': '1d20+7', 'advantage': 'advantage'},
).json()

PHP

$result = json_decode(file_get_contents(
    'https://api.rollful.dev/v1/roll',
    false,
    stream_context_create(['http' => [
        'method' => 'POST',
        'header' => 'content-type: application/json',
        'content' => json_encode(['formula' => '1d20+7', 'advantage' => 'advantage']),
    ]]),
), true);

Go

body, err := json.Marshal(map[string]string{
  "formula":   "1d20+7",
  "advantage": "advantage",
})
if err != nil {
  return err
}

response, err := http.Post(
  "https://api.rollful.dev/v1/roll",
  "application/json",
  bytes.NewReader(body),
)

Ruby

result = JSON.parse(Net::HTTP.post(
  URI('https://api.rollful.dev/v1/roll'),
  { formula: '1d20+7', advantage: 'advantage' }.to_json,
  'content-type' => 'application/json',
).body)

A body may also carry bonuses, which add dice or numbers to the roll, and tags, which name the words a formula is allowed to end with. Both are described on the endpoint itself.

Several rolls at once

POST /v1/roll/batch takes up to 20 rolls and answers with the same number of results, in order. One request rather than twenty is the difference between one round trip and twenty, and the whole batch is counted against a single dice budget.

curl -X POST https://api.rollful.dev/v1/roll/batch \
  -H 'content-type: application/json' \
  -d '{"rolls":[{"formula":"4d6kh3"},{"formula":"4d6kh3"},{"formula":"4d6kh3"}]}'

Generating a client

The API describes itself at api.rollful.dev/openapi.json, an OpenAPI 3.1 document generated from the same schemas that validate the requests — so it cannot describe an API this one does not serve. Point a client generator at it, or import it into whatever you use to poke at HTTP.

curl https://api.rollful.dev/openapi.json