Stavějte na Voxpla API

Rychlý start

1. Ve Voxpla otevřete Nastavení a pak API klíče (vlastník a administrátor).
2. Vytvořte klíč, zvolte oprávnění a zkopírujte ho. Zobrazí se jen jednou.
3. Posílejte ho v hlavičce Authorization u každého požadavku.
4. Načtěte popis OpenAPI do Postmanu, Insomnie nebo generátoru kódu.

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

Ověření

Každý požadavek potřebuje hlavičku Authorization: Bearer a za ní klíč. Klíče začínají na vx_live_ (mimo produkci vx_test_). Voxpla si ukládá jen otisk klíče a jeho první znaky pro zobrazení. Ztracený klíč nelze obnovit: vytvořte nový a starý zrušte.

Authorization: Bearer vx_live_3kQ9...

• Chybějící, neznámý, vypršelý nebo zrušený klíč vrátí 401.
• Když plán organizace API už neobsahuje, klíče vracejí 402 plan_required.
• API nepřijímá přihlášení z prohlížeče a klíče nefungují ve webové aplikaci.
• Každé volání, které mění data, se zapíše do auditního logu spolu s klíčem, který ho provedl.

Oprávnění

Číst může každý klíč. Další oprávnění dejte klíči jen tehdy, když je integrace potřebuje.

read

Seznamy a detail eventů, sekcí, dotazů, anket, výsledků, analytiky a exporty CSV.

write

Vytváření a úprava eventů, změna jejich stavu, vytváření, spouštění a uzavírání anket.

moderate

Moderování dotazů: schválení, skrytí, zvýraznění, označení jako zodpovězený, připnutí, archivace a smazání.

Volání mimo oprávnění klíče vrátí 403 insufficient_scope.

Limity požadavků

Každý klíč může poslat 600 požadavků za minutu. Nad limitem API odpoví 429 rate_limited s hlavičkou Retry-After v sekundách. Počkejte uvedenou dobu a zkuste to znovu.

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

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

Stránkování

Seznamy vracejí items a next_cursor. Parametrem limit si vyžádejte nejvýše 100 položek (výchozí 25) a hodnotu next_cursor pošlete jako cursor, abyste dostali další stránku. Na poslední stránce je next_cursor null. Kurzory jsou neprůhledné, neskládejte je sami.

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

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

Chyby

Chyby jsou objekty JSON se stabilním kódem v poli error. Logiku stavějte na kódu, ne na textovém popisu HTTP stavu.

400 invalid

Tělo požadavku nebo parametr je neplatný; issues uvádí konkrétní pole.

401 invalid_api_key

Klíč chybí, je neznámý nebo zrušený (u vypršelého klíče api_key_expired).

402 plan_required

Plán organizace neobsahuje API.

403 insufficient_scope

Klíč nemá oprávnění, které toto volání potřebuje.

404 not_found

Objekt ve vaší organizaci neexistuje.

429 rate_limited

Příliš mnoho požadavků; počkejte počet sekund z hlavičky Retry-After.

Endpointy

Všechny cesty jsou relativní k adrese https://voxpla.eu/api/v1

• GET/keyread

  Volající klíč, jeho oprávnění a organizace.

• GET/eventsread

  Eventy vaší organizace od nejnovějších, volitelně podle stavu.

• POST/eventswrite

  Vytvoří event s jednou sekcí. Kód pro připojení se vygeneruje.

• GET/events/{id}read

  Jeden event s kódem pro připojení, odkazem pro účastníky a nastavením.

• PATCH/events/{id}write

  Změní název, čas, časové pásmo, jazyk nebo nastavení.

• POST/events/{id}/statuswrite

  Přepne event na koncept, živý, ukončený nebo archivovaný.

• GET/events/{id}/sessionsread

  Sekce eventu (místnosti, bloky programu).

• GET/sessions/{id}/questionsread

  Dotazy sekce s hlasy a odpověďmi, volitelně podle stavu.

• POST/questions/{id}/actionsmoderate

  Schválí, skryje, zvýrazní, zodpoví, připne, archivuje nebo smaže dotaz.

• GET/sessions/{id}/pollsread

  Ankety sekce v jejich pořadí.

• POST/sessions/{id}/pollswrite

  Vytvoří anketu, slovní mrak, hodnocení, kvízovou otázku nebo jiný typ ankety.

• POST/polls/{id}/activatewrite

  Spustí anketu. Běžící anketa sekce se uzavře.

• POST/polls/{id}/closewrite

  Uzavře anketu.

• GET/polls/{id}/resultsread

  Agregované výsledky ankety.

• GET/events/{id}/analyticsread

  Účastníci, zapojení, časová osa, nejlepší dotazy a výsledky anket.

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

  Export CSV dotazů, anket, účastníků nebo odpovědí z dotazníku.

Odpovědi obsahují to, co vidí moderátor. Anonymní účastníci zůstávají anonymní: žádná odpověď neobsahuje identitu účastníků, tokeny ani odkazy na projekci.

Webhooky

Místo opakovaného dotazování API nechte Voxpla, ať se ozve vám. Webhook nastavíte v Nastavení v části Integrace pro event.started, question.approved, poll.closed a event.ended.

• Každé doručení je HTTPS POST podepsaný v hlavičce X-Voxpla-Signature (HMAC-SHA256 z časového razítka a surového těla).
• Odmítněte doručení starší než 5 minut a podle X-Voxpla-Delivery ignorujte duplicity.
• Neúspěšné doručení se zopakuje dvakrát. Po 10 selháních za sebou se webhook pozastaví, dokud ho znovu nezapnete.

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

Příklady

Seznam živých eventů

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

Vytvoření 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"}'

Vytvoření a spuštění 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čtení výsledků

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

Schválení dotazu

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"}'