Desenvolvedores / Referência da API

Forms API

v4

Crie enquetes e formulários, publique-os, colete respostas e leia os resultados a partir do seu próprio código.

URL base
https://api.strawpoll.com/v4
Especificação
OpenAPI 3

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 em https://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:

bash
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:

json
{ "error": "This poll is closed.", "code": "closed" }

error é pensado para pessoas; code, quando presente, para o seu código.

StatusSignificado
400A requisição não é válida. Os erros de voto também indicam a pergunta em step.
401Sem chave de API, ou invalid_api_key.
403Você não pode gerenciar este formulário, ou ele não aceita esta resposta.
404Não encontrado.
409Conflito, por exemplo uma resposta duplicada (duplicate).
429rate_limited: aguarde os segundos indicados em Retry-After.
503busy: 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çãoO que se perguntaFields
multiple_choiceEscolher uma ou várias opções; properties.layout dropdown mostra uma resposta como lista suspensaum field multiple_choice com choices
picture_choiceEscolher imagensum field multiple_choice, choices com mediaId
rankingOrdenar opções, com pontos por posiçãoum field ranking com choices
ranked_choiceCédula de voto por ordem de preferência, com apuração por segundo turno instantâneoum field ranked_choice com choices
meetingEncontrar uma dataum field date por dia (label YYYY-MM-DD), um choice por horário (label 09:00-10:00 ou All day)
contentTexto, ou uma pergunta com properties.variant em yes_no, rating, scale, text, long_text, name, email ou word_cloudum field para a pergunta
contact_infoNome e endereço de e-mailfields text_small e email
page_break, welcome_screen, thank_you_screen, end_screen, redirectLayout e telas finaisnenhum

As configurações que valem para o formulário inteiro ficam em properties. As mais usadas:

PropriedadeValoresPadrão
resultsVisibilitypublic, public_after_response, public_after_close, privatepublic
responsesVisibilitypublic mostra os nomes junto aos resultados, private não, secret também não deixa você ver quem deu quais respostasprivate
responseDuplicateChecknone, session, ip, name, email, codeip
responseDuplicateCheckIntervalminutos até que a mesma pessoa possa responder de novo, ou nullnull
opensAt, closesAtcarimbos de data/hora ISO, ou nullnull
responseLimitnúmero máximo de respostas, ou nullnull
allowComments, commentsVisibilitytrue/false, public/privatefalse, private
editResponsePermissionsadmin_own_responses, own_responses, admin, nobodyadmin_own_responses
blockVPNUsers, useCaptchaVerificationtrue/falsetrue, false

A especificação OpenAPI lista todas as propriedades das seções, fields e choices.

Criar uma enquete

bash
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:

json
{
	"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-Key ou Authorization: Bearer sp_your_key.
FerramentaO que faz
create_pollUma pergunta com opções: uma votação, uma classificação ou uma enquete de reunião. Publicada.
create_formUm formulário com várias perguntas, de multiple_choice a matrix. Um rascunho.
publish_pollPublicar um rascunho.
list_pollsSuas enquetes, da mais recente à mais antiga, com o número de respostas.
get_resultsVotos por opção, posições médias, disponibilidade das enquetes de reunião e últimas respostas de texto.
set_poll_openEncerrar 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.

Assistentes sem ferramentas podem lhe dar um link que abre o editor com a enquete já preenchida, pronta para revisar e publicar:

undefined
https://strawpoll.com/forms/new?title=Onde%20vamos%20comer%3F&options=Pizza|Sushi|Tacos

options é 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/meO dono da chave e seus espaços de trabalho.

Formulários

GET/formsSeus formulários, do mais recente ao mais antigo. ?workspaceId= mostra os formulários de um espaço de trabalho.
POST/formsCriar 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}/draftSalvar title, themeId, properties e sections como rascunho.
DELETE/forms/{slug}/draftDescartar o rascunho.
POST/forms/{slug}/publishPublicar o rascunho. Um corpo com sections é salvo antes.

Respostas

GET/forms/{slug}/responsesAs respostas, da mais recente à mais antiga. limit (até 100) e offset.
DELETE/forms/{slug}/responsesRedefinir: 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.

json
{
	"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"
}
RespostaFormato
Perguntas de opções e de imagenslista de identificadores de choices, mais um texto se respostas livres forem permitidas
Classificaçãocada identificador de choice, o melhor primeiro
Voto por ordem de preferênciao identificador do choice em cada posição, o melhor primeiro, null para uma posição em branco
Enquete de reuniãopara 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 escalao número como string, por exemplo "4"
Campos de texto e dados de contatouma 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}/codesCódigos únicos.
POST/forms/{slug}/codesGerar count códigos de length caracteres, com style e prefix opcionais.
DELETE/forms/{slug}/codesExcluir códigos por ids.
GET/forms/{slug}/invitesConvites por e-mail.
POST/forms/{slug}/invitesAdicionar 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}/invitesExcluir convites por ids.
POST/forms/{slug}/invites/importConvidar todas as pessoas de uma lista de convidados (inviteListId).
POST/forms/{slug}/invites/sendEnviar 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/mediaEnviar uma imagem (file em multipart, até 5 MB). O id dela serve como mediaId de um choice.
GET/themesSeus temas, os dos seus espaços de trabalho e os temas integrados; ?workspaceId= para os de um espaço de trabalho.
POST/themesCriar 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ê.