Introdução
Com a Forms API (v4), seu próprio código cria enquetes e formulários, publica-os, coleta as respostas e lê os resultados. É a mesma API que o editor do StrawPoll usa.
- URL base:
https://api.strawpoll.com/v4(também disponível emhttps://strawpoll.com/api/v4) - Formato: JSON na entrada e na saída. Os carimbos de data/hora são strings ISO 8601, e os identificadores, UUIDs.
- Especificação legível por máquina: OpenAPI 3.1
Cada formulário tem um identificador público curto, o slug, como em https://strawpoll.com/r/AZPg4n1Td3-hnVAj6Q8p. Todos os endpoints de formulários esperam o slug.
Autenticação
Crie uma chave em Configurações → Chaves de API. Ela só é exibida uma vez: guarde-a em um lugar seguro. Envie-a em cada requisição:
curl https://api.strawpoll.com/v4/me
-H "X-API-Key: sp_your_key"Authorization: Bearer sp_your_key também funciona. Uma chave age em seu nome: ela pode gerenciar
todos os formulários que você gerencia no painel, inclusive os dos espaços de trabalho dos quais
você é membro. Exclua uma chave nas configurações para revogá-la na hora.
Os endpoints para os participantes, submit e verify, não exigem chave a partir de um navegador.
Requisições de scripts, bibliotecas HTTP, navegadores headless, bots e agentes de IA, reconhecidos
pelo user agent, são recusadas com automated se não enviarem uma chave.
Erros
Os erros retornam o status HTTP correspondente e um corpo JSON:
{ "error": "This poll is closed.", "code": "closed" }error é pensado para pessoas; code, quando presente, para o seu código.
| Status | Significado |
|---|---|
| 400 | A requisição não é válida. Os erros de voto também indicam a pergunta em step. |
| 401 | Sem chave de API, ou invalid_api_key. |
| 403 | Você não pode gerenciar este formulário, ou ele não aceita esta resposta. |
| 404 | Não encontrado. |
| 409 | Conflito, por exemplo uma resposta duplicada (duplicate). |
| 429 | rate_limited: aguarde os segundos indicados em Retry-After. |
| 503 | busy: muitíssimos votos estão chegando ao mesmo tempo. Tente de novo em instantes. |
Limites de taxa
120 requisições por minuto por chave. Sem chave, as requisições de um navegador são contadas por
conta conectada ou por navegador (pelo cookie de voto), até 3000 por minuto para todos os
navegadores atrás de um mesmo endereço IP; requisições sem nenhum dos dois são contadas por
endereço IP. Cada resposta informa sua cota em X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (segundos Unix).
Estrutura de um formulário
Um formulário é uma lista de sections. As seções de pergunta contêm fields, e os campos de opções contêm choices.
type da seção | O que se pergunta | Fields |
|---|---|---|
multiple_choice | Escolher uma ou várias opções; properties.layout dropdown mostra uma resposta como lista suspensa | um field multiple_choice com choices |
picture_choice | Escolher imagens | um field multiple_choice, choices com mediaId |
ranking | Ordenar opções, com pontos por posição | um field ranking com choices |
ranked_choice | Cédula de voto por ordem de preferência, com apuração por segundo turno instantâneo | um field ranked_choice com choices |
meeting | Encontrar uma data | um field date por dia (label YYYY-MM-DD), um choice por horário (label 09:00-10:00 ou All day) |
content | Texto, ou uma pergunta com properties.variant em yes_no, rating, scale, text, long_text, name, email ou word_cloud | um field para a pergunta |
contact_info | Nome e endereço de e-mail | fields text_small e email |
page_break, welcome_screen, thank_you_screen, end_screen, redirect | Layout e telas finais | nenhum |
As configurações que valem para o formulário inteiro ficam em properties. As mais usadas:
| Propriedade | Valores | Padrão |
|---|---|---|
resultsVisibility | public, public_after_response, public_after_close, private | public |
responsesVisibility | public mostra os nomes junto aos resultados, private não, secret também não deixa você ver quem deu quais respostas | private |
responseDuplicateCheck | none, session, ip, name, email, code | ip |
responseDuplicateCheckInterval | minutos até que a mesma pessoa possa responder de novo, ou null | null |
opensAt, closesAt | carimbos de data/hora ISO, ou null | null |
responseLimit | número máximo de respostas, ou null | null |
allowComments, commentsVisibility | true/false, public/private | false, private |
editResponsePermissions | admin_own_responses, own_responses, admin, nobody | admin_own_responses |
blockVPNUsers, useCaptchaVerification | true/false | true, false |
A especificação OpenAPI lista todas as propriedades das seções, fields e choices.
Criar uma enquete
curl https://api.strawpoll.com/v4/forms
-H "X-API-Key: sp_your_key"
-H "Content-Type: application/json"
-d '{
"title": "Onde vamos comer?",
"status": "published",
"properties": { "responseDuplicateCheck": "ip", "resultsVisibility": "public" },
"sections": [{
"type": "multiple_choice",
"fields": [{
"type": "multiple_choice",
"label": "Onde vamos comer?",
"properties": { "isMultipleChoice": false },
"choices": [{ "label": "Pizza" }, { "label": "Sushi" }, { "label": "Tacos" }]
}]
}]
}'A resposta contém o formulário completo, com os identificadores gerados e seus links em urls.formUrl e urls.resultsUrl. Sem "status": "published", um formulário começa como
rascunho, visível só para você.
Uma enquete de reunião propõe horários em determinados dias, no fuso horário da seção:
{
"title": "Reunião de equipe",
"status": "published",
"sections": [
{
"type": "meeting",
"properties": { "timezone": "America/Sao_Paulo", "duration": 60, "location": "Sala 1" },
"fields": [
{
"type": "date",
"label": "2026-11-02",
"choices": [{ "label": "09:00-10:00" }, { "label": "14:00-15:00" }]
},
{ "type": "date", "label": "2026-11-03", "choices": [{ "label": "09:00-10:00" }] }
]
}
]
}Assistentes de IA (MCP)
O StrawPoll tem um servidor de Model Context Protocol: assim, assistentes de IA como Claude, ChatGPT ou Cursor podem criar enquetes e ler resultados por você.
- URL do servidor:
https://strawpoll.com/mcp(Streamable HTTP) - Conexão: OAuth. Adicione a URL como conector personalizado no seu assistente e entre no
StrawPoll quando ele pedir; você decide se autoriza o acesso. Clientes sem OAuth podem enviar,
em vez disso, uma chave de API via
X-API-KeyouAuthorization: Bearer sp_your_key.
| Ferramenta | O que faz |
|---|---|
create_poll | Uma pergunta com opções: uma votação, uma classificação ou uma enquete de reunião. Publicada. |
create_form | Um formulário com várias perguntas, de multiple_choice a matrix. Um rascunho. |
publish_poll | Publicar um rascunho. |
list_polls | Suas enquetes, da mais recente à mais antiga, com o número de respostas. |
get_results | Votos por opção, posições médias, disponibilidade das enquetes de reunião e últimas respostas de texto. |
set_poll_open | Encerrar uma enquete ou reabri-la. |
As enquetes criadas por um assistente são suas como as outras e usam suas configurações padrão para enquetes novas. Um assistente pode criar até 30 por hora.
Links de enquete
Assistentes sem ferramentas podem lhe dar um link que abre o editor com a enquete já preenchida, pronta para revisar e publicar:
https://strawpoll.com/forms/new?title=Onde%20vamos%20comer%3F&options=Pizza|Sushi|Tacosoptions é dividido por | (ou repita option=). Adicione type=ranking ou type=meeting (opções como 2026-11-03 ou 2026-11-03 14:00-15:00, com timezone=America/Sao_Paulo), multiple=1 para permitir mais de uma resposta e other=1 para uma resposta livre.
Endpoints
Conta
GET/me | O dono da chave e seus espaços de trabalho. |
Formulários
GET/forms | Seus formulários, do mais recente ao mais antigo. ?workspaceId= mostra os formulários de um espaço de trabalho. |
POST/forms | Criar um formulário. workspaceId opcional; por padrão, seu primeiro espaço de trabalho. |
GET/forms/{slug} | O formulário publicado, com suas sections, fields, choices e contagens. |
PUT/forms/{slug} | Substituir o formulário publicado (veja abaixo). |
PATCH/forms/{slug} | Alterar apenas name, isOpen ou properties. |
DELETE/forms/{slug} | Excluir definitivamente o formulário e suas respostas. |
PUT substitui tudo: as sections, fields e choices que você omitir são excluídos, junto com suas
respostas. Envie de novo os identificadores dos elementos que quiser manter para que as respostas
deles sejam preservadas. Formulários removidos pela moderação (deleted, blocked) respondem 403.
Rascunhos e publicação
O editor salva as alterações como rascunho e as publica em um só passo. Até lá, os participantes continuam vendo o formulário publicado.
PUT/forms/{slug}/draft | Salvar title, themeId, properties e sections como rascunho. |
DELETE/forms/{slug}/draft | Descartar o rascunho. |
POST/forms/{slug}/publish | Publicar o rascunho. Um corpo com sections é salvo antes. |
Respostas
GET/forms/{slug}/responses | As respostas, da mais recente à mais antiga. limit (até 100) e offset. |
DELETE/forms/{slug}/responses | Redefinir: excluir todas as respostas e zerar as contagens. |
Os totais por opção ficam no próprio formulário: responseCount em cada field e cada choice, e score nas classificações. O objeto fields de uma resposta contém as respostas dela no formato
descrito em Enviar uma resposta.
Enviar uma resposta
POST/forms/{slug}/submit envia uma resposta exatamente como a página de votação, aplicando todas
as regras do formulário: agendamento, limites, uma resposta por pessoa, captcha, bloqueio de VPN,
códigos e verificação de e-mail. Navegadores não precisam de chave; scripts e outros clientes
automatizados precisam enviar uma.
{
"fields": {
"<id do campo de opções>": ["<id do choice>"],
"<id do campo de classificação>": [
"<id do melhor choice>",
"<id do choice seguinte>",
"<id do último choice>"
],
"<id do campo de data>": [{ "choiceId": "<id do choice>", "status": "yes" }],
"<id do campo sim/não>": "yes",
"<id do campo de texto>": "Texto livre"
},
"name": "Ana",
"comment": "Opcional",
"code": "Código único opcional"
}| Resposta | Formato |
|---|---|
| Perguntas de opções e de imagens | lista de identificadores de choices, mais um texto se respostas livres forem permitidas |
| Classificação | cada identificador de choice, o melhor primeiro |
| Voto por ordem de preferência | o identificador do choice em cada posição, o melhor primeiro, null para uma posição em branco |
| Enquete de reunião | para cada field de data, uma lista de choiceId e status (yes, if_need_be, no); name é obrigatório |
| Sim/não | "yes" ou "no" |
| Avaliação e escala | o número como string, por exemplo "4" |
| Campos de texto e dados de contato | uma string |
Um envio bem-sucedido retorna o id da resposta. As recusas trazem um code: upcoming, closed, full, unavailable, decided, captcha, vpn, code, verify_email, disposable, automated (todos com 403), duplicate (409) e busy (503).
O navegador do participante recebe um cookie strawpoll_session. Com ele, PUT/forms/{slug}/submit e
o id da resposta alteram essa resposta, se o formulário permitir que os participantes a alterem.
Em formulários limitados a uma resposta por endereço de e-mail, verifique primeiro o endereço com POST/forms/{slug}/verify: envie action: "send" com o email e depois action: "verify" com o code de 6 dígitos que o participante recebeu.
Códigos e convites
GET/forms/{slug}/codes | Códigos únicos. |
POST/forms/{slug}/codes | Gerar count códigos de length caracteres, com style e prefix opcionais. |
DELETE/forms/{slug}/codes | Excluir códigos por ids. |
GET/forms/{slug}/invites | Convites por e-mail. |
POST/forms/{slug}/invites | Adicionar um convite, ou até 1000 via invites. |
PATCH/forms/{slug}/invites/{id} | Alterar um convite. |
DELETE/forms/{slug}/invites/{id} | Excluir um convite. |
DELETE/forms/{slug}/invites | Excluir convites por ids. |
POST/forms/{slug}/invites/import | Convidar todas as pessoas de uma lista de convidados (inviteListId). |
POST/forms/{slug}/invites/send | Enviar os convites por e-mail com subject e message. |
As mensagens de convite podem usar as variáveis name, form e link entre chaves duplas.
Mídia e temas
POST/media | Enviar uma imagem (file em multipart, até 5 MB). O id dela serve como mediaId de um choice. |
GET/themes | Seus temas, os dos seus espaços de trabalho e os temas integrados; ?workspaceId= para os de um espaço de trabalho. |
POST/themes | Criar um tema com um name e properties de cor; adicione workspaceId para compartilhá-lo com um espaço de trabalho que você possui ou gerencia. |
PUT/themes/{id} | Alterar um tema. workspaceId o compartilha com um espaço de trabalho; null o torna de novo pessoal do dono. |
DELETE/themes/{id} | Excluir um tema. Os temas de um espaço de trabalho podem ser alterados e excluídos pelo dono e pelos administradores dele. |
Migrar da Poll API (v3)
A Poll API v3 continua funcionando, com as mesmas rotas, chaves e enquetes. O guia de compatibilidade v3 mostra o que corresponde a quê.