La tua prima chiamata in cinque minuti

Da zero a una sessione live creata via API, senza lasciare questa pagina.

Prima di iniziare

  • Un account con piano a pagamento: l'API non è inclusa in FREE (l'intero riferimento però si può esplorare gratis).
  • Una presentazione nel tuo spazio: la sessione che stai per creare proietta una presentazione esistente.

  1. Crea la tua credenziale

    Nel tuo spazio, apri Azienda → API e crea una credenziale con lo scope content:write. Il segreto si mostra una sola volta: conservalo.

    Ottieni la tua API key

    La credenziale appartiene all'organizzazione, non al tuo utente: qualsiasi admin può revocarla e ogni uso finisce nel log di audit. Chiedi solo gli scope necessari — results:read per leggere, content:write per creare e condurre.

  2. Crea e apri una sessione

    Con la chiave nell'header X-API-Key, crea una sessione su una presentazione esistente e aprila.

    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_…"

    La sessione nasce in DRAFT; aprendola riceve il suo join_code e la sala è pronta. Osserva gli header X-RateLimit-* della risposta: viaggiano sempre e dicono quanto budget di richieste resta nella finestra di 60 secondi.

  3. Ricevi i risultati

    Registra un webhook per question.results.finalized e ricevi gli aggregati firmati nel tuo backend.

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

    Conserva il signing_secret restituito alla registrazione: si mostra una sola volta ed è ciò che ti permette di verificare ogni consegna. La guida ai webhook porta la verifica pronta da incollare in tre linguaggi.

Se qualcosa non torna

  • 401 — manca l'header X-API-Key o lo scope: il corpo dice quale in required_scope.
  • 402 — il tuo piano non include l'API: il corpo porta upgrade_to con il piano che la sblocca.
  • 429 — budget esaurito per questa finestra: aspetta retry_after_seconds e riprova con backoff.

E adesso?

Esplora il riferimento completo, prova ogni endpoint online e collega Zapier o il tuo agente via MCP.

Riferimento API →