API Docs

HTTP endpoints for creating, retrieving, and checking draws.

API Overview

Use the API to create saved draws, fetch stored results, and verify published outcomes with the same deterministic rules used across the platform.

Base URL

https://api.raffleroll.com/v1

Content Type

application/json

Common Response Codes

200 request succeeded
201 draw created
202 draw accepted and still processing
401 missing or invalid API key
404 draw not found
409 draw is not ready for verification yet
422 request payload is invalid
500 saved draw could not be verified

Draw IDs

Public draw IDs are 12-character tokens, for example 8Q4X7M2RKP2N.

Any saved draw can be viewed by anyone who has its draw ID.

Retention

API draws stay available for 1 year.

Participant Formats

Plain Labels

["alice", "bob"]

Weighted Pairs

[["alice", 2], ["bob", 1]]

Weighted Objects

[{"label": "alice", "count": 2}]

Endpoints

POST /v1/draws creates and stores a draw.
GET /v1/draws/:id returns the saved draw.
POST /v1/draws/:id/verify checks the saved result.

Authentication

Send your API key in the x-api-key header. Bearer auth is also accepted.

Need a key for a real integration? Request API access

Example Request

curl https://api.raffleroll.com/v1/draws/DRAW_ID \
  -H 'x-api-key: YOUR_KEY'

POST /v1/draws

Create a draw

Each draw request saves the raw entries, the expanded ticket list, and the final result. Participants must be sent as an ordered array. Weighted entries can be sent as duplicates, as ordered pairs, or as ordered objects with label and count.

Request

curl -X POST https://api.raffleroll.com/v1/draws \
  -H 'content-type: application/json' \
  -H 'x-api-key: YOUR_KEY' \
  -d '{
    "participants": [
      {"label": "bob", "count": 1},
      {"label": "alice", "count": 2},
      {"label": "carol", "count": 1}
    ],
    "n": 1,
    "algorithm_version": "1.0.2"
  }'

Response

{
  "id": "8Q4X7M2RKP2N",
  "kind": "api",
  "status": "finalized",
  "winner_count": 1,
  "raw_participants": [
    "{\"label\": \"bob\", \"count\": 1}",
    "{\"label\": \"alice\", \"count\": 2}",
    "{\"label\": \"carol\", \"count\": 1}"
  ],
  "participants": ["bob", "alice", "alice", "carol"],
  "canonical_participants": ["alice", "alice", "bob", "carol"],
  "participants_hash": "6f9d...",
  "seed_commit": "f0de...",
  "seed": "c219...",
  "normalized_seed": "c219...",
  "algorithm_version": "1.0.2",
  "winners": ["alice"],
  "indexes": [1],
  "drand": {
    "network": "mainnet",
    "round": 123456,
    "randomness": "88f5..."
  },
  "expires_at": "2027-03-28T11:47:00Z",
  "inserted_at": "2026-03-28T11:47:00Z"
}

GET /v1/draws/:id

Get a draw

Retrieve the saved draw details for a known 12-character draw ID, including raw entries, expanded tickets, and canonical proof order.

Request

curl https://api.raffleroll.com/v1/draws/DRAW_ID \
  -H 'x-api-key: YOUR_KEY'

Response

{
  "id": "8Q4X7M2RKP2N",
  "kind": "api",
  "status": "finalized",
  "winner_count": 1,
  "raw_participants": [
    "{\"label\": \"bob\", \"count\": 1}",
    "{\"label\": \"alice\", \"count\": 2}",
    "{\"label\": \"carol\", \"count\": 1}"
  ],
  "participants": ["bob", "alice", "alice", "carol"],
  "canonical_participants": ["alice", "alice", "bob", "carol"],
  "participants_hash": "6f9d...",
  "seed_commit": "f0de...",
  "seed": "c219...",
  "normalized_seed": "c219...",
  "algorithm_version": "1.0.2",
  "winners": ["alice"],
  "indexes": [1],
  "drand": {
    "network": "mainnet",
    "round": 123456,
    "randomness": "88f5..."
  },
  "expires_at": "2027-03-28T11:47:00Z",
  "inserted_at": "2026-03-28T11:47:00Z"
}

POST /v1/draws/:id/verify

Verify a saved result

This endpoint reruns the stored draw and checks whether the saved winners still match. It does not accept a manual participant list or seed input.

Request

curl -X POST https://api.raffleroll.com/v1/draws/DRAW_ID/verify \
  -H 'x-api-key: YOUR_KEY'

Success response

{
  "ok": true,
  "id": "8Q4X7M2RKP2N",
  "status": "finalized",
  "checked_at": "2026-03-30T12:15:00Z",
  "algorithm_version": "1.0.2",
  "winner_count": 1,
  "comparisons": {
    "participants_hash": true,
    "normalized_seed": true,
    "winners": true,
    "indexes": true
  },
  "stored": {
    "participants_hash": "6f9d...",
    "normalized_seed": "c219...",
    "winners": ["alice"],
    "indexes": [1]
  },
  "recomputed": {
    "participants_hash": "6f9d...",
    "normalized_seed": "c219...",
    "winners": ["alice"],
    "indexes": [1]
  }
}

Not ready yet

{
  "ok": false,
  "id": "8Q4X7M2RKP2N",
  "status": "pending_randomness",
  "error": "draw is not finalized",
  "retryable": true,
  "finalize_attempts": 2,
  "last_finalize_error": "The public randomness service could not be reached right now",
  "last_finalize_attempt_at": "2026-03-30T12:12:00Z",
  "next_finalize_at": "2026-03-30T12:17:00Z"
}