Developers

Build on the ScoreStory API

ScoreStory has a public REST API. Everything you can do in the interface with surveys, invitations, respondents, results and mailings, you can also do through the API — from your own integration, or from an AI agent acting on your behalf. Hosted in the EU, on the same endpoints the app itself uses.

API reference Interactive documentation for every endpoint. OpenAPI schema The machine-readable spec (OpenAPI 3, JSON).

Getting started

  1. Create a token inside the app, as an admin, under Organisation → API tokens. Scope it to only what your integration needs, and set an expiry if you can.
  2. Call GET /api/public-api/v1/me to check which workspace, scopes and survey restriction the token has.
  3. Make your first call:
# 1. What can this token do?
curl -s https://app.scorestory.eu/api/public-api/v1/me \
  -H "Authorization: Bearer $SCORESTORY_TOKEN"

# 2. Create a survey (required: 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":"en"}'

# 3. Invite someone
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"}'

What you can do

  • Create, read, update, clone and delete surveys
  • Manage respondent properties and themes
  • Create, reissue, revoke and email personal invitations and shared links
  • Read respondents and their transcripts; erase a respondent (GDPR)
  • Read results: overview, individual scores, written conclusion, themes with quotes, trend over time
  • Create, schedule, send, pause and read statistics for mailings

Ground rules

Rate limits are per token; a 429 response carries a Retry-After header telling you how long to wait. Errors always look like {"error": {"code": "...", "message": "..."}} — branch on code, not on the message text. Versioning is additive: fields are only added within a major version, never removed or repurposed. There are no webhooks yet — poll the results endpoints.

For AI agents

If you're an agent acting on someone's behalf, start at llms.txt — it has the same information laid out for machine reading. You'll need a workspace API token to do anything: there is no way to create one programmatically, so ask the person you're working for to make one under Organisation → API tokens and hand it to you.

Questions

Reach us at welcome@scorestory.eu.

Last updated: 7 September 2026.