API para desenvolvedores

Visão geral

A API para desenvolvedores é uma API REST sob /api/v1. Todas as requisições e respostas são JSON. O contrato completo e interativo está na referência da API; esta página leva você à sua primeira chamada bem-sucedida.

Autenticação

Autentique-se com uma chave de API do workspace enviada como token Bearer. Gere uma em Studio → API para desenvolvedores (planos pagos). O segredo é exibido uma única vez - guarde-o em local seguro; se perdê-lo, revogue a chave e crie uma nova.

Authorization: Bearer $POLLSLIVE_KEY

As chaves agem com autoridade de administrador dentro do seu workspace. Nunca exponha uma chave em código do lado do cliente. Chame a API a partir do seu servidor.

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

Início rápido

Crie uma enquete, publique-a e depois leia os 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 perguntas

Uma enquete é um conjunto de slides tipados. Defina kind em cada slide. Cada um desses tipos pode ser criado via API:

• multiple_choice: type (única/múltipla), options[]. Votável de forma assíncrona.
• quiz: options[], correctOptionIds[], timeLimitSec, points, speedBonus.
• quiz_typed: acceptedAnswers[], timeLimitSec, points, speedBonus (apenas em sessões ao vivo; 1-10 respostas aceitas, até 60 caracteres cada, comparadas sem considerar maiúsculas nem espaços extras; os jogadores digitam até 40 caracteres).
• quiz_order: items[], timeLimitSec, points, speedBonus (apenas em sessões ao vivo; 3-6 itens com id e label, guardados na ordem correta; os jogadores os veem embaralhados e só a ordem exata pontua).
• scale: min, max, minLabel, maxLabel, statements[].
• ranking: options[] (os respondentes os ordenam).
• open_ended: maxLength, render (lista/nuvem).
• qa: moderated, allowUpvotes.
• estimation: cards[], deckPreset (Planning Poker; apenas em sessões ao vivo, os votos ficam ocultos até você revelá-los).
• brainstorm: maxLength, moderated, groups[], votesPerPerson (apenas em sessões ao vivo; a sala vota nos grupos que você monta a partir das ideias).
• content - somente exibição.

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

Imagens, vídeo e links

Qualquer slide e qualquer opção pode carregar media. Faça upload ou passe uma URL para POST /media e incorpore o objeto retornado. As imagens são baixadas, recodificadas para WebP e re-hospedadas (payloads menores). Os vídeos do YouTube e os links da web mantêm sua URL e são renderizados no cliente, então você nunca paga para hospedar vídeo. Você também pode passar media: { type, url } inline em um slide/opção e a API o resolve ao salvar.

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

Respostas e resultados

multiple_choice os slides recebem votos via POST /polls/{id}/votes. Qualquer outro tipo recebe respostas assíncronas via POST /polls/{id}/responses - envie o campo correspondente ao slide (scaleValue, rankingOrder, text, ou optionIds). Leia os agregados por slide em 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!" }'

Sessões ao vivo e controle de sessão

Uma sessão ao vivo permite conduzir uma enquete em tempo real diante de um público. Crie uma sessão pela API, compartilhe o PIN ou o QR code com o público e depois controle o ritmo e a visibilidade dos resultados com o endpoint de controle.

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 as ações de controle de sessão

Faça um POST para /api/v1/sessions/{id}/control (Bearer) com uma destas strings de ação.

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

Exportar resultados

Baixe os resultados agregados como um arquivo CSV UTF-8 RFC-4180, ou como relatório PDF com ?format=pdf. Cada linha contém o número do slide, o texto da pergunta, o tipo, o rótulo da resposta e a contagem ou valor. Compatível com Excel, Google Sheets e qualquer ferramenta CSV. Apenas em planos pagos.

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

• Enquetes: GET/POST /polls, GET/PATCH/DELETE /polls/{id}
• Resultados: GET /polls/{id}/results, GET/POST /polls/{id}/responses
• Votos: GET/POST /polls/{id}/votes
• Mídia: POST /media
• Sessões: POST /sessions, GET /sessions/{id}, POST /sessions/{id}/control
• Exportar: GET /polls/{id}/export

Veja os formatos de requisição/resposta e teste chamadas ao vivo na referência da API.

Erros e limites de taxa

Os erros usam um envelope estável:

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

Códigos comuns: 401 chave inválida/ausente, 402 upgrade de plano necessário, 404 não encontrado, 409 conflito (ex.: já votou, enquete encerrada), 422 falha na validação, 429 limite de taxa atingido. A,

Limites de taxa

A API permite 120 requisições por minuto por chave em todos os endpoints. A ingestão de mídia (POST /media) tem um limite separado de 30 requisições por minuto. Quando um limite é excedido, a API retorna HTTP 429. Aguarde e tente novamente.

OAuth2 (Pro e acima)

Qualquer workspace pago (Pro ou acima) pode usar credenciais de cliente OAuth2 em vez de chaves estáticas. Crie os clientes no Studio; o guia de OAuth explica o fluxo completo.

Mudanças da API para desenvolvedores

Mudanças na API para desenvolvedores, da mais recente para a mais antiga. As mudanças do produto estão no registro de alterações.

Política de versionamento da API

A API REST é versionada no nível da URL (/api/v1/). Mudanças que quebram compatibilidade só entram com um novo prefixo de versão e ao menos 90 dias de operação em paralelo. Mudanças aditivas (novos campos, novos endpoints, novos eventos de webhook) não quebram nada e podem ser lançadas a qualquer momento.