Roll several formulas in one request

POST

/v1/roll/batch

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.rollful.dev/v1/roll/batch");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{ \"rolls\": [ { \"formula\": \"2d6+3\", \"advantage\": \"normal\", \"bonuses\": [ 1 ], \"tags\": [ \"example\" ] } ] }");

CURLcode ret = curl_easy_perform(hnd);

using System.Net.Http.Headers;
var client = new HttpClient();
var request = new HttpRequestMessage
{
    Method = HttpMethod.Post,
    RequestUri = new Uri("https://api.rollful.dev/v1/roll/batch"),
    Content = new StringContent("{ \"rolls\": [ { \"formula\": \"2d6+3\", \"advantage\": \"normal\", \"bonuses\": [ 1 ], \"tags\": [ \"example\" ] } ] }")
    {
        Headers =
        {
            ContentType = new MediaTypeHeaderValue("application/json")
        }
    }
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}

package main

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

func main() {

  url := "https://api.rollful.dev/v1/roll/batch"

  payload := strings.NewReader("{ \"rolls\": [ { \"formula\": \"2d6+3\", \"advantage\": \"normal\", \"bonuses\": [ 1 ], \"tags\": [ \"example\" ] } ] }")

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("Content-Type", "application/json")

  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/batch"))
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{ \"rolls\": [ { \"formula\": \"2d6+3\", \"advantage\": \"normal\", \"bonuses\": [ 1 ], \"tags\": [ \"example\" ] } ] }"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{ \"rolls\": [ { \"formula\": \"2d6+3\", \"advantage\": \"normal\", \"bonuses\": [ 1 ], \"tags\": [ \"example\" ] } ] }");
Request request = new Request.Builder()
  .url("https://api.rollful.dev/v1/roll/batch")
  .post(body)
  .addHeader("Content-Type", "application/json")
  .build();

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

import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://api.rollful.dev/v1/roll/batch',
  headers: {'Content-Type': 'application/json'},
  data: {
    rolls: [{formula: '2d6+3', advantage: 'normal', bonuses: [1], tags: ['example']}]
  }
};

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

const url = 'https://api.rollful.dev/v1/roll/batch';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"rolls":[{"formula":"2d6+3","advantage":"normal","bonuses":[1],"tags":["example"]}]}'
};

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

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{ \"rolls\": [ { \"formula\": \"2d6+3\", \"advantage\": \"normal\", \"bonuses\": [ 1 ], \"tags\": [ \"example\" ] } ] }")
val request = Request.Builder()
  .url("https://api.rollful.dev/v1/roll/batch")
  .post(body)
  .addHeader("Content-Type", "application/json")
  .build()

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

use serde_json::json;
use reqwest;

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

    let payload = json!({"rolls": (
            json!({
                "formula": "2d6+3",
                "advantage": "normal",
                "bonuses": (1),
                "tags": ("example")
            })
        )});

    let mut headers = reqwest::header::HeaderMap::new();
    headers.insert("Content-Type", "application/json".parse().unwrap());

    let client = reqwest::Client::new();
    let response = client.post(url)
        .headers(headers)
        .json(&payload)
        .send()
        .await;

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

    dbg!(results);
}

curl --request POST \
  --url https://api.rollful.dev/v1/roll/batch \
  --header 'Content-Type: application/json' \
  --data '{ "rolls": [ { "formula": "2d6+3", "advantage": "normal", "bonuses": [ 1 ], "tags": [ "example" ] } ] }'

wget --quiet \
  --method POST \
  --header 'Content-Type: application/json' \
  --body-data '{ "rolls": [ { "formula": "2d6+3", "advantage": "normal", "bonuses": [ 1 ], "tags": [ "example" ] } ] }' \
  --output-document \
  - https://api.rollful.dev/v1/roll/batch

Dice are counted across every roll in the request, not per roll.

Request Body^required

application/json

object

rolls

required

Array<object>

>= 1 items <= 20 items

object

formula

required

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

string

>= 1 characters <= 200 characters

advantage

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

string

Allowed values: normal advantage disadvantage

bonuses

Array

<= 20 items

tags

Trailing words to accept as a tag. A trailing word not listed here is a parse error.

Array<string>

<= 20 items

Responses

200

One result per requested roll.

application/json

object

rolls

required

Array<object>

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

{
  "rolls": [
    {
      "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."
  }
}

Roll several formulas in one request

Request Bodyrequired

Responses

200

Example

400

Example

413

Example

429

Example

500

Example

Request Body^required