Random Generator API

Every generation endpoint draws from a hash chain — a server-side row carrying a serverSeed, its public serverHash, and the current cursor/nonce. Each draw bumps the nonce and is recorded into /api/listOutcomes. Chains are addressed by a (api key, clientSeed) pair.

How chains are scoped

• Per-key chains. Every live api key (pk_live_*) has its own private chain for each clientSeed it uses. Draws made with key A never advance key B's chain, even when both use clientSeed=blackjack-2026. The two are independent hash streams from the moment the chain is created.
• Anonymous chain. Calls without an api key share a single anonymous chain per clientSeed. It's public by design — any anonymous caller can draw from it and any caller can rotate it. Don't use the anon chain for application state you don't want anyone else to influence; create a key.
• Test keys. pk_test_* keys bypass the live chain entirely on every random-generating endpoint (floats, ints, shuffle, pick, bytes, dice, gaussian): outcomes are deterministic per (account, clientSeed), stored as test rows in a per-user fixture space, never advance live seed_state, and never count toward live usage stats or fire webhooks. Responses are tagged mode: "test".

What spans all chains

Verification and lookup are intentionally global — anyone with a serverHash, a shortId, or a clientSeed can audit any outcome regardless of which chain produced it:

• /api/verifyServerHash scans every chain (anon + every key) for the given clientSeed and returns a match if any chain holds that serverHash.
• /api/listOutcomes, /api/outcome, and /o/:id permalinks return outcomes from any chain — the chain identity is internal and not part of the public outcome payload.

Practical guidance

• Each api key + clientSeed pair is a fresh chain. The first draw for a new pair lazily creates the chain; you don't manage it.
• Rotating one chain (see /api/rotate) reveals only that chain's prior serverSeed — other chains keep theirs secret.
• If you need parallel uncorrelated chains under one account (e.g. one per game table), use distinct clientSeed values, the same api key, and rotate them independently.

Generate cryptographically verifiable random floating-point numbers in the range [0, 1).

Query Parameters

Example Request

curl "https://api.provable.io/api/floats?clientSeed=my-app&count=5"

const res = await fetch("https://api.provable.io/api/floats?clientSeed=my-app&count=5");
const data = await res.json();
console.log(data.outcome);

import requests

res = requests.get("https://api.provable.io/api/floats?clientSeed=my-app&count=5")
data = res.json()
print(data["outcome"])

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    res, _ := http.Get("https://api.provable.io/api/floats?clientSeed=my-app&count=5")
    defer res.Body.Close()
    var data map[string]interface{}
    json.NewDecoder(res.Body).Decode(&data)
    fmt.Println(data["outcome"])
}

Example Response

{
  "outcome": [0.4823, 0.1175, 0.9034, 0.5567, 0.2218],
  "clientSeed": "my-app",
  "serverHash": "9f86d081884c7d65...",
  "nonce": 0,
  "cursor": 5,
  "count": 5,
  "created": 1716566400000,
  "shortId": "k7Qm2A9bXz",
  "permalink": "https://provable.io/o/k7Qm2A9bXz"
}

The shortId is a stable public ID. Hand anyone the permalink to let them view and re-verify this outcome on a no-auth page. See /o/:id below.

Generate cryptographically verifiable random integers within a custom range.

Query Parameters

Example Request

curl "https://api.provable.io/api/ints?clientSeed=my-app&count=5&min=1&max=100"

const res = await fetch("https://api.provable.io/api/ints?clientSeed=my-app&count=5&min=1&max=100");
const data = await res.json();
console.log(data.outcome);

import requests

res = requests.get("https://api.provable.io/api/ints?clientSeed=my-app&count=5&min=1&max=100")
data = res.json()
print(data["outcome"])

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    res, _ := http.Get("https://api.provable.io/api/ints?clientSeed=my-app&count=5&min=1&max=100")
    defer res.Body.Close()
    var data map[string]interface{}
    json.NewDecoder(res.Body).Decode(&data)
    fmt.Println(data["outcome"])
}

Example Response

