Card Type
API type: POLL
Interactive survey or quiz card. Users vote on a question with 2–12 answer options. Supports anonymous voting, multiple choice, and configurable results visibility. Validated by the API — min 2 options, max 12.
Required fields
storyIdrequirednumberMix ID (must be STANDARD).
questionrequiredstringPoll question text. Max 360 chars.
optionsrequiredstring[]Answer options. Min 2, max 12. Each option max 100 chars. API rejects fewer than 2 or more than 12.
Optional fields
headlinestringCTA title shown on the card. Defaults to question text if not provided. Max 360 chars.
descriptionstringSupporting line displayed beneath the headline (maps to pollFields.text). Omit if not needed — never copy the question here.
multipleVotesbooleanAllow selecting multiple options. Default: false (single choice only).
allowAnonymousbooleanAllow anonymous voting. Default: true.
showVoteResultsbooleanShow vote results to participants. Default: true.
showTotalVotesbooleanShow total vote count. Default: true.
pollDurationnumberVoting duration in hours from now. Sets votingTime (ISO8601 deadline) — poll closes for new votes at that time.
imageUrlsstring[]Gallery image (1 for POLL). Resolved via storyCardParseUrl first, upload as fallback.
imageCaptionsstring[]Caption per image. Parallel to imageUrls. Plain text — no © prefix.
imageRightholdersstring[]Copyright holder per image (parallel array).
imageCopyrightStatusesenum[]Copyright status per image: CC, LICENSED, SUBLICENSED, UNKNOWN.
backgroundColorstringHex background color (e.g. #1a365d).
status / scheduledAt / allowComment / allowReaction / allowSharing / externalTagIds / internalTagIds / statusTagIdvariousStandard card settings.
Update-only fields
headline (POLL)string⚠️ The poll question/headline is not updatable — the API silently ignores headline changes on POLL updates, even before any vote (verified live). Delete and recreate the poll to change the question.
pollOptionsstring[]Replace poll options on update (min 2). Falls back to existing options if not provided. Locked once published or any vote cast.
pollIsAnonymous / pollIsMultipleChoicebooleanUpdate anonymous/multiple-choice settings. Falls back to existing values if not provided.
pollShowVoteResults / pollShowTotalVotesbooleanAlways updatable even after publishing. Falls back to existing values if not provided.
imageUrlstringReplace poll image on update (singular, unlike create which uses imageUrls[]). Locked once published.
API validation rules
| Rule | Value | Error if violated |
|---|
| Min options | 2 | StoryCardValidationError |
| Max options | 12 | StoryCardValidationError |
| Max question length | 360 chars | StoryCardValidationError |
| Max option length | 100 chars | StoryCardValidationError |
GraphQL fields object
pollFields: {
headline: String!, // required (NonNull) — the question / CTA title
text: String, // optional — supporting line beneath headline (omit if no separate description)
options: [ // required — 2–12 options
{ id: String!, text: String! }, // client-provided IDs (strings)
...
],
multipleVotes: Boolean, // optional, default false
allowAnonymous: Boolean, // optional, default true
showVoteResults: Boolean, // optional
showTotalVotes: Boolean, // optional
votingTime: String, // optional ISO8601 — voting deadline
styles: { backgroundColor: String } // optional
}
Content type (read back)
StoryCardPollContent {
headline // the question / CTA (prominent title)
text // optional supporting line beneath headline
options { id text }
multipleVotes
allowAnonymous
showVoteResults
showTotalVotes
votingTime
totalVotes // Int — total votes cast
selectedVoteIds // [String] — current user's selections (null if not voted)
voteResults { // [{ id, count }] — no text/percent, cross-ref options by ID
id count
}
styles { backgroundColor }
}
MCP example — create with all fields
{
"name": "create_card",
"arguments": {
"storyId": 61277,
"cardType": "POLL",
"question": "Which feature should we prioritise in Q3?",
"options": ["Better search", "Dark mode", "Mobile app", "API improvements"],
"headline": "Vote now — your input shapes our roadmap",
"description": "Select the feature you'd like to see shipped first.",
"multipleVotes": false,
"allowAnonymous": true,
"showVoteResults": true,
"showTotalVotes": true,
"pollDuration": 72,
"imageUrls": ["https://example.com/poll-cover.jpg"],
"imageCaptions": ["Q3 roadmap survey"],
"imageRightholders": ["Unsplash"],
"imageCopyrightStatuses": ["CC"],
"backgroundColor": "#1a365d",
"externalTagIds": [1027],
"statusTagId": 1056
}
}
Notes
Poll content locks when PUBLISHED (even with 0 votes). headline, options, multipleVotes, allowAnonymous, and the gallery image can only be changed while the card is UNPUBLISHED and has 0 votes. Once published, these fields are silently ignored on update. Always updatable regardless: showVoteResults, showTotalVotes, tags, and card settings.
Partial updates fully supported. update_card fetches the current card first — all existing values (headline, options, booleans, image, votingTime) are preserved as fallbacks. Only pass what you want to change.
Vote results are on the card. storyCardPollVote returns only a Boolean. Re-read the card after voting to get updated voteResults and totalVotes. voteResults[].count — no percentage, no option text. Cross-reference with options[] by ID.
pollDuration sets a deadline from now. Pass an integer (hours). Converts to an ISO8601 votingTime (current time + N hours). On update, existing deadline is preserved if pollDuration not passed.
storyCardPollVote input: uses storyCardId: Int! and selectedVoteIds: [String!]! — NOT itemId or selectedOptionIds.
