Forms API

Überblick

Mit der Forms API (v4) erstellt dein eigener Code Umfragen und Formulare, veröffentlicht sie, sammelt Antworten und liest die Ergebnisse. Es ist dieselbe API, die auch der StrawPoll-Editor nutzt.

• Basis-URL: https://api.strawpoll.com/v4 (auch erreichbar unter https://strawpoll.com/api/v4)
• Format: JSON rein, JSON raus. Zeitstempel sind ISO-8601-Strings, IDs sind UUIDs.
• Maschinenlesbare Spezifikation: OpenAPI 3.1

Jedes Formular hat eine kurze öffentliche ID, den Slug, wie in https://strawpoll.com/r/AZPg4n1Td3-hnVAj6Q8p. Alle Formular-Endpunkte erwarten den Slug.

Authentifizierung

Erstelle unter Einstellungen → API-Schlüssel einen Schlüssel. Er wird nur einmal angezeigt, bewahre ihn also sicher auf. Schick ihn mit jeder Anfrage mit:

curl https://api.strawpoll.com/v4/me 
  -H "X-API-Key: sp_your_key"

Authorization: Bearer sp_your_key funktioniert ebenfalls. Ein Schlüssel handelt in deinem Namen: Er kann jedes Formular verwalten, das du im Dashboard verwalten kannst, auch in Workspaces, denen du angehörst. Löschst du einen Schlüssel in den Einstellungen, ist er sofort ungültig.

Die Endpunkte für Teilnehmende, submit und verify, brauchen aus einem Browser heraus keinen Schlüssel. Anfragen von Skripten, HTTP-Bibliotheken, Headless-Browsern, Bots und KI-Agenten, die am User-Agent erkannt werden, lehnen sie ohne Schlüssel mit automated ab.

Fehler

Fehler kommen mit dem passenden HTTP-Status und einem JSON-Body:

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

error richtet sich an Menschen, code (falls vorhanden) an deinen Code.

Ratenlimits

120 Anfragen pro Minute und Schlüssel. Ohne Schlüssel zählen Anfragen aus einem Browser pro angemeldetem Konto oder pro Browser (über sein Abstimmungs-Cookie), mit bis zu 3.000 pro Minute für alle Browser hinter einer IP-Adresse. Anfragen ohne beides zählen pro IP-Adresse. Jede Antwort meldet dein Kontingent in X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset (Unix-Sekunden).

Aufbau eines Formulars

Ein Formular ist eine Liste von Sections. Frage-Sections enthalten Fields, und Auswahlfelder enthalten Choices.

Einstellungen für das ganze Formular stehen in properties. Die wichtigsten:

Die OpenAPI-Spezifikation listet jede Property von Sections, Fields und Choices auf.

Eine Umfrage erstellen

curl https://api.strawpoll.com/v4/forms 
  -H "X-API-Key: sp_your_key" 
  -H "Content-Type: application/json" 
  -d '{
    "title": "Wo gehen wir mittagessen?",
    "status": "published",
    "properties": { "responseDuplicateCheck": "ip", "resultsVisibility": "public" },
    "sections": [{
      "type": "multiple_choice",
      "fields": [{
        "type": "multiple_choice",
        "label": "Wo gehen wir mittagessen?",
        "properties": { "isMultipleChoice": false },
        "choices": [{ "label": "Pizza" }, { "label": "Sushi" }, { "label": "Tacos" }]
      }]
    }]
  }'

Die Antwort ist das vollständige Formular mit erzeugten IDs und seinen Links in urls.formUrl und urls.resultsUrl. Ohne "status": "published" beginnt ein Formular als Entwurf, den nur du sehen kannst.

Eine Terminumfrage bietet Uhrzeiten an bestimmten Tagen an, in der Zeitzone der Section:

{
	"title": "Team-Meeting",
	"status": "published",
	"sections": [
		{
			"type": "meeting",
			"properties": { "timezone": "Europe/Berlin", "duration": 60, "location": "Raum 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" }] }
			]
		}
	]
}

KI-Assistenten (MCP)

StrawPoll betreibt einen Server für das Model Context Protocol. So können KI-Assistenten wie Claude, ChatGPT oder Cursor für dich Umfragen erstellen und Ergebnisse lesen.

