API Reference

/api/v1/raffles/{raffle_uuid}/audit

Retrieve all tamper-proof audit records for a raffle's draws, including cryptographic signatures and draw details for each prize (1st, 2nd, 3rd place).

Parameters

Parameter	Type	Description
raffle_uuid	string (UUID)	Raffle identifier

Example Request

curl https://raffaly.com/api/v1/raffles/550e8400-e29b-41d4-a716-446655440000/audit \
  -H "Accept: application/json"

Example Response (200 OK)

{
  "raffle_id": "550e8400-e29b-41d4-a716-446655440000",
  "total_draws": 3,
  "draws": [
    {
      "draw_id": "660e8400-e29b-41d4-a716-446655440001",
      "prize_name": "iPhone 15 Pro (1st Prize)",
      "drawn_at_utc": "2025-11-06T20:32:01+00:00",
      "total_entries": 142,
      "rng_seed_hash": "a1b2c3d4e5f6...",
      "winner_entry_id": "12345",
      "signature_hash": "d4e5f6a7b8c9..."
    },
    {
      "draw_id": "770e8400-e29b-41d4-a716-446655440002",
      "prize_name": "AirPods Pro (2nd Prize)",
      "drawn_at_utc": "2025-11-06T20:32:05+00:00",
      "total_entries": 141,
      "rng_seed_hash": "b2c3d4e5f6a7...",
      "winner_entry_id": "67890",
      "signature_hash": "e5f6a7b8c9d0..."
    },
    {
      "draw_id": "880e8400-e29b-41d4-a716-446655440003",
      "prize_name": "Apple Watch (3rd Prize)",
      "drawn_at_utc": "2025-11-06T20:32:09+00:00",
      "total_entries": 140,
      "rng_seed_hash": "c3d4e5f6a7b8...",
      "winner_entry_id": "54321",
      "signature_hash": "f6a7b8c9d0e1..."
    }
  ]
}

Response Headers

• ETag - MD5 hash for caching
• Cache-Control - public, max-age=3600

/api/v1/raffles/{raffle_uuid}/entries/stats

Get current entry statistics including total entries, paid entries, and free entries.

Example Request

curl https://raffaly.com/api/v1/raffles/550e8400-e29b-41d4-a716-446655440000/entries/stats \
  -H "Accept: application/json"

Example Response (200 OK)

{
  "raffle_id": "550e8400-e29b-41d4-a716-446655440000",
  "total_entries": 142,
  "paid_entries": 131,
  "free_entries": 11,
  "max_entries": 10000,
  "updated_at": "2025-11-06T20:31:55+00:00"
}

/api/v1/raffles/{raffle_uuid}/odds?entries={count}

Calculate winning probability for a given number of entries.

Parameters

Parameter	Type	Description
raffle_uuid	string (UUID)	Raffle identifier
entries	integer (query)	Number of entries to calculate odds for (min: 1)

Example Request

curl "https://raffaly.com/api/v1/raffles/550e8400-e29b-41d4-a716-446655440000/odds?entries=9" \
  -H "Accept: application/json"

Example Response (200 OK)

{
  "raffle_id": "550e8400-e29b-41d4-a716-446655440000",
  "entrant_entries": 9,
  "total_entries": 142,
  "ratio": "9 in 142",
  "probability": 0.063380,
  "as_of": "2025-11-06T20:31:55+00:00"
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "request_id": "req_abc123"
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please try again later.",
    "request_id": "req_abc123"
  }
}