Roll a formula from a query string

GET

/v1/roll

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.rollful.dev/v1/roll?formula=2d6%2B3&advantage=normal");

CURLcode ret = curl_easy_perform(hnd);

using System.Net.Http.Headers;
var client = new HttpClient();
var request = new HttpRequestMessage
{
    Method = HttpMethod.Get,
    RequestUri = new Uri("https://api.rollful.dev/v1/roll?formula=2d6%2B3&advantage=normal"),
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}

package main

import (
  "fmt"
  "net/http"
  "io"
)

func main() {

  url := "https://api.rollful.dev/v1/roll?formula=2d6%2B3&advantage=normal"

  req, _ := http.NewRequest("GET", url, nil)

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.rollful.dev/v1/roll?formula=2d6%2B3&advantage=normal"))
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.rollful.dev/v1/roll?formula=2d6%2B3&advantage=normal")
  .get()
  .build();

Response response = client.newCall(request).execute();

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.rollful.dev/v1/roll',
  params: {formula: '2d6+3', advantage: 'normal'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

const url = 'https://api.rollful.dev/v1/roll?formula=2d6%2B3&advantage=normal';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.rollful.dev/v1/roll?formula=2d6%2B3&advantage=normal")
  .get()
  .build()

val response = client.newCall(request).execute()

use reqwest;

#[tokio::main]
pub async fn main() {
    let url = "https://api.rollful.dev/v1/roll";

    let querystring = [
        ("formula", "2d6+3"),
        ("advantage", "normal"),
    ];

    let client = reqwest::Client::new();
    let response = client.get(url)
        .query(&querystring)
        .send()
        .await;

    let results = response.unwrap()
        .json::<serde_json::Value>()
        .await
        .unwrap();

    dbg!(results);
}

curl --request GET \
  --url 'https://api.rollful.dev/v1/roll?formula=2d6%2B3&advantage=normal'

The link- and curl-friendly form. Use POST for bonuses and tags.

Parameters

Query Parameters

formula

required

A dice formula, such as 2d6+3 or 4d6kh3.

string

>= 1 characters <= 200 characters

A dice formula, such as 2d6+3 or 4d6kh3.

advantage

Applies to the first plain d20 term. Net advantage and disadvantage yourself.

string

Allowed values: normal advantage disadvantage

Applies to the first plain d20 term. Net advantage and disadvantage yourself.

Responses

200

The roll, with every die it rolled.

application/json

object

formula

required

string

dice

required

Array<object>

object

sides

required

integer

sign

required

Any of:

number
number

number

Allowed values: 1

results

required

Every die rolled, including dropped ones. A penetrated 1 is recorded as 0, the one case this holds a number below 1.

Array<integer>

kept

required

The dice that counted towards the total.

Array<integer>

keptFlags

required

Aligned to results: whether each die was kept.

Array<boolean>

multiplier

required

integer

total

required

This group’s signed contribution to the total.

integer

naturalHigh

required

boolean

naturalLow

required

boolean

modifier

required

Sum of the flat modifiers. Dice are not counted.

integer

modifiers

required

Each flat modifier in order, so +1 -6 can be shown rather than -5.

Array<integer>

total

required

integer

advantageState

required

Applies to the first plain d20 term. Net advantage and disadvantage yourself.

string

Allowed values: normal advantage disadvantage

tag

string

Example

{
  "dice": [
    {
      "sign": 1
    }
  ],
  "advantageState": "normal"
}

400

The request or the formula was rejected.

application/json

object

error

required

object

code

required

string

Allowed values: invalid_request invalid_formula too_many_dice

message

required

string

Example

{
  "error": {
    "code": "invalid_formula",
    "message": "A roll may use at most 1000 dice, but this one asks for 999999"
  }
}

413

The request body was larger than the limit.

application/json

object

error

required

object

code

required

string

Allowed values: payload_too_large

message

required

string

Example

{
  "error": {
    "code": "payload_too_large",
    "message": "A request body may be at most 8192 bytes"
  }
}

429

Too many requests from this address.

application/json

object

error

required

object

code

required

string

Allowed values: rate_limited

message

required

string

Example

{
  "error": {
    "code": "rate_limited",
    "message": "At most 60 requests every 60 seconds"
  }
}

500

The random source failed.

application/json

object

error

required

object

code

required

string

Allowed values: internal_error

message

required

string

Example

{
  "error": {
    "code": "internal_error",
    "message": "The random source failed. Try again."
  }
}