API développeur

Aperçu

L'API développeur est une API REST sous /api/v1. Toutes les requêtes et réponses sont en JSON. Le contrat complet et interactif se trouve dans la référence de l'API; cette page vous amène à votre premier appel réussi.

Authentification

Authentifiez-vous avec une clé d'API d'espace de travail envoyée comme jeton Bearer. Générez-en une dans Studio → API développeur (forfaits payants). Le secret est affiché une seule fois - conservez-le en lieu sûr ; si vous le perdez, révoquez la clé et créez-en une nouvelle.

Authorization: Bearer $POLLSLIVE_KEY

Les clés agissent avec une autorité d'administrateur au sein de leur espace de travail. N'exposez jamais une clé dans du code côté client. Appelez l'API depuis votre serveur.

You can also authenticate using an OAuth 2.0 Client Credentials access token for machine-to-machine integrations.

Démarrage rapide

Créez un sondage, publiez-le, puis lisez les résultats :

curl -X POST https://pollslive.com/api/v1/polls \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Lunch vote",
    "content": {
      "questions": [{
        "id": "q1", "kind": "multiple_choice", "text": "Where to?",
        "type": "single",
        "options": [
          { "id": "a", "label": "Tacos" },
          { "id": "b", "label": "Sushi" }
        ]
      }]
    }
  }'

curl -X PATCH https://pollslive.com/api/v1/polls/POLL_ID \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "publish": true }'

curl https://pollslive.com/api/v1/polls/POLL_ID/results \
  -H "Authorization: Bearer $POLLSLIVE_KEY"

Types de questions

Un sondage est un jeu de diapositives typées. Définissez kind sur chaque diapositive. Chacun de ces types peut être créé via l'API :

