Bauen Sie auf der Voxpla API auf

Schnellstart

1. Öffnen Sie in Voxpla die Einstellungen und dann API-Schlüssel (Inhaber und Administratoren).
2. Erstellen Sie einen Schlüssel, wählen Sie seine Berechtigungen und kopieren Sie ihn. Er wird nur einmal angezeigt.
3. Senden Sie ihn bei jeder Anfrage im Header Authorization.
4. Laden Sie die OpenAPI-Beschreibung in Postman, Insomnia oder Ihren Codegenerator.

curl https://voxpla.eu/api/v1/key \
  -H "Authorization: Bearer vx_live_..."

Authentifizierung

Jede Anfrage braucht den Header Authorization: Bearer, gefolgt vom Schlüssel. Schlüssel beginnen mit vx_live_ (außerhalb der Produktion vx_test_). Voxpla speichert nur einen Fingerabdruck des Schlüssels und seine ersten Zeichen zur Anzeige. Ein verlorener Schlüssel lässt sich nicht wiederherstellen: Erstellen Sie einen neuen und widerrufen Sie den alten.

Authorization: Bearer vx_live_3kQ9...

• Ein fehlender, unbekannter, abgelaufener oder widerrufener Schlüssel liefert 401.
• Enthält der Plan der Organisation die API nicht mehr, liefern Schlüssel 402 plan_required.
• Die API akzeptiert keine Browser-Sitzungen, und Schlüssel funktionieren nicht in der Web-App.
• Jeder schreibende Aufruf wird zusammen mit dem verwendeten Schlüssel im Audit-Log festgehalten.

Berechtigungen

Jeder Schlüssel darf lesen. Geben Sie einem Schlüssel weitere Berechtigungen nur, wenn eine Integration sie braucht.

read

Events, Sessions, Fragen, Umfragen, Ergebnisse und Analysen auflisten und lesen, CSV-Exporte abrufen.

write

Events anlegen und bearbeiten, ihren Status ändern, Umfragen anlegen, starten und schließen.

moderate

Fragen moderieren: freigeben, ausblenden, hervorheben, als beantwortet markieren, anheften, archivieren und löschen.

Ein Aufruf außerhalb der Berechtigungen des Schlüssels liefert 403 insufficient_scope.

Ratenlimits

Jeder Schlüssel darf 600 Anfragen pro Minute senden. Darüber antwortet die API mit 429 rate_limited und einem Header Retry-After in Sekunden. Warten Sie so lange und versuchen Sie es dann erneut.

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{"error":"rate_limited","retryAfter":12}

Paginierung

Listen liefern items und next_cursor. Fordern Sie mit limit bis zu 100 Einträge an (Standard 25) und übergeben Sie next_cursor als cursor, um die nächste Seite zu erhalten. Auf der letzten Seite ist next_cursor null. Cursor sind undurchsichtig, bauen Sie sie nicht selbst zusammen.

curl "https://voxpla.eu/api/v1/events?limit=100&cursor=djE6Y2x4..." \
  -H "Authorization: Bearer $VOXPLA_API_KEY"

{ "items": [ ... ], "next_cursor": null }

Fehler

Fehler sind JSON-Objekte mit einem stabilen Code im Feld error. Bauen Sie Ihre Logik auf dem Code auf, nicht auf dem HTTP-Statustext.

400 invalid

Der Anfragetext oder ein Parameter ist ungültig; issues nennt die betroffenen Felder.

401 invalid_api_key

Der Schlüssel fehlt, ist unbekannt oder widerrufen (bei einem abgelaufenen Schlüssel api_key_expired).

402 plan_required

Der Plan der Organisation enthält die API nicht.

403 insufficient_scope

Dem Schlüssel fehlt die Berechtigung, die dieser Aufruf braucht.

404 not_found

Das Objekt existiert in Ihrer Organisation nicht.

429 rate_limited

Zu viele Anfragen; warten Sie die Sekunden aus Retry-After ab.

Endpunkte

Alle Pfade sind relativ zu https://voxpla.eu/api/v1

• GET/keyread

  Der aufrufende Schlüssel, seine Berechtigungen und die Organisation.