{
  "outcome": [42, 87, 13, 65, 29],
  "clientSeed": "my-app",
  "serverHash": "9f86d081884c7d65...",
  "nonce": 0,
  "cursor": 5,
  "count": 5,
  "min": 1,
  "max": 100,
  "created": 1716566400000,
  "shortId": "k7Qm2A9bXz",
  "permalink": "https://provable.io/o/k7Qm2A9bXz"
}

Return a uniformly fair shuffle of a caller-supplied array. The same clientSeed/cursor/nonce always yields the same permutation, so the result is fully verifiable.

Query Parameters

Example Request

curl "https://api.provable.io/api/shuffle?clientSeed=my-app&items=%5B%22a%22%2C%22b%22%2C%22c%22%2C%22d%22%5D"

const items = ["a", "b", "c", "d"];
const url = `https://api.provable.io/api/shuffle?clientSeed=my-app&items=${encodeURIComponent(JSON.stringify(items))}`;
const res = await fetch(url);
const data = await res.json();
console.log(data.outcome);

import json, requests

items = ["a", "b", "c", "d"]
res = requests.get("https://api.provable.io/api/shuffle", params={"clientSeed": "my-app", "items": json.dumps(items)})
print(res.json()["outcome"])

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "net/url"
)

func main() {
    items, _ := json.Marshal([]string{"a", "b", "c", "d"})
    q := url.Values{"clientSeed": {"my-app"}, "items": {string(items)}}
    res, _ := http.Get("https://api.provable.io/api/shuffle?" + q.Encode())
    defer res.Body.Close()
    var data map[string]interface{}
    json.NewDecoder(res.Body).Decode(&data)
    fmt.Println(data["outcome"])
}

Example Response

{
  "outcome": ["c", "a", "d", "b"],
  "clientSeed": "my-app",
  "serverHash": "9f86d081884c7d65...",
  "nonce": 0,
  "cursor": 0,
  "count": 4,
  "endpoint": "shuffle",
  "created": 1716566400000
}

Pick one item from a list, optionally with per-item weights. Returns the chosen item and its zero-based index.

Query Parameters

Example Request

curl "https://api.provable.io/api/pick?clientSeed=loot-roll&items=common,rare,legendary&weights=70,25,5"

const params = new URLSearchParams({
  clientSeed: "loot-roll",
  items: JSON.stringify(["common", "rare", "legendary"]),
  weights: JSON.stringify([70, 25, 5]),
});
const res = await fetch(`https://api.provable.io/api/pick?${params}`);
const data = await res.json();
console.log(data.outcome, data.index);

import json, requests

res = requests.get("https://api.provable.io/api/pick", params={
    "clientSeed": "loot-roll",
    "items": json.dumps(["common", "rare", "legendary"]),
    "weights": json.dumps([70, 25, 5]),
})
data = res.json()
print(data["outcome"], data["index"])

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "net/url"
)

func main() {
    items, _ := json.Marshal([]string{"common", "rare", "legendary"})
    weights, _ := json.Marshal([]int{70, 25, 5})
    q := url.Values{"clientSeed": {"loot-roll"}, "items": {string(items)}, "weights": {string(weights)}}
    res, _ := http.Get("https://api.provable.io/api/pick?" + q.Encode())
    defer res.Body.Close()
    var data map[string]interface{}
    json.NewDecoder(res.Body).Decode(&data)
    fmt.Println(data["outcome"], data["index"])
}

Example Response

{
  "outcome": "legendary",
  "index": 2,
  "clientSeed": "loot-roll",
  "serverHash": "9f86d081884c7d65...",
  "nonce": 0,
  "cursor": 0,
  "count": 1,
  "weights": [70, 25, 5],
  "endpoint": "pick",
  "created": 1716566400000
}

Return count random bytes encoded as hex (default) or base64. Useful for tokens, salts, and key material.

Query Parameters

Example Request

curl "https://api.provable.io/api/bytes?clientSeed=my-app&count=16&encoding=hex"

const res = await fetch("https://api.provable.io/api/bytes?clientSeed=my-app&count=16&encoding=hex");
const data = await res.json();
console.log(data.outcome);

import requests

