Entwickler-API

Überblick

Die Entwickler-API ist eine REST-API unter /api/v1. Alle Anfragen und Antworten sind JSON. Der vollständige, interaktive Vertrag findet sich in der API-Referenz; diese Seite bringt dich zu deinem ersten erfolgreichen Aufruf.

Authentifizierung

Authentifiziere dich mit einem Workspace-API-Schlüssel , der als Bearer-Token gesendet wird. Erstelle einen in Studio → Entwickler-API (kostenpflichtige Tarife). Das Secret wird nur einmal angezeigt. Bewahre es sicher auf; wenn du es verlierst, widerrufe den Schlüssel und erstelle einen neuen.

Authorization: Bearer $POLLSLIVE_KEY

Schlüssel handeln mit Admin-Berechtigung innerhalb ihres Workspaces. Gib einen Schlüssel niemals im clientseitigen Code preis. Rufe die API von deinem Server aus auf.

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

Schnellstart

Erstelle eine Umfrage, veröffentliche sie und lies dann die Ergebnisse:

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"

Fragetypen

Eine Umfrage ist ein Stapel typisierter Folien. Setze kind auf jeder Folie. Jeder dieser Typen lässt sich über die API erstellen:

• multiple_choice: type (Einfach-/Mehrfachauswahl), options[]. Asynchron abstimmbar.
• quiz: options[], correctOptionIds[], timeLimitSec, points, speedBonus.
• quiz_typed: acceptedAnswers[], timeLimitSec, points, speedBonus (nur in Live-Sitzungen; 1-10 gültige Antworten mit je bis zu 60 Zeichen, verglichen ohne Rücksicht auf Groß- und Kleinschreibung und überflüssige Leerzeichen; Spielende tippen bis zu 40 Zeichen).
• quiz_order: items[], timeLimitSec, points, speedBonus (nur in Live-Sitzungen; 3-6 Elemente mit id und label, gespeichert in der richtigen Reihenfolge; Spielende sehen sie gemischt, Punkte gibt es nur für die exakte Reihenfolge).
• scale: min, max, minLabel, maxLabel, statements[].
• ranking: options[] (die Befragten ordnen sie).
• open_ended: maxLength, render (Liste/Wolke).
• qa: moderated, allowUpvotes.
• estimation: cards[], deckPreset (Planning Poker; nur in Live-Sitzungen, Stimmen bleiben verborgen, bis du sie aufdeckst).
• brainstorm: maxLength, moderated, groups[], votesPerPerson (nur in Live-Sitzungen; das Publikum stimmt über die Gruppen ab, die du aus den Ideen bildest).
• content - nur Anzeige.

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

Bilder, Video & Links

Jede Folie und jede Option kann mediatragen. Lade eine URL hoch oder übergib sie an POST /media und binde das zurückgegebene Objekt ein. Bilder werden heruntergeladen, in WebP neu kodiert und neu gehostet (kleinere Payloads). YouTube -Videos und Web-Links behalten ihre URL und werden clientseitig gerendert, du zahlst also nie für das Hosten von Video. Du kannst auch media: { type, url } inline auf einer Folie/Option übergeben, und die API löst es beim Speichern auf.

# 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" } }

Antworten & Ergebnisse

multiple_choice -Folien nehmen Stimmen über POST /polls/{id}/votesentgegen. Jeder andere Typ nimmt asynchrone Antworten über POST /polls/{id}/responses entgegen. Sende das zur Folie passende Feld (scaleValue, rankingOrder, text, oder optionIds). Lies Aggregate pro Folie aus 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!" }'

Live-Sitzungen & Sitzungssteuerung

Mit einer Live-Sitzung steuerst du eine Umfrage in Echtzeit vor einem Publikum. Erstelle eine Sitzung über die API, teile die PIN oder den QR-Code mit deinem Publikum und steuere dann Tempo und Sichtbarkeit der Ergebnisse über den Control-Endpunkt.

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

Alle Aktionen zur Sitzungssteuerung

POST an /api/v1/sessions/{id}/control (Bearer) mit einem dieser Aktions-Strings.

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

Ergebnisse exportieren

Lade aggregierte Umfrageergebnisse als UTF-8-CSV nach RFC 4180 herunter oder als PDF-Bericht mit ?format=pdf. Jede Zeile enthält Foliennummer, Fragetext, Typ, Antwortbezeichnung und Anzahl bzw. Wert. Kompatibel mit Excel, Google Sheets und jedem CSV-Tool. Nur in kostenpflichtigen Tarifen.

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

Endpoints

• Umfragen: GET/POST /polls, GET/PATCH/DELETE /polls/{id}
• Ergebnisse: GET /polls/{id}/results, GET/POST /polls/{id}/responses
• Stimmen: GET/POST /polls/{id}/votes
• Medien: POST /media
• Sitzungen: POST /sessions, GET /sessions/{id}, POST /sessions/{id}/control
• Export: GET /polls/{id}/export

Sieh dir Anfrage-/Antwortformate an und teste Aufrufe live in der API-Referenz.

Fehler & Rate-Limits

Fehler verwenden eine stabile Hülle:

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

Häufige Codes: 401 ungültiger/fehlender Schlüssel, 402 Tarif-Upgrade erforderlich, 404 nicht gefunden, 409 Konflikt (z. B. bereits abgestimmt, Umfrage geschlossen), 422 Validierung fehlgeschlagen, 429 Rate-Limit erreicht.,

Rate-Limits

Die API erlaubt 120 Anfragen pro Minute und Schlüssel für alle Endpunkte. Die Medienaufnahme (POST /media) ist separat auf 30 Anfragen pro Minute begrenzt. Bei Überschreitung eines Limits wird HTTP 429 zurückgegeben. Warte kurz und versuche es erneut.

OAuth2 (ab Pro)

Jeder kostenpflichtige Workspace (ab Pro) kann OAuth2-Client-Credentials statt statischer Schlüssel nutzen. Clients erstellst du im Studio; der OAuth-Leitfaden beschreibt den vollständigen Ablauf.

Änderungen an der Entwickler-API

Änderungen an der Entwickler-API, die neuesten zuerst. Produktänderungen stehen im Änderungsprotokoll.

Versionierungsrichtlinie der API

Die REST-API wird auf URL-Ebene versioniert (/api/v1/). Breaking Changes kommen nur mit einem neuen Versionspräfix und mindestens 90 Tagen Parallelbetrieb. Additive Änderungen (neue Felder, neue Endpunkte, neue Webhook-Events) sind nicht brechend und können jederzeit ausgeliefert werden.