개요
Forms API(v4)를 사용하면 직접 작성한 코드로 투표와 폼을 만들고, 게시하고, 응답을 수집하고, 결과를 읽을 수 있습니다. StrawPoll 에디터도 같은 API를 사용합니다.
- 기본 URL:
https://api.strawpoll.com/v4(https://strawpoll.com/api/v4에서도 제공) - 형식: 요청과 응답 모두 JSON입니다. 타임스탬프는 ISO 8601 문자열이고, id는 UUID입니다.
- 기계 판독용 명세: OpenAPI 3.1
모든 폼에는 https://strawpoll.com/r/AZPg4n1Td3-hnVAj6Q8p처럼 짧은 공개 id인 slug가
있습니다. 모든 폼 엔드포인트는 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 에이전트의 요청은 user agent로
식별되며, 키를 보내지 않으면 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: 한꺼번에 많은 표가 들어오고 있습니다. 잠시 후 다시 시도하세요. |
속도 제한
키당 분당 120회 요청할 수 있습니다. 키 없이 브라우저에서 보낸 요청은 로그인한 사용자 또는
브라우저(투표자 쿠키) 단위로 계산되며, 한 IP 주소의 모든 브라우저를 합쳐 분당 최대
3,000회입니다. 둘 다 없는 요청은 IP 주소 단위로 계산됩니다. 모든 응답은 남은 한도를 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset(Unix 초)으로 알려 줍니다.
폼의 구조
폼은 sections의 목록입니다. 질문 섹션에는 fields가 있고, 선택형 필드에는 choices가 있습니다.
섹션 type | 묻는 내용 | Fields |
|---|---|---|
multiple_choice | 선택지를 하나 이상 고릅니다. properties.layout을 dropdown으로 하면 답변 하나를 드롭다운으로 표시합니다 | choices가 있는 multiple_choice 필드 하나 |
picture_choice | 이미지를 고릅니다 | multiple_choice 필드 하나, choices에 mediaId |
ranking | 선택지의 순서를 정하고, 순위마다 점수를 매깁니다 | choices가 있는 ranking 필드 하나 |
ranked_choice | 순위 선택 투표용지로, 즉석 결선(instant runoff) 방식으로 집계합니다 | choices가 있는 ranked_choice 필드 하나 |
meeting | 가능한 시간을 찾습니다 | 날짜마다 date 필드 하나(label YYYY-MM-DD), 시간마다 choice 하나(label 09:00-10:00 또는 All day) |
content | 텍스트, 또는 properties.variant가 yes_no, rating, scale, text, long_text, name, email, word_cloud 중 하나인 질문 하나 | 질문용 필드 하나 |
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 |
섹션, 필드, choice의 모든 속성은 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/Seoul", "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를 지원하지 않는 클라이언트는
대신
X-API-Key또는Authorization: Bearer sp_your_key로 API 키를 보낼 수 있습니다.
| 도구 | 기능 |
|---|---|
create_poll | 선택지가 있는 질문 하나: 일반 투표, 순위 질문 또는 일정 조율 투표. 바로 게시됩니다. |
create_form | multiple_choice부터 matrix까지 여러 질문이 있는 설문조사. 초안으로 만들어집니다. |
publish_poll | 초안을 게시합니다. |
list_polls | 내 투표를 최신순으로, 응답 수와 함께 보여 줍니다. |
get_results | 선택지별 득표, 평균 순위, 일정 조율 가능 여부, 최근 텍스트 답변. |
set_poll_open | 투표를 마감하거나 다시 엽니다. |
어시스턴트가 만든 투표도 다른 투표와 똑같이 본인 소유이며, 새 투표의 기본 설정을 따릅니다. 어시스턴트는 시간당 최대 30개까지 만들 수 있습니다.
투표 링크
도구를 쓸 수 없는 어시스턴트는 투표 내용이 채워진 에디터를 여는 링크를 건넬 수 있습니다. 확인한 뒤 바로 게시하면 됩니다.
https://strawpoll.com/forms/new?title=점심%20뭐%20먹을까요%3F&options=피자|초밥|타코options는 |로 나뉩니다(또는 option=을 반복하세요). type=ranking 또는 type=meeting (선택지는 2026-11-03 또는 2026-11-03 14:00-15:00 형식, timezone=Asia/Seoul과 함께),
여러 답변을 허용하려면 multiple=1, 직접 입력 답변을 받으려면 other=1을 추가하세요.
엔드포인트
계정
GET/me | 키 소유자와 소속 워크스페이스. |
폼
GET/forms | 내 폼을 최신순으로 반환합니다. ?workspaceId=를 붙이면 해당 워크스페이스의 폼을 반환합니다. |
POST/forms | 폼을 만듭니다. workspaceId는 선택이며, 기본값은 첫 번째 워크스페이스입니다. |
GET/forms/{slug} | 섹션, 필드, choice, 집계가 포함된 게시 중인 폼. |
PUT/forms/{slug} | 게시 중인 폼을 교체합니다(아래 참고). |
PATCH/forms/{slug} | name, isOpen, properties만 변경합니다. |
DELETE/forms/{slug} | 폼과 응답을 영구 삭제합니다. |
PUT은 모든 것을 교체합니다. 보내지 않은 섹션, 필드, choice는 해당 답변과 함께 삭제됩니다.
유지할 항목의 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 | 초기화: 모든 응답을 삭제하고 집계를 0으로 되돌립니다. |
선택지별 합계는 폼 자체에 있습니다. 각 필드와 choice의 responseCount, 순위 질문의 score를
확인하세요. 응답의 fields에는 응답 제출에서 설명한 형태로 답변이 담겨
있습니다.
응답 제출
POST/forms/{slug}/submit은 투표 페이지와 똑같이 응답을 보내며, 폼의 모든 규칙을
적용합니다. 일정, 한도, 1인 1응답, 캡차, VPN 차단, 코드, 이메일 인증이 모두 포함됩니다.
브라우저는 키가 필요 없지만, 스크립트와 기타 자동화 클라이언트는 키를 보내야 합니다.
{
"fields": {
"<선택형 필드 id>": ["<choice id>"],
"<순위 필드 id>": ["<1순위 choice id>", "<다음 choice id>", "<마지막 choice id>"],
"<일정 날짜 필드 id>": [{ "choiceId": "<choice id>", "status": "yes" }],
"<예/아니요 필드 id>": "yes",
"<텍스트 필드 id>": "자유 텍스트"
},
"name": "지민",
"comment": "선택 사항",
"code": "고유 코드(선택 사항)"
}| 답변 | 형태 |
|---|---|
| 선택형 및 이미지 질문 | choice id 목록. 직접 입력이 허용되면 텍스트 하나 추가 |
| 순위 질문 | 모든 choice id, 1순위부터 |
| 순위 선택 투표 | 순위별 choice 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 쿠키를 받습니다. 폼이 투표자의 수정을 허용하면, 이
쿠키와 응답 id로 PUT/forms/{slug}/submit을 호출해 해당 응답을 변경할 수 있습니다.
이메일 주소당 응답 하나로 제한된 폼은 먼저 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 | 초대를 하나 추가하거나, 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를 choice의 mediaId로 사용하세요. |
GET/themes | 내 테마, 내 워크스페이스의 테마, 기본 제공 테마. 워크스페이스 하나의 테마만 보려면 ?workspaceId=를 붙이세요. |
POST/themes | name과 색상 properties로 테마를 만듭니다. 소유하거나 관리하는 워크스페이스와 공유하려면 workspaceId를 추가하세요. |
PUT/themes/{id} | 테마를 변경합니다. workspaceId를 지정하면 워크스페이스와 공유하고, null이면 다시 소유자 개인 테마가 됩니다. |
DELETE/themes/{id} | 테마를 삭제합니다. 워크스페이스 테마는 해당 워크스페이스의 소유자와 관리자가 변경하고 삭제할 수 있습니다. |
Poll API(v3)에서 옮겨 오기
Poll API v3는 같은 경로, 키, 투표로 계속 동작합니다. 무엇이 어디에 대응하는지는 v3 호환성 가이드를 참고하세요.