res = requests.get("https://api.provable.io/api/bytes?clientSeed=my-app&count=16&encoding=hex")
print(res.json()["outcome"])

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    res, _ := http.Get("https://api.provable.io/api/bytes?clientSeed=my-app&count=16&encoding=hex")
    defer res.Body.Close()
    var data map[string]interface{}
    json.NewDecoder(res.Body).Decode(&data)
    fmt.Println(data["outcome"])
}

Example Response

{
  "outcome": "3f0a8b7d1c4e6f209a8c5b4d2e1f0a8b",
  "clientSeed": "my-app",
  "serverHash": "9f86d081884c7d65...",
  "nonce": 0,
  "cursor": 0,
  "count": 16,
  "encoding": "hex",
  "endpoint": "bytes",
  "created": 1716566400000
}

Roll dice using standard tabletop notation. Returns the individual rolls, the modifier, and the total.

Query Parameters

Example Request

curl "https://api.provable.io/api/dice?clientSeed=tabletop&notation=3d6%2B2"

const res = await fetch("https://api.provable.io/api/dice?clientSeed=tabletop&notation=" + encodeURIComponent("3d6+2"));
const data = await res.json();
console.log(data.outcome);

import requests

res = requests.get("https://api.provable.io/api/dice", params={"clientSeed": "tabletop", "notation": "3d6+2"})
print(res.json()["outcome"])

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "net/url"
)

func main() {
    q := url.Values{"clientSeed": {"tabletop"}, "notation": {"3d6+2"}}
    res, _ := http.Get("https://api.provable.io/api/dice?" + q.Encode())
    defer res.Body.Close()
    var data map[string]interface{}
    json.NewDecoder(res.Body).Decode(&data)
    fmt.Println(data["outcome"])
}

Example Response

{
  "outcome": { "notation": "3d6+2", "rolls": [4, 6, 3], "modifier": 2, "total": 15 },
  "clientSeed": "tabletop",
  "serverHash": "9f86d081884c7d65...",
  "nonce": 0,
  "cursor": 0,
  "count": 3,
  "sides": 6,
  "modifier": 2,
  "endpoint": "dice",
  "created": 1716566400000
}

Draw samples from a normal, exponential, or poisson distribution with caller-supplied parameters.

Query Parameters

Example Request

curl "https://api.provable.io/api/gaussian?clientSeed=stats&distribution=normal&count=5&mean=0&stddev=1"

const res = await fetch("https://api.provable.io/api/gaussian?clientSeed=stats&distribution=normal&count=5&mean=0&stddev=1");
const data = await res.json();
console.log(data.outcome);

import requests

res = requests.get("https://api.provable.io/api/gaussian", params={
    "clientSeed": "stats", "distribution": "normal", "count": 5, "mean": 0, "stddev": 1
})
print(res.json()["outcome"])

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    res, _ := http.Get("https://api.provable.io/api/gaussian?clientSeed=stats&distribution=normal&count=5&mean=0&stddev=1")
    defer res.Body.Close()
    var data map[string]interface{}
    json.NewDecoder(res.Body).Decode(&data)
    fmt.Println(data["outcome"])
}

Example Response

{
  "outcome": [-0.42, 1.05, 0.18, -1.21, 0.66],
  "clientSeed": "stats",
  "serverHash": "9f86d081884c7d65...",
  "nonce": 0,
  "cursor": 0,
  "count": 5,
  "distribution": "normal",
  "mean": 0,
  "stddev": 1,
  "endpoint": "gaussian",
  "created": 1716566400000
}

Open a long-lived Server-Sent Events connection that emits one verifiable outcome per interval, indefinitely (up to a 10 minute cap). Use it for live games, simulators, and dashboards that need a steady drip of randomness without paying the per-request HTTP overhead.

Response type differs from the other endpoints. Instead of a single JSON body the server holds the connection open and writes a stream of text/event-stream frames. Each frame is a self-contained event: outcome message whose data: field is a full JSON outcome (identical shape to the matching non-streaming endpoint, plus an outcomeId field of clientSeed:cursor:nonce). Every emitted outcome verifies independently via /api/verifyServerHash.

Query Parameters

Lifecycle

