Skip to content

Getting started

Minimal play loop against a running FastAPI instance. Examples use https://pr-api-staging.jvsassoc.com for this docs environment.

Open questions are unresolved issuances on live or recently scheduled matches (not a UTC calendar day). Use admin Live / Clone Past Match if you need a feed issuing questions while you integrate.

1. Register or log in

curl -sS -X POST 'https://pr-api-staging.jvsassoc.com/api/auth/register' \
  -H 'Content-Type: application/json' \
  -d '{
    "username":"dev-player",
    "password":"secret",
    "email":"dev@example.com",
    "first_name":"Dev"
  }'

Or POST /api/auth/login with username (username or email) + password. Save the returned api_key (plaintext once). In Swagger, open Authorize and paste it as a Bearer token.

export API_KEY='psk_…'

2. Open questions (live)

Prefer the WebSocket stream for open questions (see Live play client). REST /open remains for catch-up and quick curl checks (followed matches only):

curl -sS "https://pr-api-staging.jvsassoc.com/api/question-answers/open" \
  -H "Authorization: Bearer $API_KEY"

Each item includes question_issuance_id, choices[].identifier, seconds_remaining, and optional current_answer if this user already answered.

3. Submit (or change) an answer

curl -sS -X PUT 'https://pr-api-staging.jvsassoc.com/api/question-answers' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{
    \"question_issuance_id\": \"$ISSUANCE_ID\",
    \"selected_answer_identifier\": \"$CHOICE_ID\"
  }"

Common failures (see Swagger for full catalog):

Status Meaning
400 selected_answer_identifier not in the issuance choices
401 Missing or invalid API key
404 Unknown issuance
409 Issuance already resolved
410 Answer window expired

4. Answer history

curl -sS "https://pr-api-staging.jvsassoc.com/api/question-answers?limit=20" \
  -H "Authorization: Bearer $API_KEY"

Optional match_id filters to one internal match id (Match.id).

Players can file feedback on a resolved history row. Form catalog and POST: Report this (user feedback).