• Server-URL: https://strawpoll.com/mcp (Streamable HTTP)
• Anmeldung: OAuth. Füge die URL in deinem Assistenten als eigenen Connector hinzu und melde dich bei StrawPoll an, wenn er danach fragt. Du entscheidest, ob du den Zugriff erlaubst. Clients ohne OAuth können stattdessen einen API-Schlüssel als X-API-Key oder Authorization: Bearer sp_your_key senden.

Umfragen eines Assistenten gehören dir wie jede andere und nutzen deine Standards für neue Umfragen. Ein Assistent kann bis zu 30 pro Stunde erstellen.

Umfragelinks

Assistenten ohne Tools können dir einen Link geben, der den Editor mit ausgefüllter Umfrage öffnet, bereit zum Prüfen und Veröffentlichen:

https://strawpoll.com/forms/new?title=Wo%20essen%20wir%3F&options=Pizza|Sushi|Tacos

options wird an | getrennt (oder wiederhole option=). Mit type=ranking oder type=meeting (Optionen wie 2026-11-03 oder 2026-11-03 14:00-15:00, dazu timezone=Europe/Berlin) wählst du den Typ, mit multiple=1 erlaubst du mehrere Antworten und mit other=1 eine eigene Antwort.

Endpunkte

Konto

Formulare

PUT ersetzt alles: Sections, Fields und Choices, die du weglässt, werden mitsamt ihren Antworten gelöscht. Schick die IDs der Teile zurück, die bleiben sollen, damit ihre Antworten erhalten bleiben. Von der Moderation entfernte Formulare (deleted, blocked) antworten mit 403.

Entwürfe und Veröffentlichen

Der Editor speichert Änderungen als Entwurf und veröffentlicht sie in einem Schritt. Bis dahin sehen Teilnehmende das veröffentlichte Formular.

Antworten

Die Summen pro Option stehen am Formular selbst: responseCount an jedem Field und jeder Choice, dazu score bei Rangfolgen. Das fields-Objekt einer Antwort enthält ihre Antworten in der Form, die unter Antwort abschicken beschrieben ist.

Antwort abschicken

POST/forms/{slug}/submit schickt eine Antwort so ab wie die Abstimmungsseite, mit allen Regeln des Formulars: Zeitplan, Limits, eine Antwort pro Person, Captcha, VPN-Sperre, Codes und E-Mail-Bestätigung. Browser brauchen keinen Schlüssel, Skripte und andere automatisierte Clients müssen einen senden.

{
	"fields": {
		"<ID des Auswahlfelds>": ["<Choice-ID>"],
		"<ID des Rangfolgefelds>": [
			"<ID der besten Choice>",
			"<nächste Choice-ID>",
			"<letzte Choice-ID>"
		],
		"<ID des Terminfelds>": [{ "choiceId": "<Choice-ID>", "status": "yes" }],
		"<ID des Ja/Nein-Felds>": "yes",
		"<ID des Textfelds>": "Freitext"
	},
	"name": "Ada",
	"comment": "Optional",
	"code": "Optionaler Einmalcode"
}

Eine erfolgreiche Antwort liefert die id der Antwort zurück. Ablehnungen tragen einen code: upcoming, closed, full, unavailable, decided, captcha, vpn, code, verify_email, disposable, automated (alle 403), duplicate (409) und busy (503).

Der Browser der teilnehmenden Person bekommt ein sp_voter-Cookie. Damit ändern PUT/forms/{slug}/submit und die id der Antwort genau diese Antwort, sofern das Formular Änderungen erlaubt.

Ist ein Formular auf eine Antwort pro E-Mail-Adresse begrenzt, bestätige die Adresse zuerst mit POST/forms/{slug}/verify: Schick action: "send" mit der email, danach action: "verify" mit dem sechsstelligen code, den die Person bekommen hat.

Codes und Einladungen

Einladungstexte können die Platzhalter name, form und link in doppelten geschweiften Klammern verwenden.

Medien und Designs

Umstieg von der Poll API (v3)

Die Poll API v3 funktioniert weiter, mit denselben Pfaden, Schlüsseln und Umfragen. Was wohin gehört, steht im Leitfaden zur v3-Kompatibilität.