• The first outcome is emitted immediately after the connection is accepted (it also doubles as parameter validation — bad inputs come back as a normal 400, no stream is opened).
• Heartbeat comments (: heartbeat …) are sent every ~15 seconds so proxies don't time the connection out.
• Each emitted outcome counts as one billed call against your account (live keys only). Anonymous and test-mode streams are not metered but still subject to the per-IP anonymous rate limit on the initial connection.
• The server caps any single connection at 10 minutes. When the cap (or quota) is reached the server emits a final event: done frame and closes — reconnect to keep streaming.
• Every event: outcome frame includes an id: line. On a transient drop, vanilla EventSource auto-reconnects and replays it as Last-Event-ID; raw fetch clients can pass the same value as a ?lastEventId= query parameter. Either way the server resumes strictly after the last id you saw on that clientSeed, so reconnects don't double-count or skip — and skipped duplicates aren't billed.
• Closing the connection (e.g. EventSource.close()) tears down the timers cleanly on the server, so no further outcomes are generated or billed.

Example Request

curl -N "https://api.provable.io/api/stream?endpoint=floats&clientSeed=my-app&intervalMs=1000"

const url = "https://api.provable.io/api/stream?endpoint=floats&clientSeed=my-app&intervalMs=1000";
const es = new EventSource(url);
es.addEventListener("outcome", (e) => {
    const o = JSON.parse(e.data);
    console.log(o.outcomeId, o.outcome);
});
es.addEventListener("done", (e) => {
    console.log("stream closed:", JSON.parse(e.data));
    es.close();
});
es.onerror = () => es.close();

Example Stream

id: my-app:0:0
event: outcome
data: {"outcome":[0.4823],"clientSeed":"my-app","serverHash":"9f86d0...","nonce":0,"cursor":0,"count":1,"endpoint":"floats","created":1716566400000,"outcomeId":"my-app:0:0"}

: heartbeat 1716566415000

id: my-app:0:1
event: outcome
data: {"outcome":[0.1175],"clientSeed":"my-app","serverHash":"9f86d0...","nonce":1,"cursor":0,"count":1,"endpoint":"floats","created":1716566401000,"outcomeId":"my-app:0:1"}

event: done
data: {"reason":"max_duration","count":600,"durationMs":600000}

For a full worked example see Streaming outcomes in real time.

Run up to 50 independent draws across any of the random-generating endpoints in a single HTTP round trip. Each draw uses its own clientSeed/cursor/nonce, so every result is independently verifiable via /api/verifyServerHash and has its own shortId/permalink.

Request Body

Behavior

• Per-draw error isolation. A failing draw produces { "ok": false, "error": "…" } in its slot — it does not abort the rest of the batch. Successful draws still persist their outcomes.
• Quota. Authenticated calls bump usage counters once per successful draw (failures don't count). If the daily quota is hit mid-batch, remaining draws short-circuit with { "ok": false, "error": "…", "code": "quota_exceeded" }.
• Order. results is in the same order as draws.
• Idempotency. A single Idempotency-Key header covers the whole batch — replays return the identical results array and do not re-run any draw.

Example Request

curl -X POST "https://api.provable.io/api/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "draws": [
      { "endpoint": "ints", "params": { "clientSeed": "chest-1", "min": 1, "max": 100 } },
      { "endpoint": "ints", "params": { "clientSeed": "chest-2", "min": 1, "max": 100 } },
      { "endpoint": "pick", "params": { "clientSeed": "loot-3", "items": ["common","rare","legendary"], "weights": [70,25,5] } }
    ]
  }'

const res = await fetch("https://api.provable.io/api/batch", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    draws: [
      { endpoint: "ints", params: { clientSeed: "chest-1", min: 1, max: 100 } },
      { endpoint: "ints", params: { clientSeed: "chest-2", min: 1, max: 100 } },
      { endpoint: "pick", params: { clientSeed: "loot-3", items: ["common","rare","legendary"], weights: [70,25,5] } },
    ],
  }),
});
const data = await res.json();
for (const r of data.results) console.log(r);

import requests