• GET/eventsread

  Events Ihrer Organisation, neueste zuerst, optional nach Status gefiltert.

• POST/eventswrite

  Legt ein Event mit einer Session an. Der Teilnahmecode wird erzeugt.

• GET/events/{id}read

  Ein Event mit Teilnahmecode, Link für Teilnehmende und Einstellungen.

• PATCH/events/{id}write

  Ändert Name, Zeit, Zeitzone, Sprache oder Einstellungen.

• POST/events/{id}/statuswrite

  Schaltet das Event auf Entwurf, live, beendet oder archiviert.

• GET/events/{id}/sessionsread

  Sessions eines Events (Räume, Programmblöcke).

• GET/sessions/{id}/questionsread

  Fragen einer Session mit Stimmen und Antworten, optional nach Status gefiltert.

• POST/questions/{id}/actionsmoderate

  Gibt eine Frage frei, blendet sie aus, hebt sie hervor, beantwortet, heftet an, archiviert oder löscht sie.

• GET/sessions/{id}/pollsread

  Umfragen einer Session in ihrer Reihenfolge.

• POST/sessions/{id}/pollswrite

  Legt eine Umfrage, Wortwolke, Bewertung, Quizfrage oder einen anderen Umfragetyp an.

• POST/polls/{id}/activatewrite

  Startet eine Umfrage. Die laufende Umfrage der Session wird geschlossen.

• POST/polls/{id}/closewrite

  Schließt eine Umfrage.

• GET/polls/{id}/resultsread

  Aggregierte Ergebnisse einer Umfrage.

• GET/events/{id}/analyticsread

  Teilnehmende, Beteiligung, Zeitverlauf, Top-Fragen und Umfrageergebnisse.

• GET/events/{id}/export.csvread

  CSV-Export von Fragen, Umfragen, Teilnehmenden oder Antworten aus der Nachbefragung.

Antworten enthalten, was ein Moderator sieht. Anonyme Teilnehmende bleiben anonym: Keine Antwort enthält Identitäten von Teilnehmenden, Tokens oder Links zur Projektion.

Webhooks

Statt die API immer wieder abzufragen, lassen Sie sich von Voxpla benachrichtigen. Einen Webhook richten Sie unter Einstellungen und dann Integrationen für event.started, question.approved, poll.closed und event.ended ein.

• Jede Zustellung ist ein HTTPS POST, signiert im Header X-Voxpla-Signature (HMAC-SHA256 aus Zeitstempel und unverändertem Body).
• Lehnen Sie Zustellungen ab, die älter als 5 Minuten sind, und ignorieren Sie Duplikate anhand von X-Voxpla-Delivery.
• Fehlgeschlagene Zustellungen werden zweimal wiederholt. Nach 10 Fehlern in Folge pausiert der Webhook, bis Sie ihn wieder einschalten.

X-Voxpla-Event: poll.closed
X-Voxpla-Delivery: dlv_6b0c3f...
X-Voxpla-Signature: t=1793390000,v1=5f0c1a...

Beispiele

Live-Events auflisten

curl https://voxpla.eu/api/v1/events?status=live&limit=50 \
  -H "Authorization: Bearer $VOXPLA_API_KEY"

Ein Event anlegen

curl -X POST https://voxpla.eu/api/v1/events \
  -H "Authorization: Bearer $VOXPLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"All hands","startsAt":"2026-11-20T09:00:00Z","locale":"en"}'

Eine Umfrage anlegen und starten

curl -X POST https://voxpla.eu/api/v1/sessions/$SESSION_ID/polls \
  -H "Authorization: Bearer $VOXPLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"multiple_choice","title":"Lunch?","options":[{"label":"Pizza"},{"label":"Salad"}]}'

curl -X POST https://voxpla.eu/api/v1/polls/$POLL_ID/activate -H "Authorization: Bearer $VOXPLA_API_KEY"

Ergebnisse abrufen

curl https://voxpla.eu/api/v1/polls/$POLL_ID/results -H "Authorization: Bearer $VOXPLA_API_KEY"

Eine Frage freigeben

curl -X POST https://voxpla.eu/api/v1/questions/$QUESTION_ID/actions \
  -H "Authorization: Bearer $VOXPLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"approve"}'