• multiple_choice: type (simple/multiple), options[]. Votable en asynchrone.
• quiz: options[], correctOptionIds[], timeLimitSec, points, speedBonus.
• quiz_typed: acceptedAnswers[], timeLimitSec, points, speedBonus (sessions en direct uniquement ; 1-10 réponses acceptées, 60 caractères maximum chacune, comparées sans tenir compte de la casse ni des espaces en trop ; les joueurs saisissent jusqu'à 40 caractères).
• quiz_order: items[], timeLimitSec, points, speedBonus (sessions en direct uniquement ; 3-6 éléments avec id et label, enregistrés dans le bon ordre ; les joueurs les voient mélangés et seul l'ordre exact rapporte des points).
• scale: min, max, minLabel, maxLabel, statements[].
• ranking: options[] (les répondants les classent).
• open_ended: maxLength, render (liste/nuage).
• qa: moderated, allowUpvotes.
• estimation: cards[], deckPreset (Planning Poker ; sessions en direct uniquement, les votes restent masqués jusqu'à ce que vous les révéliez).
• brainstorm: maxLength, moderated, groups[], votesPerPerson (sessions en direct uniquement ; la salle vote pour les groupes que vous formez à partir des idées).
• content - affichage seul.

{
  "questions": [
    {
      "id": "s1", "kind": "scale", "text": "How likely are you to recommend us?",
      "min": 0, "max": 10, "minLabel": "Not likely", "maxLabel": "Very likely"
    },
    {
      "id": "q2", "kind": "quiz", "text": "Capital of France?",
      "options": [{ "id": "a", "label": "Paris" }, { "id": "b", "label": "Rome" }],
      "correctOptionIds": ["a"], "timeLimitSec": 20, "points": 100, "speedBonus": true
    },
    {
      "id": "q3", "kind": "ranking", "text": "Rank these features by importance",
      "options": [
        { "id": "r1", "label": "Speed" },
        { "id": "r2", "label": "Reliability" },
        { "id": "r3", "label": "Price" }
      ]
    },
    {
      "id": "q4", "kind": "open_ended", "text": "Any other feedback?",
      "maxLength": 300, "render": "list"
    },
    {
      "id": "q5", "kind": "qa", "text": "Questions for the presenter",
      "moderated": true, "allowUpvotes": true
    }
  ]
}

Images, vidéo et liens

Toute diapositive et toute option peut porter un media. Téléversez ou transmettez une URL à POST /media et intégrez l'objet renvoyé. Les images sont téléchargées, ré-encodées en WebP et ré-hébergées (charges plus légères). Les vidéos YouTube et les liens web conservent leur URL et s'affichent côté client, vous ne payez donc jamais pour héberger la vidéo. Vous pouvez aussi transmettre media: { type, url } en ligne sur une diapositive/option et l'API le résout à l'enregistrement.

# 1) Ingest an image (returns { data: { type, url, storedUrl, width, height } })
curl -X POST https://pollslive.com/api/v1/media \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/cat.jpg" }'

# 2) Embed the storedUrl on a slide option
{ "id": "a", "label": "Option A", "media": { "type": "image", "url": "https://pollslive.com/media/abc.webp" } }

# Or pass the original URL inline - the API resolves it on save:
{ "id": "a", "label": "Option A", "media": { "type": "image", "url": "https://example.com/cat.jpg" } }

# YouTube on a question slide
{ "id": "q1", "kind": "content", "text": "Watch this first",
  "media": { "type": "youtube", "url": "https://youtu.be/dQw4w9WgXcQ" } }

Réponses et résultats

multiple_choice les diapositives reçoivent des votes via POST /polls/{id}/votes. Tout autre type reçoit des réponses asynchrones via POST /polls/{id}/responses - envoyez le champ correspondant à la diapositive (scaleValue, rankingOrder, text, ou optionIds). Lisez les agrégats par diapositive depuis GET /polls/{id}/results.

curl -X POST https://pollslive.com/api/v1/polls/POLL_ID/responses \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "voterId": "user-123", "slideId": "s1", "scaleValue": 9 }'

curl -X POST https://pollslive.com/api/v1/polls/POLL_ID/responses \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voterId": "user-123",
    "slideId": "q3",
    "rankingOrder": ["r2", "r1", "r3"]
  }'

curl -X POST https://pollslive.com/api/v1/polls/POLL_ID/responses \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "voterId": "user-123", "slideId": "q4", "text": "Great product!" }'

Sessions en direct et pilotage de session

A live session lets you drive a poll in real time in front of an audience. Create a session via the API, share the PIN or QR code, then control pacing and results visibility with the control endpoint.

curl -X POST https://pollslive.com/api/v1/sessions \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "pollId": "POLL_ID" }'
# Response includes: id, pin, status, currentSlideIndex, hostToken (once)

curl -X POST https://pollslive.com/api/v1/sessions/SESSION_ID/control \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "next" }'

Toutes les actions de pilotage de session

Envoyez une requête POST à /api/v1/sessions/{id}/control (Bearer) avec l'une de ces chaînes d'action.

{ "action": "goto", "slideIndex": 2 }

Exporter les résultats

Téléchargez les résultats agrégés au format CSV UTF-8 RFC-4180, ou en rapport PDF avec ?format=pdf. Chaque ligne contient le numéro de diapositive, le texte de la question, le type, le libellé de réponse et le décompte ou la valeur. Compatible avec Excel, Google Sheets et tout outil CSV. Forfaits payants uniquement.

curl https://pollslive.com/api/v1/polls/POLL_ID/export \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  --output results.csv

# CSV structure:
# Slide, Question, Type, Answer / Label, Count / Value
# 1, "Where to?", multiple_choice, Tacos, 12
# 1, "Where to?", multiple_choice, Sushi, 8
# 2, "Rate your experience", scale, Average, 8.50
# 2, "Rate your experience", scale, Rating 10, 5

Points de terminaison

• Sondages: GET/POST /polls, GET/PATCH/DELETE /polls/{id}
• Résultats: GET /polls/{id}/results, GET/POST /polls/{id}/responses
• Votes: GET/POST /polls/{id}/votes
• Médias: POST /media
• Sessions: POST /sessions, GET /sessions/{id}, POST /sessions/{id}/control
• Export: GET /polls/{id}/export

Consultez les formes de requête/réponse et testez les appels en direct dans la référence de l'API.

Erreurs et limites de débit

Les erreurs utilisent une enveloppe stable :

{ "error": { "code": "not_found", "message": "Poll not found." } }

Codes courants : 401 clé invalide/absente, 402 mise à niveau du forfait requise, 404 introuvable, 409 conflit (par ex. déjà voté, sondage fermé), 422 échec de la validation, 429 limite de débit atteinte.,

Limites de débit

L'API autorise 120 requêtes par minute et par clé pour tous les endpoints. L'ingestion de médias (POST /media) est plafonnée séparément à 30 requêtes par minute. Un dépassement de limite renvoie HTTP 429. Patientez puis réessayez.

OAuth2 (Pro et au-dela)

Tout espace de travail payant (Pro et au-delà) peut utiliser les identifiants client OAuth2 au lieu de clés statiques. Créez les clients dans le Studio ; le guide OAuth décrit le flux complet.

Changements de l'API développeurs

Les changements de l'API développeurs, du plus récent au plus ancien. Les changements du produit sont dans le journal des modifications.

Politique de versionnage de l'API

L'API REST est versionnée au niveau de l'URL (/api/v1/). Les changements cassants ne sont introduits qu'avec un nouveau préfixe de version et au moins 90 jours de fonctionnement en parallèle. Les changements additifs (nouveaux champs, nouveaux points de terminaison, nouveaux événements webhook) ne cassent rien et peuvent être livrés à tout moment.