res = requests.post("https://api.provable.io/api/batch", json={
    "draws": [
        {"endpoint": "ints", "params": {"clientSeed": "chest-1", "min": 1, "max": 100}},
        {"endpoint": "ints", "params": {"clientSeed": "chest-2", "min": 1, "max": 100}},
        {"endpoint": "pick", "params": {"clientSeed": "loot-3", "items": ["common","rare","legendary"], "weights": [70,25,5]}},
    ],
})
for r in res.json()["results"]:
    print(r)

Example Response

{
  "results": [
    { "ok": true, "outcome": { "outcome": [42], "clientSeed": "chest-1", "serverHash": "9f86d081...", "nonce": 0, "cursor": 0, "count": 1, "min": 1, "max": 100, "endpoint": "ints", "created": 1716566400000, "shortId": "k7Qm2A9bXz", "permalink": "https://provable.io/o/k7Qm2A9bXz" } },
    { "ok": true, "outcome": { "outcome": [73], "clientSeed": "chest-2", "serverHash": "5e3b...", "nonce": 0, "cursor": 0, "count": 1, "min": 1, "max": 100, "endpoint": "ints", "created": 1716566400000, "shortId": "9aB2c3D4eF", "permalink": "https://provable.io/o/9aB2c3D4eF" } },
    { "ok": true, "outcome": { "outcome": "legendary", "index": 2, "clientSeed": "loot-3", "serverHash": "0a1b...", "nonce": 0, "cursor": 0, "count": 1, "weights": [70, 25, 5], "endpoint": "pick", "created": 1716566400000, "shortId": "P9q8R7s6T5", "permalink": "https://provable.io/o/P9q8R7s6T5" } }
  ]
}

Reveal the current serverSeed for a chain and rotate to a fresh one. This is the only endpoint that exposes the secret serverSeed — every other endpoint surfaces only the public serverHash. After rotation, cursor and nonce reset to 0 on the new serverHash.

Which chain gets rotated

• Authenticated call (pk_live_*) — rotates only that key's chain for the given clientSeed. Other keys' chains and the anonymous chain are untouched.
• Anonymous call (no x-api-key) — rotates the shared anonymous chain. There's no owner, so any caller can rotate it; treat the revealed serverSeed as public.
• Test keys (pk_test_*) — rejected 403 (code: "test_mode_forbidden"). Test mode never reveals secrets, and forbidding rotate prevents a test key from exposing the public anon chain's serverSeed.

Request Body

Example Request

curl -X POST https://api.provable.io/api/rotate \
  -H "x-api-key: pk_live_..." \
  -H "content-type: application/json" \
  -d '{"clientSeed":"blackjack-2026"}'

const res = await fetch("https://api.provable.io/api/rotate", {
  method: "POST",
  headers: {
    "x-api-key": "pk_live_...",
    "content-type": "application/json",
  },
  body: JSON.stringify({ clientSeed: "blackjack-2026" }),
});
const { revealed, next } = await res.json();
// verify: sha256(revealed.serverSeed) === revealed.serverHash

import requests

res = requests.post(
    "https://api.provable.io/api/rotate",
    headers={"x-api-key": "pk_live_..."},
    json={"clientSeed": "blackjack-2026"},
)
print(res.json())

package main

import (
    "bytes"
    "net/http"
)

func main() {
    body := bytes.NewBufferString(`{"clientSeed":"blackjack-2026"}`)
    req, _ := http.NewRequest("POST", "https://api.provable.io/api/rotate", body)
    req.Header.Set("x-api-key", "pk_live_...")
    req.Header.Set("content-type", "application/json")
    http.DefaultClient.Do(req)
}

Example Response

{
  "clientSeed": "blackjack-2026",
  "revealed": {
    "serverSeed": "b1946ac92492d2347c6235b4d2611184a3a6f3c1e5c1c4d8e6b7f1a2c3d4e5f6",
    "serverHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "cursor": 7,
    "nonce": 3
  },
  "next": {
    "serverHash": "a3b1c5d7e9f1a3b5c7d9e1f3a5b7c9d1e3f5a7b9c1d3e5f7a9b1c3d5e7f9a1b3",
    "cursor": 0,
    "nonce": 0,
    "rotatedAt": 1716566400000
  }
}

Verifying the reveal

