Introduzione
Con la Forms API (v4) il tuo codice crea sondaggi e moduli, li pubblica, raccoglie le risposte e legge i risultati. È la stessa API che usa l’editor di StrawPoll.
- URL di base:
https://api.strawpoll.com/v4(disponibile anche suhttps://strawpoll.com/api/v4) - Formato: JSON in entrata e in uscita. I timestamp sono stringhe ISO 8601, gli id sono UUID.
- Specifica leggibile da una macchina: OpenAPI 3.1
Ogni modulo ha un id pubblico breve, lo slug, come in https://strawpoll.com/r/AZPg4n1Td3-hnVAj6Q8p. Tutti gli endpoint dei moduli usano lo slug.
Autenticazione
Crea una chiave in Impostazioni → Chiavi API. Viene mostrata una sola volta: conservala in un posto sicuro. Inviala con ogni richiesta:
curl https://api.strawpoll.com/v4/me
-H "X-API-Key: sp_your_key"Funziona anche Authorization: Bearer sp_your_key. Una chiave agisce a tuo nome: può gestire
tutti i moduli che gestisci nella dashboard, compresi quelli degli spazi di lavoro di cui fai parte.
Elimina una chiave nelle impostazioni per revocarla subito.
Gli endpoint per i partecipanti, submit e verify, non richiedono una chiave da un browser. Le
richieste di script, librerie HTTP, browser headless, bot e agenti IA, riconosciuti dal loro user
agent, vengono rifiutate con automated se non inviano una chiave.
Errori
Gli errori usano lo stato HTTP e un corpo JSON:
{ "error": "This poll is closed.", "code": "closed" }error è scritto per le persone; code, quando presente, è pensato per il tuo codice.
| Stato | Significato |
|---|---|
| 400 | La richiesta non è valida. Gli errori di voto indicano anche la domanda in step. |
| 401 | Nessuna chiave API, oppure invalid_api_key. |
| 403 | Non puoi gestire questo modulo, oppure il modulo non accetta questa risposta. |
| 404 | Non trovato. |
| 409 | Conflitto, ad esempio una risposta duplicata (duplicate). |
| 429 | rate_limited: attendi i secondi indicati da Retry-After. |
| 503 | busy: stanno arrivando moltissimi voti nello stesso momento; riprova tra poco. |
Limiti di frequenza
120 richieste al minuto per chiave. Senza chiave, le richieste da un browser vengono contate per
utente che ha eseguito l’accesso o per browser (tramite il suo cookie di voto), fino a 3.000 al
minuto per tutti i browser dietro uno stesso indirizzo IP; le richieste senza nessuno dei due
vengono contate per indirizzo IP. Ogni risposta indica la tua quota in X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (secondi Unix).
Struttura di un modulo
Un modulo è un elenco di sections. Le sezioni con domande contengono fields, e i campi a scelta contengono choices.
type della sezione | Cosa chiede | Fields |
|---|---|---|
multiple_choice | Scegliere una o più opzioni; properties.layout dropdown mostra una risposta come menu a tendina | un field multiple_choice con choices |
picture_choice | Scegliere immagini | un field multiple_choice, choices con mediaId |
ranking | Ordinare le opzioni, con punti per posizione | un field ranking con choices |
ranked_choice | Scheda con voto a preferenza ordinata, conteggiata con ballottaggio istantaneo | un field ranked_choice con choices |
meeting | Trovare un orario | un field date per giorno (label YYYY-MM-DD), un choice per fascia oraria (label 09:00-10:00 o All day) |
content | Testo, oppure una domanda con properties.variant impostato su yes_no, rating, scale, text, long_text, name, email o word_cloud | un field per la domanda |
contact_info | Nome e indirizzo email | fields text_small ed email |
page_break, welcome_screen, thank_you_screen, end_screen, redirect | Impaginazione e schermate finali | nessuno |
Le impostazioni valide per tutto il modulo si trovano in properties. Le più usate:
| Proprietà | Valori | Predefinito |
|---|---|---|
resultsVisibility | public, public_after_response, public_after_close, private | public |
responsesVisibility | public mostra i nomi accanto ai risultati, private no, secret nasconde anche a te chi ha dato quali risposte | private |
responseDuplicateCheck | none, session, ip, name, email, code | ip |
responseDuplicateCheckInterval | minuti prima che lo stesso partecipante possa rispondere di nuovo, o null | null |
opensAt, closesAt | timestamp ISO, o null | null |
responseLimit | numero massimo di risposte, o 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 |
La specifica OpenAPI elenca tutte le proprietà di sections, fields e choices.
Creare un sondaggio
curl https://api.strawpoll.com/v4/forms
-H "X-API-Key: sp_your_key"
-H "Content-Type: application/json"
-d '{
"title": "Dove andiamo a pranzo?",
"status": "published",
"properties": { "responseDuplicateCheck": "ip", "resultsVisibility": "public" },
"sections": [{
"type": "multiple_choice",
"fields": [{
"type": "multiple_choice",
"label": "Dove andiamo a pranzo?",
"properties": { "isMultipleChoice": false },
"choices": [{ "label": "Pizza" }, { "label": "Sushi" }, { "label": "Tacos" }]
}]
}]
}'La risposta contiene il modulo completo, con gli id generati e i suoi link in urls.formUrl e urls.resultsUrl. Senza "status": "published" un modulo nasce come bozza, visibile solo a te.
Un sondaggio per riunioni propone orari in determinate date, nel fuso orario della sezione:
{
"title": "Riunione di team",
"status": "published",
"sections": [
{
"type": "meeting",
"properties": { "timezone": "Europe/Rome", "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" }] }
]
}
]
}Assistenti IA (MCP)
StrawPoll offre un server Model Context Protocol: così assistenti IA come Claude, ChatGPT o Cursor possono creare sondaggi e leggere i risultati per te.
- URL del server:
https://strawpoll.com/mcp(Streamable HTTP) - Accesso: OAuth. Aggiungi l’URL come connettore personalizzato nel tuo assistente e accedi a
StrawPoll quando te lo chiede; sei tu a decidere se autorizzarlo. I client senza OAuth possono
invece inviare una chiave API come
X-API-KeyoAuthorization: Bearer sp_your_key.
| Strumento | Cosa fa |
|---|---|
create_poll | Una domanda con opzioni: una votazione, una classifica o un sondaggio per riunioni. Pubblicato. |
create_form | Un questionario con più domande, da multiple_choice a matrix. Una bozza. |
publish_poll | Pubblica una bozza. |
list_polls | I tuoi sondaggi, dal più recente, con il numero di risposte. |
get_results | Voti per opzione, posizioni medie, disponibilità nei sondaggi per riunioni e ultime risposte di testo. |
set_poll_open | Chiude un sondaggio o lo riapre. |
I sondaggi creati da un assistente sono tuoi come tutti gli altri e usano le tue impostazioni predefinite per i nuovi sondaggi. Un assistente può crearne fino a 30 all’ora.
Link ai sondaggi
Gli assistenti senza strumenti possono darti un link che apre l’editor con il sondaggio già compilato, pronto da controllare e pubblicare:
https://strawpoll.com/forms/new?title=Dove%20andiamo%20a%20pranzo%3F&options=Pizza|Sushi|Tacosoptions viene diviso su | (oppure ripeti option=). Aggiungi type=ranking o type=meeting (opzioni come 2026-11-03 o 2026-11-03 14:00-15:00, con timezone=Europe/Rome), multiple=1 per consentire più risposte e other=1 per una risposta libera.
Endpoint
Account
GET/me | Il proprietario della chiave e i suoi spazi di lavoro. |
Moduli
GET/forms | I tuoi moduli, dal più recente. ?workspaceId= elenca i moduli di uno spazio di lavoro. |
POST/forms | Crea un modulo. workspaceId facoltativo; per impostazione predefinita, il tuo primo spazio di lavoro. |
GET/forms/{slug} | Il modulo pubblicato, con sections, fields, choices e conteggi. |
PUT/forms/{slug} | Sostituisce il modulo pubblicato (vedi sotto). |
PATCH/forms/{slug} | Modifica solo name, isOpen o properties. |
DELETE/forms/{slug} | Elimina definitivamente il modulo e le sue risposte. |
PUT sostituisce tutto: le sections, i fields e i choices che ometti vengono eliminati, insieme
alle loro risposte. Rinvia gli id degli elementi che vuoi mantenere, così le loro risposte
restano. I moduli rimossi dalla moderazione (deleted, blocked) rispondono 403.
Bozze e pubblicazione
L’editor salva le modifiche come bozza e le pubblica in un solo passaggio. Fino ad allora i partecipanti continuano a vedere il modulo pubblicato.
PUT/forms/{slug}/draft | Salva title, themeId, properties e sections come bozza. |
DELETE/forms/{slug}/draft | Scarta la bozza. |
POST/forms/{slug}/publish | Pubblica la bozza. Un corpo con sections viene salvato prima. |
Risposte
GET/forms/{slug}/responses | Le risposte, dalla più recente. limit (fino a 100) e offset. |
DELETE/forms/{slug}/responses | Reimposta: elimina tutte le risposte e riporta i conteggi a zero. |
I totali per opzione si trovano nel modulo stesso: responseCount su ogni field e ogni choice, e score per le classifiche. L’oggetto fields di una risposta contiene le sue risposte nella
forma descritta in Inviare una risposta.
Inviare una risposta
POST/forms/{slug}/submit invia una risposta come fa la pagina di voto, applicando tutte le
regole del modulo: programmazione, limiti, una risposta per persona, captcha, blocco VPN, codici e
verifica dell’email. I browser non hanno bisogno di una chiave; gli script e gli altri client
automatizzati devono inviarne una.
{
"fields": {
"<id del campo a scelta>": ["<id del choice>"],
"<id del campo di classifica>": [
"<id del choice migliore>",
"<id del choice successivo>",
"<id dell’ultimo choice>"
],
"<id del campo data della riunione>": [{ "choiceId": "<id del choice>", "status": "yes" }],
"<id del campo sì/no>": "yes",
"<id del campo di testo>": "Testo libero"
},
"name": "Ada",
"comment": "Facoltativo",
"code": "Codice univoco facoltativo"
}| Risposta | Forma |
|---|---|
| Domande a scelta e con immagini | elenco di id dei choices, più un testo se sono consentite risposte libere |
| Classifica | ogni id dei choices, dal migliore |
| Voto a preferenza ordinata | l’id del choice in ogni posizione, dal migliore, null per una posizione lasciata vuota |
| Sondaggio per riunioni | per ogni field data, un elenco di choiceId e status (yes, if_need_be, no); name è obbligatorio |
| Sì/no | "yes" o "no" |
| Valutazione e scala | il numero come stringa, ad esempio "4" |
| Campi di testo e di contatto | una stringa |
Un invio riuscito restituisce l’id della risposta. I rifiuti riportano un code: upcoming, closed, full, unavailable, decided, captcha, vpn, code, verify_email, disposable, automated (tutti 403), duplicate (409) e busy (503).
Il browser del partecipante riceve un cookie strawpoll_session. Con questo cookie, PUT/forms/{slug}/submit e l’id della risposta modificano quella risposta, se il modulo
consente ai partecipanti di modificarla.
Per i moduli limitati a una risposta per indirizzo email, verifica prima l’indirizzo con POST/forms/{slug}/verify: invia action: "send" e l’email, poi action: "verify" con il code di 6 cifre ricevuto dal partecipante.
Codici e inviti
GET/forms/{slug}/codes | Codici univoci. |
POST/forms/{slug}/codes | Genera count codici di length caratteri, con style e prefix facoltativi. |
DELETE/forms/{slug}/codes | Elimina i codici indicati in ids. |
GET/forms/{slug}/invites | Inviti via email. |
POST/forms/{slug}/invites | Aggiunge un invito, o fino a 1000 tramite invites. |
PATCH/forms/{slug}/invites/{id} | Modifica un invito. |
DELETE/forms/{slug}/invites/{id} | Elimina un invito. |
DELETE/forms/{slug}/invites | Elimina gli inviti indicati in ids. |
POST/forms/{slug}/invites/import | Invita tutte le persone di una lista di invitati (inviteListId). |
POST/forms/{slug}/invites/send | Invia gli inviti via email con subject e message. |
I messaggi di invito possono usare i segnaposto name, form e link tra doppie parentesi graffe.
Media e temi
POST/media | Carica un’immagine (file multipart, fino a 5 MB). Usa il suo id come mediaId di un choice. |
GET/themes | I tuoi temi, quelli dei tuoi spazi di lavoro e quelli integrati; ?workspaceId= per quelli di uno spazio di lavoro. |
POST/themes | Crea un tema con name e properties di colore; aggiungi workspaceId per condividerlo con uno spazio di lavoro che possiedi o gestisci. |
PUT/themes/{id} | Modifica un tema. workspaceId lo condivide con uno spazio di lavoro; null lo riporta al solo proprietario. |
DELETE/themes/{id} | Elimina un tema. I temi di uno spazio di lavoro possono essere modificati ed eliminati dal proprietario e dagli amministratori. |
Passare dalla Poll API (v3)
La Poll API v3 continua a funzionare, con gli stessi percorsi, le stesse chiavi e gli stessi sondaggi. La guida alla compatibilità v3 spiega cosa corrisponde a cosa.