Pierwsze wywołanie w pięć minut

Od zera do sesji na żywo utworzonej przez API, bez opuszczania tej strony.

Przed rozpoczęciem

  • Konto w planie płatnym: API nie wchodzi w skład planu FREE (pełną dokumentację można jednak przeglądać bezpłatnie).
  • Prezentacja w Państwa przestrzeni roboczej: tworzona sesja uruchamia istniejącą prezentację.

  1. Utwórz poświadczenie

    W przestrzeni roboczej należy otworzyć Organizacja → API i utworzyć poświadczenie z zakresem content:write. Sekret jest pokazywany tylko raz – prosimy go zapisać.

    Uzyskaj klucz API

    Poświadczenie należy do organizacji, a nie do konta użytkownika: każdy administrator może je unieważnić, a każde użycie trafia do dziennika audytu. Prosimy prosić wyłącznie o potrzebne zakresy – results:read do odczytu, content:write do tworzenia i prowadzenia sesji.

  2. Utwórz i otwórz sesję

    Z kluczem w nagłówku X-API-Key należy utworzyć sesję na istniejącej prezentacji i otworzyć ją.

    curl -X POST https://api.votinova.prd.atbionapps.com/public/v1/sessions \
  -H "X-API-Key: vz_live_…" \
  -d '{ "presentation_id": "prs_8f3k2" }'

curl -X POST https://api.votinova.prd.atbionapps.com/public/v1/sessions/ses_71xw9/open \
  -H "X-API-Key: vz_live_…"

    Sesja powstaje w stanie DRAFT; jej otwarcie generuje join_code i pokój jest gotowy. Warto obserwować nagłówki X-RateLimit-* w odpowiedzi: są zwracane zawsze i pokazują, ile budżetu żądań pozostało w 60-sekundowym oknie.

  3. Odbierz wyniki

    Prosimy zarejestrować webhooka dla zdarzenia question.results.finalized i odbierać podpisane agregaty we własnym backendzie.

    curl -X POST https://api.votinova.prd.atbionapps.com/public/v1/webhooks \
  -H "X-API-Key: vz_live_…" \
  -d '{ "url": "https://example.com/hooks/votinova",
        "event_types": ["question.results.finalized"] }'

    Prosimy zapisać signing_secret zwrócony przy rejestracji: jest pokazywany tylko raz i to on pozwala zweryfikować każde dostarczenie. Przewodnik po webhookach zawiera gotową do wklejenia weryfikację w trzech językach.

Jeśli coś wygląda nie tak

  • 401 – brakuje nagłówka X-API-Key albo zakresu: treść odpowiedzi wskazuje dokładnie który, w polu required_scope.
  • 402 – Państwa plan nie obejmuje API: treść odpowiedzi zawiera upgrade_to z planem, który je odblokowuje.
  • 429 – budżet tego okna wyczerpany: należy odczekać retry_after_seconds i ponowić z narastającym odstępem.

Co dalej?

Prosimy przejrzeć pełną dokumentację, przetestować każdy endpoint online i podłączyć Zapier albo własnego agenta przez MCP.

Dokumentacja API →