To audit fairness, recompute sha256(revealed.serverSeed) and check it matches revealed.serverHash. That hash is what was published with every outcome on this chain since the previous rotate (or since the chain was created), so any /o/:id permalink referencing it can now be re-derived from the revealed seed.

Errors

Verify that a server hash matches our records for a given client seed. Returns true if the hash is authentic.

Query Parameters

Example Request

curl "https://api.provable.io/api/verifyServerHash?clientSeed=my-app&serverHash=9f86d081884c7d65..."

const res = await fetch("https://api.provable.io/api/verifyServerHash?clientSeed=my-app&serverHash=9f86d081884c7d65...");
const valid = await res.json();
console.log(valid);

import requests

res = requests.get("https://api.provable.io/api/verifyServerHash?clientSeed=my-app&serverHash=9f86d081884c7d65...")
print(res.json())

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    res, _ := http.Get("https://api.provable.io/api/verifyServerHash?clientSeed=my-app&serverHash=9f86d081884c7d65...")
    defer res.Body.Close()
    var valid bool
    json.NewDecoder(res.Body).Decode(&valid)
    fmt.Println(valid)
}

Example Response

{
  "verified": true,
  "clientSeed": "my-app",
  "serverHash": "9f86d081884c7d65...",
  "outcomes": [
    {
      "shortId": "k7Qm2A9bXz",
      "permalink": "https://provable.io/o/k7Qm2A9bXz",
      "endpoint": "ints",
      "cursor": 5,
      "nonce": 0,
      "created": 1716566400000
    }
  ]
}

When verified, the response also lists permalinks for any recorded outcomes under that (clientSeed, serverHash) pair — convenient for handing a third party a single link.

List all recorded outcomes for a given client seed, in chronological order.

Query Parameters

Example Request

curl "https://api.provable.io/api/listOutcomes?clientSeed=my-app"

const res = await fetch("https://api.provable.io/api/listOutcomes?clientSeed=my-app");
const outcomes = await res.json();
console.log(outcomes);

import requests

res = requests.get("https://api.provable.io/api/listOutcomes?clientSeed=my-app")
print(res.json())

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    res, _ := http.Get("https://api.provable.io/api/listOutcomes?clientSeed=my-app")
    defer res.Body.Close()
    var outcomes []map[string]interface{}
    json.NewDecoder(res.Body).Decode(&outcomes)
    fmt.Println(outcomes)
}

Example Response

[
  {
    "outcome": [42, 87, 13, 65, 29],
    "clientSeed": "my-app",
    "serverHash": "9f86d081884c7d65...",
    "nonce": 0,
    "cursor": 5,
    "created": 1716566400000,
    "shortId": "k7Qm2A9bXz",
    "permalink": "https://provable.io/o/k7Qm2A9bXz"
  }
]

Public, no-auth HTML page for a recorded outcome. Anyone with the shortId can open it to view the endpoint, parameters, client seed, server hash, the generated values, and a server-side Verified ✓ / Mismatch ✗ badge. Includes og:image / og:title so links unfurl in Slack, Discord, and X.

Path Parameters

Example

https://provable.io/o/k7Qm2A9bXz

Unknown IDs return 404. The page also links into /verify so a skeptical reader can independently reproduce the hash.

Stronger fairness guarantee than the one-shot /api/floats and /api/ints. We generate a fresh server seed, publish its serverHash and a commitId, and hold the seed secret. You then submit your client seed to /api/reveal — because the hash was published before you committed your seed, we can't have picked our seed in response to yours. Default TTL is 10 minutes.

Example Request

curl -X POST "https://api.provable.io/api/commit"

const res = await fetch("https://api.provable.io/api/commit", { method: "POST" });
const { commitId, serverHash, expiresAt } = await res.json();

import requests

res = requests.post("https://api.provable.io/api/commit")
print(res.json())

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    res, _ := http.Post("https://api.provable.io/api/commit", "", nil)
    defer res.Body.Close()
    var data map[string]interface{}
    json.NewDecoder(res.Body).Decode(&data)
    fmt.Println(data)
}

Example Response

