All endpoints expect and return application/json.
Base URL: /api/v1
If the frontend sends bad data, the backend will return a 400 or 404 status code with this standard structure so the frontend knows exactly what went wrong.
{
"success": false,
"error": "INVALID_PIN",
"message": "The room PIN 4921 does not exist or voting has already closed."
}Endpoint: POST /rooms
Description: Initializes a new voting lobby.
Request Body:
{
"host_id": "uuid-string",
"mode": "DISCOVERY", // or "CUSTOM"
"theme": "restaurant", // only if DISCOVERY
"radius": 5000 // only if DISCOVERY
}Response (201 Created):
{
"room_id": "uuid-string",
"pin": "4921",
"status": "CONFIGURING"
}Endpoint: POST /rooms/:pin/constraints
Description: Participants submit their anonymous budget limits.
Request Body:
{
"participant_id": "uuid-string",
"max_price_level": 2 // 1 to 4
}Response (200 OK):
{
"success": true,
"message": "Constraint locked."
}Endpoint: POST /rooms/:pin/suggestions
Description: Participants submit strings for Custom Mode.
Request Body:
{
"participant_id": "uuid-string",
"suggestion": "John's House"
}Response (200 OK):
{
"success": true
}Endpoint: POST /rooms/:pin/start-voting
Description: The Host closes the suggestion phase. The backend automatically runs the Levenshtein Distance Algorithm to invisibly merge duplicate strings (e.g. "Johns House" and "John's House") before distributing the final list of cards via WebSockets.
Request Body:
{
"host_id": "uuid-string"
}Response (200 OK):
{
"success": true
}Endpoint: POST /rooms/:pin/votes
Description: After swiping all cards, the client sends the final rankings.
Request Body:
{
"participant_id": "uuid-string",
"rankings": [
{ "option_id": "uuid-1", "score": 1 }, // Swiped Right (Approve)
{ "option_id": "uuid-2", "score": -1 }, // Swiped Left (Pass)
{ "option_id": "uuid-3", "score": -100 } // Middle Button (VETO)
]
}Response (200 OK):
{
"success": true,
"message": "Votes recorded safely."
}Endpoint: POST /rooms/:pin/feedback
Description: Updates the proprietary analytics table.
Request Body:
{
"participant_id": "uuid-string",
"option_id": "uuid-string",
"satisfaction_score": 4,
"price_accuracy_score": 3
}Response (200 OK):
{
"success": true
}Endpoint: POST /rooms/:pin/force-resolve
Description: The Host forces the algorithm to run early if a participant goes AFK.
Request Body:
{
"host_id": "uuid-string"
}Response (200 OK):
{
"success": true,
"message": "Algorithm triggered manually."
}