開発者向け / APIリファレンス

Forms API

v4

自分のコードから投票やフォームを作成・公開し、回答を集めて結果を取得できます。

ベースURL
https://api.strawpoll.com/v4
仕様
OpenAPI 3

概要

Forms API(v4)を使うと、自分のコードから投票やフォームを作成・公開し、回答を集めて結果を取得できます。 StrawPollのエディター自体が使っているのと同じAPIです。

  • ベースURL: https://api.strawpoll.com/v4(https://strawpoll.com/api/v4でも利用可能)
  • 形式: 入力も出力もJSONです。タイムスタンプはISO 8601形式の文字列、IDはUUIDです。
  • 機械可読な仕様: OpenAPI 3.1

各フォームには短い公開ID、slugがあります(例:https://strawpoll.com/r/AZPg4n1Td3-hnVAj6Q8p)。 フォームのエンドポイントはすべてslugを受け取ります。

認証

設定 → APIキーでキーを作成します。キーは一度しか表示されないため、安全な場所に保管してください。 すべてのリクエストでキーを送信します:

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

Authorization: Bearer sp_your_keyでも送信できます。キーはあなた本人として動作し、ダッシュボードで管理できる すべてのフォーム(所属しているワークスペースのフォームを含む)を管理できます。 設定でキーを削除すると、すぐに無効になります。

回答者向けのエンドポイントであるsubmitとverifyは、ブラウザからならキーは不要です。スクリプト、HTTPライブラリ、 ヘッドレスブラウザ、ボット、AIエージェントからのリクエストはユーザーエージェントで識別され、キーを送信しない限り automatedで拒否されます。

エラー

エラーはHTTPステータスとJSONの本文で返されます:

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

errorは人が読むためのもの、code(ある場合)はコードで扱うためのものです。

ステータス意味
400リクエストが無効です。投票のエラーでは、対象の質問もstepで示されます。
401APIキーがない、またはinvalid_api_key。
403このフォームを管理する権限がない、またはフォームがこの回答を受け付けません。
404見つかりません。
409競合。duplicate(重複した回答)など。
429rate_limited:Retry-Afterの秒数だけ待ってください。
503busy:大量の票が同時に届いています。少し待ってから再試行してください。

レート制限

キーごとに1分あたり120リクエストです。キーがない場合、ブラウザからのリクエストはログイン中のユーザーまたは ブラウザ(投票者Cookie)ごとに数えられ、同じIPアドレスのすべてのブラウザを合わせて1分あたり最大3,000件までです。 どちらもないリクエストはIPアドレスごとに数えられます。各レスポンスでは、残りの枠がX-RateLimit-Limit、 X-RateLimit-Remaining、X-RateLimit-Reset(Unix秒)で示されます。

フォームの構造

フォームはsections(セクション)のリストです。質問のセクションはfields(フィールド)を持ち、 選択式のフィールドはchoices(選択肢)を持ちます。

セクションのtype内容Fields
multiple_choice1つまたは複数の選択肢を選ぶ。properties.layoutをdropdownにすると、1つを選ぶドロップダウンとして表示choicesを持つmultiple_choiceフィールド1つ
picture_choice画像を選ぶmultiple_choiceフィールド1つ、choicesにmediaId
ranking選択肢を並べ替える。順位ごとにポイントchoicesを持つrankingフィールド1つ
ranked_choice順位付け投票。即時決選投票(IRV)で集計choicesを持つranked_choiceフィールド1つ
meeting日程を調整する日ごとにdateフィールド1つ(label YYYY-MM-DD)、時間帯ごとにchoice 1つ(label 09:00-10:00またはAll day)
contentテキスト、またはproperties.variantをyes_no、rating、scale、text、long_text、name、email、word_cloudのいずれかにした質問1つ質問用のフィールド1つ
contact_info名前とメールアドレスtext_smallとemailのフィールド
page_break、welcome_screen、thank_you_screen、end_screen、redirectレイアウトと終了画面なし

フォーム全体の設定はpropertiesにあります。よく使うもの:

プロパティ値デフォルト
resultsVisibilitypublic、public_after_response、public_after_close、privatepublic
responsesVisibilitypublicは結果の横に名前を表示、privateは表示しない、secretは誰がどの回答をしたかをあなたからも隠すprivate
responseDuplicateChecknone、session、ip、name、email、codeip
responseDuplicateCheckInterval同じ投票者が再び回答できるまでの分数、またはnullnull
opensAt、closesAtISO形式のタイムスタンプ、またはnullnull
responseLimit回答数の上限、またはnullnull
allowComments、commentsVisibilitytrue/false、public/privatefalse、private
editResponsePermissionsadmin_own_responses、own_responses、admin、nobodyadmin_own_responses
blockVPNUsers、useCaptchaVerificationtrue/falsetrue、false

セクション、フィールド、選択肢のすべてのプロパティはOpenAPI仕様に記載されています。

投票を作成する

bash
curl https://api.strawpoll.com/v4/forms 
  -H "X-API-Key: sp_your_key" 
  -H "Content-Type: application/json" 
  -d '{
    "title": "お昼はどこにする?",
    "status": "published",
    "properties": { "responseDuplicateCheck": "ip", "resultsVisibility": "public" },
    "sections": [{
      "type": "multiple_choice",
      "fields": [{
        "type": "multiple_choice",
        "label": "お昼はどこにする?",
        "properties": { "isMultipleChoice": false },
        "choices": [{ "label": "ラーメン" }, { "label": "寿司" }, { "label": "カレー" }]
      }]
    }]
  }'

