Developers

Entwickeln Sie mit der ScoreStory-API

ScoreStory hat eine öffentliche REST-API. Alles, was Sie in der Oberfläche mit Umfragen, Einladungen, Teilnehmern, Ergebnissen und Mailings tun können, können Sie auch über die API tun — für Ihre eigene Integration oder für einen KI-Agenten, der in Ihrem Auftrag handelt. Gehostet in der EU, auf denselben Endpunkten, die auch die App selbst nutzt.

API-Referenz Interaktive Dokumentation für jeden Endpunkt. OpenAPI-Schema Die maschinenlesbare Spezifikation (OpenAPI 3, JSON).

Erste Schritte

  1. Erstellen Sie als Administrator in der App unter Organisation → API-Tokens ein Token. Beschränken Sie es auf das, was Ihre Integration tatsächlich braucht, und setzen Sie nach Möglichkeit ein Ablaufdatum.
  2. Rufen Sie GET /api/public-api/v1/me auf, um zu prüfen, welchen Workspace, welche Scopes und welche Umfrage-Einschränkung das Token hat.
  3. Machen Sie Ihren ersten Aufruf:
# 1. Was darf dieses Token?
curl -s https://app.scorestory.eu/api/public-api/v1/me \
  -H "Authorization: Bearer $SCORESTORY_TOKEN"

# 2. Umfrage erstellen (erforderlich: name, metric_type, interview_locale)
#    metric_type: nps | enps | csat | ces | scale
curl -s -X POST https://app.scorestory.eu/api/surveys \
  -H "Authorization: Bearer $SCORESTORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Q3 pulse","metric_type":"nps","interview_locale":"de"}'

# 3. Jemanden einladen
curl -s -X POST https://app.scorestory.eu/api/surveys/<survey_id>/invitations/personal \
  -H "Authorization: Bearer $SCORESTORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"recipient_email":"sam@example.com","recipient_name":"Sam"}'

Was Sie tun können

  • Umfragen erstellen, lesen, aktualisieren, duplizieren und löschen
  • Teilnehmereigenschaften und Themen verwalten
  • Persönliche Einladungen und geteilte Links erstellen, neu ausstellen, widerrufen und per E-Mail versenden
  • Teilnehmer und ihre Transkripte lesen; einen Teilnehmer löschen (DSGVO)
  • Ergebnisse lesen: Übersicht, einzelne Scores, schriftliches Fazit, Themen mit Zitaten, Verlauf über die Zeit
  • Mailings erstellen, planen, versenden, pausieren und deren Statistiken lesen

Grundregeln

Ratenlimits gelten pro Token; eine 429-Antwort enthält einen Retry-After-Header, der angibt, wie lange Sie warten sollten. Fehler haben immer die Form {"error": {"code": "...", "message": "..."}} — werten Sie code aus, nicht den Text der Meldung. Die Versionierung ist additiv: Felder werden innerhalb einer Hauptversion nur hinzugefügt, nie entfernt oder umgewidmet. Webhooks gibt es noch nicht — fragen Sie die Ergebnis-Endpunkte per Polling ab.

Für KI-Agenten

Wenn Sie als Agent im Auftrag einer Person handeln, beginnen Sie bei llms.txt — dort stehen dieselben Informationen maschinenlesbar aufbereitet. Sie benötigen ein Workspace-API-Token, um irgendetwas zu tun: Es gibt keine Möglichkeit, eines programmatisch zu erstellen, bitten Sie also die Person, für die Sie arbeiten, eines unter Organisation → API-Tokens zu erstellen und es Ihnen zu geben.

Fragen

Erreichen Sie uns unter welcome@scorestory.eu.

Zuletzt aktualisiert: 7. September 2026.