API para desarrolladores

Visión general

La API para desarrolladores es una API REST bajo /api/v1. Todas las solicitudes y respuestas son JSON. El contrato completo e interactivo está en la referencia de la API; esta página te lleva a tu primera llamada exitosa.

Autenticación

Autentícate con una clave de API del workspace enviada como token Bearer. Genera una en Studio → API para desarrolladores (planes de pago). El secreto se muestra una sola vez - guárdalo en un lugar seguro; si lo pierdes, revoca la clave y crea una nueva.

Authorization: Bearer $POLLSLIVE_KEY

Las claves actúan con autoridad de administrador dentro de su workspace. Nunca expongas una clave en código del lado del cliente: llama a la API desde tu servidor.

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

Inicio rápido

Crea una encuesta, publícala y luego lee los resultados:

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"

Tipos de preguntas

Una encuesta es un mazo de diapositivas tipadas. Establece kind en cada diapositiva. Cada uno de estos tipos se puede crear mediante la API:

• multiple_choice: type (única/múltiple), options[]. Votable de forma asíncrona.
• quiz: options[], correctOptionIds[], timeLimitSec, points, speedBonus.
• quiz_typed: acceptedAnswers[], timeLimitSec, points, speedBonus (solo en sesiones en vivo; 1-10 respuestas válidas de hasta 60 caracteres cada una, comparadas sin tener en cuenta mayúsculas ni espacios de más; los jugadores escriben hasta 40 caracteres).
• quiz_order: items[], timeLimitSec, points, speedBonus (solo en sesiones en vivo; 3-6 elementos con id y label, guardados en el orden correcto; los jugadores los ven mezclados y solo puntúa el orden exacto).
• scale: min, max, minLabel, maxLabel, statements[].
• ranking: options[] (los encuestados las ordenan).
• open_ended: maxLength, render (lista/nube).
• qa: moderated, allowUpvotes.
• estimation: cards[], deckPreset (Planning Poker; solo en sesiones en vivo, los votos permanecen ocultos hasta que los reveles).
• brainstorm: maxLength, moderated, groups[], votesPerPerson (solo en sesiones en vivo; la sala vota los grupos que formas a partir de las ideas).
• content - solo de visualización.

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

Imágenes, vídeo y enlaces

Cualquier diapositiva y cualquier opción puede llevar media. Sube o pasa una URL a POST /media e incrusta el objeto devuelto. Las imágenes se descargan, se recodifican a WebP y se vuelven a alojar (cargas más pequeñas). Los vídeos de YouTube y los enlaces web conservan su URL y se renderizan del lado del cliente, así que nunca pagas por alojar vídeo. También puedes pasar media: { type, url } en línea en una diapositiva u opción y la API lo resuelve al guardar.

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

Respuestas y resultados

multiple_choice las diapositivas reciben votos mediante POST /polls/{id}/votes. Cualquier otro tipo recibe respuestas asíncronas mediante POST /polls/{id}/responses - envía el campo que corresponda a la diapositiva (scaleValue, rankingOrder, text, o optionIds). Lee los agregados por diapositiva desde 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!" }'

Sesiones en vivo y control de sesiones

A live session lets you drive a poll in real time in front of an audience. Create a session via the API, share the PIN or QR code, then control pacing and results visibility with the control endpoint.

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

Todas las acciones de control de sesión

Haz un POST a /api/v1/sessions/{id}/control (Bearer) con una de estas cadenas de acción.

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

Exportar resultados

Descarga los resultados agregados como un archivo CSV UTF-8 RFC-4180, o como informe PDF con ?format=pdf. Cada fila contiene el número de diapositiva, el texto de la pregunta, el tipo, la etiqueta de respuesta y el recuento o valor. Compatible con Excel, Google Sheets y cualquier herramienta CSV. Solo en planes de pago.

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

• Encuestas: GET/POST /polls, GET/PATCH/DELETE /polls/{id}
• Resultados: GET /polls/{id}/results, GET/POST /polls/{id}/responses
• Votos: GET/POST /polls/{id}/votes
• Medios: POST /media
• Sesiones: POST /sessions, GET /sessions/{id}, POST /sessions/{id}/control
• Exportar: GET /polls/{id}/export

Consulta las formas de solicitud/respuesta y prueba llamadas en vivo en la referencia de la API.

Errores y límites de tasa

Los errores usan un sobre estable:

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

Códigos comunes: 401 clave inválida o ausente, 402 se requiere mejorar el plan, 404 no encontrado, 409 conflicto (p. ej. ya votó, encuesta cerrada), 422 validación fallida, 429 límite de tasa alcanzado.,

Límites de frecuencia

La API permite 120 peticiones por minuto por clave en todos los endpoints. La ingesta de medios (POST /media) tiene un límite aparte de 30 peticiones por minuto. Al superar un límite se devuelve HTTP 429. Espera y vuelve a intentarlo.

OAuth2 (Pro y superior)

Cualquier espacio de trabajo de pago (Pro o superior) puede usar credenciales de cliente OAuth2 en lugar de claves estáticas. Crea los clientes en el Studio; la guía de OAuth explica el flujo completo.

Cambios de la API para desarrolladores

Cambios en la API para desarrolladores, del más reciente al más antiguo. Los cambios del producto están en el registro de cambios.

Política de versionado de la API

La API REST se versiona a nivel de URL (/api/v1/). Los cambios que rompen compatibilidad solo se introducen con un nuevo prefijo de versión y con al menos 90 días de aviso en funcionamiento paralelo. Los cambios aditivos (campos nuevos, endpoints nuevos, eventos de webhook nuevos) no rompen nada y pueden publicarse en cualquier momento.