レスポンスは、生成されたIDを含むフォーム全体です。リンクはurls.formUrlとurls.resultsUrlにあります。 "status": "published"を指定しないと、フォームはあなただけが見られる下書きとして作成されます。

日程調整の投票では、セクションのタイムゾーンで日付ごとに時間帯を提示します:

json
{
	"title": "チーム定例",
	"status": "published",
	"sections": [
		{
			"type": "meeting",
			"properties": { "timezone": "Asia/Tokyo", "duration": 60, "location": "会議室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" }] }
			]
		}
	]
}

AIアシスタント(MCP)

StrawPollはModel Context Protocolサーバーを提供しているため、 Claude、ChatGPT、CursorなどのAIアシスタントがあなたの代わりに投票を作成し、結果を読み取れます。

  • サーバーURL: https://strawpoll.com/mcp(Streamable HTTP)
  • ログイン: OAuth。アシスタントでこのURLをカスタムコネクタとして追加し、求められたらStrawPollにログインします。 アクセスを許可するかどうかはあなたが選べます。OAuthに対応していないクライアントは、代わりにAPIキーを X-API-KeyまたはAuthorization: Bearer sp_your_keyで送信できます。
ツール機能
create_poll選択肢つきの質問1つ:投票、ランキング、または日程調整。公開状態で作成。
create_formmultiple_choiceからmatrixまで、複数の質問を持つアンケート。下書きとして作成。
publish_poll下書きを公開する。
list_polls自分の投票を新しい順に、回答数とともに一覧表示。
get_results選択肢ごとの票数、平均順位、日程調整の参加可否、最近のテキスト回答。
set_poll_open投票を締め切る、または再開する。

アシスタントが作った投票もほかの投票と同じくあなたのもので、新しい投票のデフォルト設定が使われます。 アシスタントが作成できるのは1時間あたり30件までです。

投票リンク

ツールを使えないアシスタントでも、投票の内容が入力済みの状態でエディターを開くリンクを渡せます。 確認して公開するだけです:

undefined
https://strawpoll.com/forms/new?title=%E3%81%8A%E6%98%BC%E3%81%AF%E3%81%A9%E3%81%93%E3%81%AB%E3%81%99%E3%82%8B%EF%BC%9F&options=%E3%83%A9%E3%83%BC%E3%83%A1%E3%83%B3|%E5%AF%BF%E5%8F%B8|%E3%82%AB%E3%83%AC%E3%83%BC

optionsは|で区切られます(option=を繰り返しても構いません)。type=rankingまたはtype=meeting (選択肢は2026-11-03や2026-11-03 14:00-15:00の形式で、timezone=Asia/Tokyoを添える)、複数回答を許可する multiple=1、自由回答を追加するother=1も指定できます。

エンドポイント

アカウント

GET/meキーの所有者と、その人のワークスペース。

フォーム

GET/forms自分のフォームを新しい順に表示。?workspaceId=でワークスペースのフォームを一覧表示。
POST/formsフォームを作成。workspaceIdは任意で、省略すると最初のワークスペースに作成されます。
GET/forms/{slug}公開中のフォーム。sections、fields、choices、集計を含みます。
PUT/forms/{slug}公開中のフォームを置き換える(下記参照)。
PATCH/forms/{slug}name、isOpen、propertiesだけを変更。
DELETE/forms/{slug}フォームとその回答を完全に削除。

PUTはすべてを置き換えます。送信しなかったsections、fields、choicesは、その回答とともに削除されます。 残したい部分のIDを送り返せば、その回答は保持されます。モデレーションで削除されたフォーム(deleted、blocked)は 403を返します。

下書きと公開

