Votre premier appel en cinq minutes

De zéro à une session en direct créée par API, sans quitter cette page.

Avant de commencer

  • Un compte avec un plan payant : l'API ne fait pas partie de FREE (vous pouvez tout de même parcourir toute la référence sans payer).
  • Une présentation dans votre espace : la session que vous allez créer projette une présentation existante.

  1. Créez votre identifiant

    Dans votre espace, ouvrez Entreprise → API et créez un identifiant avec le scope content:write. Le secret n'est montré qu'une fois : conservez-le.

    Obtenez votre clé d'API

    L'identifiant appartient à l'organisation, pas à votre utilisateur : tout administrateur peut le révoquer et chaque usage est consigné dans le journal d'audit. Ne demandez que les scopes nécessaires — results:read pour lire, content:write pour créer et conduire.

  2. Créez et ouvrez une session

    Avec votre clé dans l'en-tête X-API-Key, créez une session sur une présentation existante et ouvrez-la.

    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 session naît en DRAFT ; l'ouvrir frappe son join_code et la salle est prête. Surveillez les en-têtes X-RateLimit-* de la réponse : ils voyagent à chaque réponse et disent le budget de requêtes restant dans la fenêtre de 60 secondes.

  3. Recevez les résultats

    Enregistrez un webhook pour question.results.finalized et recevez les agrégats signés dans votre 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"] }'

    Conservez le signing_secret retourné à l'inscription : il n'est montré qu'une fois, et c'est lui qui permet de vérifier chaque livraison. Le guide des webhooks fournit la vérification prête à coller en trois langages.

Si quelque chose cloche

  • 401 — l'en-tête X-API-Key ou le scope manque : le corps nomme lequel dans required_scope.
  • 402 — votre plan n'inclut pas l'API : le corps porte upgrade_to avec le plan qui la débloque.
  • 429 — budget épuisé pour cette fenêtre : attendez retry_after_seconds et réessayez avec backoff.

Et ensuite ?

Parcourez la référence complète, essayez chaque endpoint en ligne et connectez Zapier ou votre agent via MCP.

Référence de l'API →