API reference¶

All HTTP endpoints exposed by Pollux.

UUID¶

GET /api/uuid¶

Generate a new UUIDv7.

curl http://localhost:3000/api/uuid
# 0194f1e0-abcd-7000-8000-000000000000

Voting¶

POST /api/vote¶

Submit a vote for a static or dynamic poll.

Request body:

{
  "uuid": "0194f1e0-...",
  "choice": 0
}

Response: 201 Created

GET /api/vote/:uuid¶

Get poll results. Optional query parameter ?step=N to filter by step.

curl http://localhost:3000/api/vote/0194f1e0-...?step=0

{
  "result": [
    { "choice": 0, "total": 5 },
    { "choice": 1, "total": 3 }
  ]
}

Dynamic polls¶

POST /api/dynamic/:uuid/step¶

Define choices for a step.

Request body:

{
  "step": 0,
  "choices": ["Red", "Blue", "Green"]
}

Response: 201 Created

GET /api/dynamic/:uuid/step?step=N¶

Get choices for a specific step.

curl "http://localhost:3000/api/dynamic/UUID/step?step=0"

{
  "step": 0,
  "choices": ["Red", "Blue", "Green"]
}

Quizzes¶

POST /api/quizz/:uuid/step¶

Save a quiz question definition.

Request body:

{
  "step": 0,
  "choices": ["Paris", "London", "Berlin"],
  "correct": [0, 2],
  "question": "Which cities are capitals?",
  "media": "https://example.com/image.jpg"
}

Response: 201 Created

GET /api/quizz/:uuid/step?step=N¶

Get a question definition with correct answers.

curl "http://localhost:3000/api/quizz/UUID/step?step=0"

{
  "step": 0,
  "choices": ["Paris", "London", "Berlin"],
  "question": "Which cities are capitals?",
  "correct": [0, 2],
  "timer": 0,
  "startedAt": null,
  "media": "https://example.com/image.jpg"
}

POST /api/quizz/:uuid/start¶

Start a question with a timer.

Request body:

{
  "step": 0,
  "timer": 30
}

Response:

{ "step": 0, "timer": 30, "startedAt": 1718200000000 }

POST /api/quizz/:uuid/podium¶

Broadcast the final podium to all connected clients.

Response:

{ "scores": [...] }

POST /api/quizz/:uuid/register¶

Register a player with a pseudonym.

{
  "user_id": "0194f1e0-...",
  "pseudo": "Alice"
}

Response: 201 Created

GET /api/quizz/:uuid/players¶

Get all registered players.

curl http://localhost:3000/api/quizz/UUID/players

{
  "players": [
    { "user_id": "...", "pseudo": "Alice" }
  ]
}

POST /api/quizz/vote¶

Submit a quiz answer.

Request body:

{
  "uuid": "0194f1e0-...",
  "user_id": "0194f1e0-...",
  "step": 0,
  "choices": [0, 2],
  "response_time_ms": 4500
}

Response:

{
  "score": 3,
  "total": 2,
  "correct": [0, 2],
  "correctScore": 2,
  "speedBonus": 1
}

GET /api/quizz/:uuid/scores¶

Get leaderboard or individual submissions.

Use ?user_id=UUID to get a specific player's submissions.

curl http://localhost:3000/api/quizz/UUID/scores

{
  "scores": [
    { "user_id": "...", "pseudo": "Alice", "score": 15, "total": 20 }
  ]
}

GET /api/quizz/:uuid/results?step=N¶

Get aggregated results for a step.

curl "http://localhost:3000/api/quizz/UUID/results?step=0"

Raffles¶

POST /api/raffle/:uuid/register¶

Register a player for a raffle draw. A random pseudo is auto-assigned if not provided.

Request body:

{
  "user_id": "0194f1e0-...",
  "pseudo": "Alice"
}

Response: 201 Created

{ "pseudo": "Alice" }

POST /api/raffle/:uuid/spin¶

Spin the wheel and randomly pick a winner. Requires at least 2 registered players.

Response:

{ "winnerId": "...", "winnerPseudo": "Alice" }

GET /api/raffle/:uuid/players¶

Get all registered players.

curl http://localhost:3000/api/raffle/UUID/players

{
  "players": [
    { "user_id": "...", "pseudo": "Alice" },
    { "user_id": "...", "pseudo": "Bob" }
  ]
}

GET /api/raffle/:uuid/status¶

Get the current raffle status (winner and player count).

curl http://localhost:3000/api/raffle/UUID/status

{
  "winnerId": null,
  "winnerPseudo": null,
  "playerCount": 3
}

After spinning:

{
  "winnerId": "0194f1e0-...",
  "winnerPseudo": "Alice",
  "playerCount": 3
}

Pages¶

Flush¶

POST /api/flush/:uuid¶

Delete all votes for a poll.

curl -X POST http://localhost:3000/api/flush/0194f1e0-...

Static assets¶

Error codes¶