エディターは変更を下書きとして保存し、ワンステップで公開します。それまで回答者には公開中のフォームが表示され続けます。

PUT/forms/{slug}/drafttitle、themeId、properties、sectionsを下書きとして保存。
DELETE/forms/{slug}/draft下書きを破棄。
POST/forms/{slug}/publish下書きを公開。sectionsを含む本文を送ると、先に保存されます。

回答

GET/forms/{slug}/responses回答を新しい順に表示。limit(最大100)とoffset。
DELETE/forms/{slug}/responsesリセット:すべての回答を削除し、集計をゼロに戻します。

選択肢ごとの合計はフォーム自体にあります。各フィールドと各選択肢のresponseCount、ランキングではscoreです。 回答のfieldsには、回答を送信するで説明する形式で回答内容が入ります。

回答を送信する

POST/forms/{slug}/submitは、投票ページと同じように回答を送信し、フォームのすべてのルール(公開期間、上限、 1人1回答、CAPTCHA、VPNのブロック、コード、メール認証)を適用します。ブラウザからはキー不要ですが、 スクリプトやその他の自動化されたクライアントはキーを送信する必要があります。

json
{
	"fields": {
		"<選択式フィールドのID>": ["<選択肢のID>"],
		"<ランキングフィールドのID>": ["<1位の選択肢のID>", "<次の選択肢のID>", "<最下位の選択肢のID>"],
		"<日程調整の日付フィールドのID>": [{ "choiceId": "<選択肢のID>", "status": "yes" }],
		"<はい/いいえフィールドのID>": "yes",
		"<テキストフィールドのID>": "自由記述"
	},
	"name": "佐藤",
	"comment": "任意",
	"code": "任意のユニークコード"
}
回答形式
選択式・画像選択の質問選択肢IDのリスト。自由回答が許可されている場合はテキスト1つを追加
ランキングすべての選択肢ID、1位から順に
順位付け投票各順位の選択肢ID、1位から順に。空欄の順位はnull
日程調整日付フィールドごとに、choiceIdとstatus(yes、if_need_be、no)のリスト。nameは必須
はい/いいえ"yes"または"no"
評価・スケール数値を文字列で(例:"4")
テキスト・連絡先フィールド文字列

送信に成功すると、回答のidが返されます。拒否された場合はcodeが付きます:upcoming、 closed、full、unavailable、decided、captcha、vpn、code、verify_email、 disposable、automated(いずれも403)、duplicate(409)、busy(503)。

投票者のブラウザにはstrawpoll_session Cookieが設定されます。フォームで投票者による編集が許可されていれば、 このCookieと回答のidを使ってPUT/forms/{slug}/submitでその回答を変更できます。

メールアドレスごとに1回答に制限されたフォームでは、まずPOST/forms/{slug}/verifyでアドレスを確認します。 action: "send"とemailを送信し、次に投票者が受け取った6桁のcodeとともにaction: "verify"を送信します。

コードと招待

GET/forms/{slug}/codesユニークコード。
POST/forms/{slug}/codeslength文字のコードをcount個生成。styleとprefixは任意。
DELETE/forms/{slug}/codesidsで指定したコードを削除。
GET/forms/{slug}/invitesメール招待。
POST/forms/{slug}/invites招待を1件追加、またはinvitesで最大1000件追加。
PATCH/forms/{slug}/invites/{id}招待を変更。
DELETE/forms/{slug}/invites/{id}招待を削除。
DELETE/forms/{slug}/invitesidsで指定した招待を削除。
POST/forms/{slug}/invites/import招待リスト(inviteListId)の全員を招待。
POST/forms/{slug}/invites/sendsubjectとmessageを付けて招待メールを送信。

招待メッセージでは、二重の波かっこで囲んだプレースホルダーname、form、linkを使えます。

メディアとテーマ

POST/media画像をアップロード(multipartのfile、最大5 MB)。そのidを選択肢のmediaIdとして使います。
GET/themes自分のテーマ、所属ワークスペースのテーマ、組み込みのテーマ。?workspaceId=で1つのワークスペースのテーマを表示。
POST/themesnameと色のpropertiesでテーマを作成。workspaceIdを加えると、自分が所有または管理するワークスペースと共有できます。
PUT/themes/{id}テーマを変更。workspaceIdでワークスペースと共有し、nullで所有者個人のテーマに戻します。
DELETE/themes/{id}テーマを削除。ワークスペースのテーマは、そのオーナーと管理者が変更・削除できます。

Poll API(v3)からの移行

Poll API v3は、同じパス、キー、投票のまま引き続き動作します。何がどこに対応するかは v3互換ガイドをご覧ください。