HTTP API & Hosted Schema

RANDSUM exposes two zero-install web surfaces at randsum.dev: an HTTP roll endpoint and the hosted games meta-schema. Both are public and CORS-enabled, so you can call them from any browser, editor, or server.

Hosted meta-schema

The @randsum/games package validates every *.randsum.json game spec against a JSON Schema. That schema is published at its declared $id:

https://randsum.dev/schemas/v1/randsum.json

It is served as application/json and is byte-identical to the source of truth in the monorepo (packages/games/randsum.json) — a build step copies it into the site and a sync test fails the build if the two ever drift.

Editor autocompletion

Until the schema lands in SchemaStore (tracked in issue #1130), reference it explicitly with a $schema key so editors like VS Code give you completion and validation while authoring a game spec:

{
  "$schema": "https://randsum.dev/schemas/v1/randsum.json",
  "name": "My Game",
  "shortcode": "mygame",
  "game_url": "https://example.com",
  "roll": {
    "dice": { "pool": { "sides": 6, "quantity": 2 } },
    "resolve": "sum"
  }
}

POST /api/roll

Evaluate any RANDSUM dice notation over HTTP. The endpoint runs the same roll() engine as @randsum/roller.

Request

POST JSON with a single notation field:

curl -X POST https://randsum.dev/api/roll \
  -H "Content-Type: application/json" \
  -d '{"notation":"4d6L"}'

Response — 200 OK

{
  "notation": "4d6L",
  "total": 12,
  "rolls": [3, 4, 5],
  "description": "Roll 4 6-sided dice; Drop lowest"
}

Field	Type	Description
notation	string	The notation that was rolled
total	number	Combined total of all rolls
rolls	number[]	Individual die values after modifiers
description	string	Human-readable description of the roll

Errors — 400 Bad Request

Invalid notation returns the roller’s own error message, plus a suggestion when a likely fix can be inferred (the same hint powered by suggestNotationFix):

curl -X POST https://randsum.dev/api/roll \
  -H "Content-Type: application/json" \
  -d '{"notation":"d6"}'

{
  "error": "Invalid dice notation: \"d6\"",
  "suggestion": "1d6"
}

Notation longer than 1000 characters is rejected before parsing, and oversized request bodies return 413 Payload Too Large.

Usage — GET /api/roll

A plain GET returns a JSON description of the contract, handy for quick discovery:

curl https://randsum.dev/api/roll

CORS

Every response includes Access-Control-Allow-Origin: *, so the endpoint is callable directly from browser front-ends.