{
  "commitId": "8c3d7b9e-1f2a-4c5d-9e8f-7a6b5c4d3e2f",
  "serverHash": "9f86d081884c7d65...",
  "expiresAt": 1716567000000
}

Submit your clientSeed and the generation parameters against a commitId from /api/commit. We mark the commit revealed (single-use), run the generation against the committed server seed, persist the outcome, and return the revealed serverSeed for independent verification.

Request Body

Errors

Example Request

curl -X POST "https://api.provable.io/api/reveal" \
  -H "Content-Type: application/json" \
  -d '{"commitId":"8c3d7b9e-...","clientSeed":"my-app","endpoint":"ints","params":{"count":5,"min":1,"max":100}}'

const commitId = "8c3d7b9e-...";
const res = await fetch("https://api.provable.io/api/reveal", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    commitId, clientSeed: "my-app",
    endpoint: "ints", params: { count: 5, min: 1, max: 100 }
  })
});
const data = await res.json();
console.log(data);

import requests

commit_id = "8c3d7b9e-..."
res = requests.post("https://api.provable.io/api/reveal", json={
  "commitId": commit_id,
  "clientSeed": "my-app",
  "endpoint": "ints",
  "params": {"count": 5, "min": 1, "max": 100}
})
print(res.json())

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]interface{}{
        "commitId":   "8c3d7b9e-...",
        "clientSeed": "my-app",
        "endpoint":   "ints",
        "params":     map[string]interface{}{"count": 5, "min": 1, "max": 100},
    })
    res, _ := http.Post("https://api.provable.io/api/reveal", "application/json", bytes.NewReader(body))
    defer res.Body.Close()
    var data map[string]interface{}
    json.NewDecoder(res.Body).Decode(&data)
    fmt.Println(data)
}

Example Response

{
  "outcome": [42, 87, 13, 65, 29],
  "clientSeed": "my-app",
  "serverHash": "9f86d081884c7d65...",
  "serverSeed": "b1946ac92492d2347c6235b4d2611184...",
  "nonce": 0,
  "cursor": 0,
  "count": 5,
  "min": 1,
  "max": 100,
  "endpoint": "ints",
  "commitId": "8c3d7b9e-1f2a-4c5d-9e8f-7a6b5c4d3e2f",
  "created": 1716566400000
}

Service health, version, and uptime. Returns 503 when the database is unreachable.

Example Request

curl "https://api.provable.io/api/health"

const res = await fetch("https://api.provable.io/api/health");
const data = await res.json();
console.log(data);

import requests

res = requests.get("https://api.provable.io/api/health")
print(res.json())

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    res, _ := http.Get("https://api.provable.io/api/health")
    defer res.Body.Close()
    var data map[string]interface{}
    json.NewDecoder(res.Body).Decode(&data)
    fmt.Println(data)
}

Example Response

{
  "status": "ok",
  "version": "1.0.0",
  "uptime": 12345
}

Get the published Merkle root for a UTC day.

Path Parameters

Example Request

curl "https://api.provable.io/api/merkle/2026-05-23"

Example Response

{
  "date": "2026-05-23",
  "root": "a3f1c2...e7",
  "leafCount": 14238,
  "treeHeight": 14,
  "publishedAt": 1716595500000
}

Get an inclusion proof for a single outcome inside a published daily tree.

Path Parameters

Example Request

curl "https://api.provable.io/api/merkle/2026-05-23/proof/my-app:0:0"

Example Response

{
  "date": "2026-05-23",
  "outcomeId": "my-app:0:0",
  "leaf": {
    "outcomeId": "my-app:0:0",
    "serverHash": "9f86d081884c7d65...",
    "clientSeed": "my-app",
    "timestamp": 1716566400000,
    "canonical": "my-app:0:0|9f86d081884c7d65...|my-app|1716566400000",
    "hash": "5f4e3d..."
  },
  "index": 0,
  "leafCount": 14238,
  "treeHeight": 14,
  "root": "a3f1c2...e7",
  "publishedAt": 1716595500000,
  "siblings": [
    { "position": "right", "hash": "2bcd..." },
    { "position": "left",  "hash": "9876..." }
  ]
}

Paste the response into the verifier widget on /transparency to confirm inclusion client-side.