A sua primeira chamada em cinco minutos

Do zero a uma sessão ao vivo criada por API, sem sair desta página.

Antes de começar

  • Uma conta num plano pago: a API não faz parte do FREE (pode na mesma consultar toda a referência sem pagar).
  • Uma apresentação no seu espaço de trabalho: a sessão que vai criar corre sobre uma apresentação existente.

  1. Crie a sua credencial

    No seu espaço de trabalho, abra Organização → API e crie uma credencial com o âmbito content:write. O segredo mostra-se uma única vez: guarde-o.

    Obter a sua chave de API

    A credencial pertence à organização, não ao seu utilizador: qualquer administrador a pode revogar e cada utilização fica no registo de auditoria. Peça apenas os âmbitos de que precisa — results:read para ler, content:write para criar e conduzir.

  2. Crie e abra uma sessão

    Com a sua chave no cabeçalho X-API-Key, crie uma sessão sobre uma apresentação existente e abra-a.

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

    A sessão nasce em DRAFT; abri-la gera o seu join_code e a sala fica pronta. Repare nos cabeçalhos X-RateLimit-* da resposta: viajam em todas e dizem-lhe quanto orçamento de pedidos resta na janela de 60 segundos.

  3. Receba os resultados

    Registe um webhook para question.results.finalized e receba os agregados assinados no seu 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"] }'

    Guarde o signing_secret que o registo devolve: mostra-se uma única vez e é o que lhe permite verificar cada entrega. O guia de webhooks traz a verificação pronta a colar em três linguagens.

Se algo não bate certo

  • 401 — falta o cabeçalho X-API-Key ou o âmbito: o corpo indica o âmbito exato em required_scope.
  • 402 — o seu plano não inclui a API: o corpo traz upgrade_to com o plano que a desbloqueia.
  • 429 — orçamento gasto nesta janela: espere retry_after_seconds e repita com backoff.

E agora?

Consulte toda a referência, experimente cada endpoint online e ligue o Zapier ou o seu agente por MCP.

Referência da API →