Stavajte na Voxpla API

Rýchly štart

1. Vo Voxpla otvorte Nastavenia a potom API kľúče (vlastník a administrátor).
2. Vytvorte kľúč, zvoľte oprávnenia a skopírujte ho. Zobrazí sa iba raz.
3. Posielajte ho v hlavičke Authorization pri každej požiadavke.
4. Načítajte popis OpenAPI do Postmanu, Insomnie alebo generátora kódu.

curl https://voxpla.eu/api/v1/key \
  -H "Authorization: Bearer vx_live_..."

Overenie

Každá požiadavka potrebuje hlavičku Authorization: Bearer a za ňou kľúč. Kľúče začínajú na vx_live_ (mimo produkcie vx_test_). Voxpla si ukladá len odtlačok kľúča a jeho prvé znaky na zobrazenie. Stratený kľúč sa nedá obnoviť: vytvorte nový a starý zrušte.

Authorization: Bearer vx_live_3kQ9...

• Chýbajúci, neznámy, expirovaný alebo zrušený kľúč vráti 401.
• Keď plán organizácie API už neobsahuje, kľúče vracajú 402 plan_required.
• API neprijíma prihlásenie z prehliadača a kľúče nefungujú vo webovej aplikácii.
• Každé volanie, ktoré mení dáta, sa zapíše do auditného logu spolu s kľúčom, ktorý ho urobil.

Oprávnenia

Čítať môže každý kľúč. Ďalšie oprávnenia dajte kľúču len vtedy, keď ich integrácia potrebuje.

read

Zoznamy a detail eventov, sekcií, otázok, ankiet, výsledkov, analytiky a exporty CSV.

write

Vytváranie a úprava eventov, zmena ich stavu, vytváranie, spúšťanie a zatváranie ankiet.

moderate

Moderovanie otázok: schválenie, skrytie, zvýraznenie, označenie ako zodpovedanej, pripnutie, archivácia a zmazanie.

Volanie mimo oprávnení kľúča vráti 403 insufficient_scope.

Limity požiadaviek

Každý kľúč môže poslať 600 požiadaviek za minútu. Nad limitom API odpovie 429 rate_limited s hlavičkou Retry-After v sekundách. Počkajte uvedený čas a skúste to znova.

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{"error":"rate_limited","retryAfter":12}

Stránkovanie

Zoznamy vracajú items a next_cursor. Parametrom limit si vypýtajte najviac 100 položiek (predvolene 25) a hodnotu next_cursor pošlite ako cursor, aby ste dostali ďalšiu stránku. Na poslednej stránke je next_cursor null. Kurzory sú nepriehľadné, neskladajte ich sami.

curl "https://voxpla.eu/api/v1/events?limit=100&cursor=djE6Y2x4..." \
  -H "Authorization: Bearer $VOXPLA_API_KEY"

{ "items": [ ... ], "next_cursor": null }

Chyby

Chyby sú objekty JSON so stabilným kódom v poli error. Logiku stavajte na kóde, nie na textovom popise HTTP stavu.

400 invalid

Telo požiadavky alebo parameter je neplatný; issues uvádza konkrétne polia.

401 invalid_api_key

Kľúč chýba, je neznámy alebo zrušený (pri expirovanom kľúči api_key_expired).

402 plan_required

Plán organizácie neobsahuje API.

403 insufficient_scope

Kľúč nemá oprávnenie, ktoré toto volanie potrebuje.

404 not_found

Objekt vo vašej organizácii neexistuje.

429 rate_limited

Priveľa požiadaviek; počkajte počet sekúnd z hlavičky Retry-After.

Endpointy

Všetky cesty sú relatívne k adrese https://voxpla.eu/api/v1

• GET/keyread

  Volajúci kľúč, jeho oprávnenia a organizácia.

• GET/eventsread

  Eventy vašej organizácie od najnovších, voliteľne podľa stavu.

