{ "openapi": "3.1.1", "info": { "title": "Random Generator API", "version": "1.0.0", "summary": "Random numbers, dice, coins, list picks, shuffles, fair teams, dates, strings and UUIDs.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://randomgenerator.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Random numbers, dice, coins, list picks, shuffles, fair teams, dates, strings and UUIDs.", "description": "Generates random whole or decimal numbers (optionally unique), dice rolls such as 3d6+2, coin flips, picks from a list, shuffles, balanced teams (by optional skill), random dates, strings and UUID v4/v7. Uses cryptographic randomness by default; with a seed the output is reproducible so others can verify a draw.\n\nMethodology:\n- Without a seed, bytes come from the server's cryptographically secure generator (Node.js crypto.randomBytes); nothing is stored. With a seed, bytes come from SHA-256 in counter mode over the seed, so anyone can reproduce the draw with the same seed and settings.\n- Whole numbers in a range use rejection sampling (no modulo bias). Decimals use 53 random bits scaled into [min, max) and rounded to the chosen places. Unique numbers use a partial Fisher–Yates shuffle or Floyd's algorithm for huge ranges.\n- Shuffles and picks use Fisher–Yates. Teams: without skills, a random round-robin; with skills, a snake draft over a random order followed by swaps that shrink the gap between the strongest and weakest team.\n- UUID v4 has 122 random bits; UUID v7 has a 48-bit Unix millisecond timestamp and 74 random bits (RFC 9562).\n\nSeeded output is predictable by design. For passwords or keys, leave the seed empty (or use a dedicated password generator on your own device).", "tags": [ "calculators" ], "x-mcp-tool": "random_generator", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RandomGeneratorInput" }, "examples": { "example1": { "summary": "Lottery 6 of 49 (seeded)", "value": { "mode": "integers", "count": 6, "min": 1, "max": 49, "unique": true, "seed": "draw-2026-10-18" } }, "example2": { "summary": "Roll 4d6+2 five times (seeded)", "value": { "mode": "dice", "count": 5, "dice": "4d6+2", "seed": "demo" } }, "example3": { "summary": "Balanced teams by skill (seeded)", "value": { "mode": "teams", "teams": 2, "items": [ "Ana, 8", "Ben, 5", "Cleo, 9", "Dev, 4", "Eli, 6", "Fay, 7" ], "seed": "friday" } }, "example4": { "summary": "Three UUID v4 (seeded)", "value": { "mode": "uuid4", "count": 3, "seed": "example" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RandomGeneratorResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "RandomGeneratorInput": { "type": "object", "additionalProperties": false, "properties": { "mode": { "title": "Generate", "type": "string", "enum": [ "integers", "floats", "dice", "coins", "pick", "shuffle", "teams", "dates", "strings", "uuid4", "uuid7" ], "default": "integers" }, "count": { "title": "How many", "description": "Numbers, rolls, flips, picks, dates, strings or UUIDs.", "type": "integer", "minimum": 1, "maximum": 1000, "default": 10 }, "min": { "title": "Minimum", "type": "number", "minimum": -9007199254740991, "maximum": 9007199254740991, "default": 1 }, "max": { "title": "Maximum", "type": "number", "minimum": -9007199254740991, "maximum": 9007199254740991, "default": 100 }, "unique": { "title": "No repeats (numbers and picks)", "type": "boolean", "default": false }, "decimals": { "title": "Decimal places", "type": "integer", "minimum": 0, "maximum": 15, "default": 2 }, "dice": { "title": "Dice notation", "description": "NdS±M, e.g. 2d20, 4d6+2, d100.", "type": "string", "maxLength": 40, "default": "3d6" }, "items": { "title": "List (one per line; \"name, skill\" for teams)", "type": "array", "items": { "type": "string" }, "maxItems": 1000 }, "teams": { "title": "Number of teams", "type": "integer", "minimum": 2, "maximum": 50, "default": 2 }, "dateFrom": { "title": "Earliest date", "type": "string", "format": "date", "default": "2026-01-01" }, "dateTo": { "title": "Latest date", "type": "string", "format": "date", "default": "2026-12-31" }, "length": { "title": "String length", "type": "integer", "minimum": 1, "maximum": 256, "default": 16 }, "charset": { "title": "Characters", "type": "string", "enum": [ "alnum", "unambiguous", "lower", "upper", "digits", "hex", "symbols" ], "default": "alnum" }, "seed": { "title": "Seed (optional, for reproducible results)", "description": "Empty = cryptographic randomness, different every time. With a seed, the same settings always give the same result — never use seeded output for passwords or keys.", "type": "string", "maxLength": 200 }, "uuidTime": { "title": "UUID v7 timestamp (optional)", "description": "Default: now (UTC). Set it together with a seed for reproducible v7 UUIDs. Local date-time YYYY-MM-DDTHH:mm", "type": "string" } }, "required": [] }, "RandomGeneratorResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "required": [ "mode", "seeded", "values" ], "properties": { "mode": { "type": "string" }, "seeded": { "type": "boolean" }, "seed": { "type": [ "string", "null" ] }, "values": { "type": "array", "items": { "type": "string" }, "description": "Generated values as text, in order." }, "numbers": { "type": "array", "items": { "type": "number" } }, "dice": { "type": "object", "properties": { "notation": { "type": "string" }, "rolls": { "type": "array", "items": { "type": "object", "properties": { "dice": { "type": "array", "items": { "type": "integer" } }, "total": { "type": "integer" } } } }, "min": { "type": "integer" }, "max": { "type": "integer" }, "mean": { "type": "number" } } }, "heads": { "type": "integer" }, "teams": { "type": "array", "items": { "type": "object", "required": [ "team", "members" ], "properties": { "team": { "type": "integer" }, "members": { "type": "array", "items": { "type": "string" } }, "totalSkill": { "type": [ "number", "null" ] } } } }, "stats": { "type": "object", "properties": { "sum": { "type": "number" }, "mean": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" } } } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }