概要
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キーでキーを作成します。キーは一度しか表示されないため、安全な場所に保管してください。 すべてのリクエストでキーを送信します:
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の本文で返されます:
{ "error": "This poll is closed.", "code": "closed" }errorは人が読むためのもの、code(ある場合)はコードで扱うためのものです。
| ステータス | 意味 |
|---|---|
| 400 | リクエストが無効です。投票のエラーでは、対象の質問もstepで示されます。 |
| 401 | APIキーがない、またはinvalid_api_key。 |
| 403 | このフォームを管理する権限がない、またはフォームがこの回答を受け付けません。 |
| 404 | 見つかりません。 |
| 409 | 競合。duplicate(重複した回答)など。 |
| 429 | rate_limited:Retry-Afterの秒数だけ待ってください。 |
| 503 | busy:大量の票が同時に届いています。少し待ってから再試行してください。 |
レート制限
キーごとに1分あたり120リクエストです。キーがない場合、ブラウザからのリクエストはログイン中のユーザーまたは
ブラウザ(投票者Cookie)ごとに数えられ、同じIPアドレスのすべてのブラウザを合わせて1分あたり最大3,000件までです。
どちらもないリクエストはIPアドレスごとに数えられます。各レスポンスでは、残りの枠がX-RateLimit-Limit、 X-RateLimit-Remaining、X-RateLimit-Reset(Unix秒)で示されます。
フォームの構造
フォームはsections(セクション)のリストです。質問のセクションはfields(フィールド)を持ち、 選択式のフィールドはchoices(選択肢)を持ちます。
セクションのtype | 内容 | Fields |
|---|---|---|
multiple_choice | 1つまたは複数の選択肢を選ぶ。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にあります。よく使うもの:
| プロパティ | 値 | デフォルト |
|---|---|---|
resultsVisibility | public、public_after_response、public_after_close、private | public |
responsesVisibility | publicは結果の横に名前を表示、privateは表示しない、secretは誰がどの回答をしたかをあなたからも隠す | private |
responseDuplicateCheck | none、session、ip、name、email、code | ip |
responseDuplicateCheckInterval | 同じ投票者が再び回答できるまでの分数、またはnull | null |
opensAt、closesAt | ISO形式のタイムスタンプ、またはnull | null |
responseLimit | 回答数の上限、または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 |
セクション、フィールド、選択肢のすべてのプロパティはOpenAPI仕様に記載されています。
投票を作成する
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"を指定しないと、フォームはあなただけが見られる下書きとして作成されます。
日程調整の投票では、セクションのタイムゾーンで日付ごとに時間帯を提示します:
{
"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_form | multiple_choiceからmatrixまで、複数の質問を持つアンケート。下書きとして作成。 |
publish_poll | 下書きを公開する。 |
list_polls | 自分の投票を新しい順に、回答数とともに一覧表示。 |
get_results | 選択肢ごとの票数、平均順位、日程調整の参加可否、最近のテキスト回答。 |
set_poll_open | 投票を締め切る、または再開する。 |
アシスタントが作った投票もほかの投票と同じくあなたのもので、新しい投票のデフォルト設定が使われます。 アシスタントが作成できるのは1時間あたり30件までです。
投票リンク
ツールを使えないアシスタントでも、投票の内容が入力済みの状態でエディターを開くリンクを渡せます。 確認して公開するだけです:
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%BCoptionsは|で区切られます(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}/draft | title、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のブロック、コード、メール認証)を適用します。ブラウザからはキー不要ですが、
スクリプトやその他の自動化されたクライアントはキーを送信する必要があります。
{
"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}/codes | length文字のコードをcount個生成。styleとprefixは任意。 |
DELETE/forms/{slug}/codes | idsで指定したコードを削除。 |
GET/forms/{slug}/invites | メール招待。 |
POST/forms/{slug}/invites | 招待を1件追加、またはinvitesで最大1000件追加。 |
PATCH/forms/{slug}/invites/{id} | 招待を変更。 |
DELETE/forms/{slug}/invites/{id} | 招待を削除。 |
DELETE/forms/{slug}/invites | idsで指定した招待を削除。 |
POST/forms/{slug}/invites/import | 招待リスト(inviteListId)の全員を招待。 |
POST/forms/{slug}/invites/send | subjectとmessageを付けて招待メールを送信。 |
招待メッセージでは、二重の波かっこで囲んだプレースホルダーname、form、linkを使えます。
メディアとテーマ
POST/media | 画像をアップロード(multipartのfile、最大5 MB)。そのidを選択肢のmediaIdとして使います。 |
GET/themes | 自分のテーマ、所属ワークスペースのテーマ、組み込みのテーマ。?workspaceId=で1つのワークスペースのテーマを表示。 |
POST/themes | nameと色のpropertiesでテーマを作成。workspaceIdを加えると、自分が所有または管理するワークスペースと共有できます。 |
PUT/themes/{id} | テーマを変更。workspaceIdでワークスペースと共有し、nullで所有者個人のテーマに戻します。 |
DELETE/themes/{id} | テーマを削除。ワークスペースのテーマは、そのオーナーと管理者が変更・削除できます。 |
Poll API(v3)からの移行
Poll API v3は、同じパス、キー、投票のまま引き続き動作します。何がどこに対応するかは v3互換ガイドをご覧ください。