• POST/eventswrite

  Vytvorí event s jednou sekciou. Kód na pripojenie sa vygeneruje.

• GET/events/{id}read

  Jeden event s kódom na pripojenie, odkazom pre účastníkov a nastaveniami.

• PATCH/events/{id}write

  Zmení názov, čas, časové pásmo, jazyk alebo nastavenia.

• POST/events/{id}/statuswrite

  Prepne event na koncept, živý, ukončený alebo archivovaný.

• GET/events/{id}/sessionsread

  Sekcie eventu (miestnosti, bloky programu).

• GET/sessions/{id}/questionsread

  Otázky sekcie s hlasmi a odpoveďami, voliteľne podľa stavu.

• POST/questions/{id}/actionsmoderate

  Schváli, skryje, zvýrazní, zodpovie, pripne, archivuje alebo zmaže otázku.

• GET/sessions/{id}/pollsread

  Ankety sekcie v ich poradí.

• POST/sessions/{id}/pollswrite

  Vytvorí anketu, slovný mrak, hodnotenie, kvízovú otázku alebo iný typ ankety.

• POST/polls/{id}/activatewrite

  Spustí anketu. Bežiaca anketa sekcie sa zatvorí.

• POST/polls/{id}/closewrite

  Zatvorí anketu.

• GET/polls/{id}/resultsread

  Agregované výsledky ankety.

• GET/events/{id}/analyticsread

  Účastníci, zapojenie, časová os, najlepšie otázky a výsledky ankiet.

• GET/events/{id}/export.csvread

  Export CSV otázok, ankiet, účastníkov alebo odpovedí z dotazníka.

Odpovede obsahujú to, čo vidí moderátor. Anonymní účastníci zostávajú anonymní: žiadna odpoveď neobsahuje identitu účastníkov, tokeny ani odkazy na projekciu.

Webhooky

Namiesto opakovaného dopytovania API nechajte Voxpla, nech sa ozve vám. Webhook nastavíte v Nastaveniach v časti Integrácie pre event.started, question.approved, poll.closed a event.ended.

• Každé doručenie je HTTPS POST podpísaný v hlavičke X-Voxpla-Signature (HMAC-SHA256 z časovej pečiatky a surového tela).
• Odmietnite doručenia staršie ako 5 minút a podľa X-Voxpla-Delivery ignorujte duplicity.
• Neúspešné doručenie sa zopakuje dvakrát. Po 10 zlyhaniach za sebou sa webhook pozastaví, kým ho znova nezapnete.

X-Voxpla-Event: poll.closed
X-Voxpla-Delivery: dlv_6b0c3f...
X-Voxpla-Signature: t=1793390000,v1=5f0c1a...

Príklady

Zoznam živých eventov

curl https://voxpla.eu/api/v1/events?status=live&limit=50 \
  -H "Authorization: Bearer $VOXPLA_API_KEY"

Vytvorenie eventu

curl -X POST https://voxpla.eu/api/v1/events \
  -H "Authorization: Bearer $VOXPLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"All hands","startsAt":"2026-11-20T09:00:00Z","locale":"en"}'

Vytvorenie a spustenie ankety

curl -X POST https://voxpla.eu/api/v1/sessions/$SESSION_ID/polls \
  -H "Authorization: Bearer $VOXPLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"multiple_choice","title":"Lunch?","options":[{"label":"Pizza"},{"label":"Salad"}]}'

curl -X POST https://voxpla.eu/api/v1/polls/$POLL_ID/activate -H "Authorization: Bearer $VOXPLA_API_KEY"

Načítanie výsledkov

curl https://voxpla.eu/api/v1/polls/$POLL_ID/results -H "Authorization: Bearer $VOXPLA_API_KEY"

Schválenie otázky

curl -X POST https://voxpla.eu/api/v1/questions/$QUESTION_ID/actions \
  -H "Authorization: Bearer $VOXPLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"approve"}'