Developers

Desarrolle sobre la API de ScoreStory

ScoreStory tiene una API REST pública. Todo lo que puede hacer en la interfaz con encuestas, invitaciones, participantes, resultados y envíos de correo, también puede hacerlo a través de la API — desde su propia integración, o desde un agente de IA que actúe en su nombre. Alojada en la UE, en los mismos endpoints que usa la propia aplicación.

Referencia de la API Documentación interactiva de cada endpoint. Esquema OpenAPI La especificación legible por máquina (OpenAPI 3, JSON).

Primeros pasos

  1. Cree un token dentro de la aplicación, como administrador, en Organización → Tokens de API. Limítelo a lo que su integración realmente necesita, y fije una caducidad si es posible.
  2. Llame a GET /api/public-api/v1/me para comprobar qué espacio de trabajo, qué scopes y qué restricción de encuesta tiene el token.
  3. Haga su primera llamada:
# 1. ¿Qué puede hacer este token?
curl -s https://app.scorestory.eu/api/public-api/v1/me \
  -H "Authorization: Bearer $SCORESTORY_TOKEN"

# 2. Crear una encuesta (obligatorio: 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":"es"}'

# 3. Invitar a alguien
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"}'

Qué puede hacer

  • Crear, leer, actualizar, duplicar y eliminar encuestas
  • Gestionar propiedades y temas de los participantes
  • Crear, reemitir, revocar y enviar por correo invitaciones personales y enlaces compartidos
  • Leer los participantes y sus transcripciones; eliminar un participante (RGPD)
  • Leer resultados: resumen, puntuaciones individuales, conclusión escrita, temas con citas, evolución en el tiempo
  • Crear, programar, enviar y pausar envíos de correo, y leer sus estadísticas

Reglas básicas

Los límites de frecuencia se aplican por token; una respuesta 429 incluye una cabecera Retry-After que indica cuánto tiempo esperar. Los errores siempre tienen la forma {"error": {"code": "...", "message": "..."}} — evalúe code, no el texto del mensaje. El versionado es aditivo: los campos solo se añaden dentro de una versión principal, nunca se eliminan ni se reutilizan. Todavía no hay webhooks — consulte los endpoints de resultados mediante sondeo (polling).

Para agentes de IA

Si es un agente que actúa en nombre de alguien, empiece por llms.txt — contiene la misma información presentada para lectura por máquina. Necesitará un token de API del espacio de trabajo para hacer cualquier cosa: no hay forma de crear uno de manera programática, así que pida a la persona para la que trabaja que cree uno en Organización → Tokens de API y se lo entregue.

Preguntas

Contáctenos en welcome@scorestory.eu.

Última actualización: 7 de septiembre de 2026.