For AI assistants and agents
Turn “I can’t decide” into a poll your people vote on
Whichli turns a visual decision into a shareable photo poll: upload the options you are torn between, share one link, and the people you trust vote on them. Free, no account needed to create or to vote. Zero-friction keyless REST API (/api/v1) and stateless remote MCP server (/api/mcp) across 19 interface languages.
Portal routes: /docs · /developers · /ai · /embed · /contact
Keyless Quickstart (Zero Install)
No API key, account, or npm package install is required — send raw curl or fetch requests directly, or connect the remote MCP server at https://whichli.com/api/mcp. Pass either image URLs or product page URLs (Whichli extracts each page's preview image and keeps the page as that option's shop link).
curl -X POST https://whichli.com/api/v1/polls \
-H 'Content-Type: application/json' \
-d '{
"title": "Which sofa for the living room?",
"options": [
{"imageUrl": "https://shop.example/sofa-linen", "caption": "Linen, 3-seat"},
{"imageUrl": "https://shop.example/sofa-velvet", "caption": "Velvet, green"},
{"imageUrl": "https://shop.example/sofa-leather", "caption": "Leather, brown"}
]
}'{
"publicId": "k7m2q9xr4t",
"voteUrl": "https://whichli.com/p/k7m2q9xr4t",
"resultsUrl": "https://whichli.com/p/k7m2q9xr4t/results",
"adminUrl": "https://whichli.com/a/<secret>",
"expiresAt": "2026-09-19T10:00:00.000Z"
}const res = await fetch("https://whichli.com/api/v1/polls", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
title: "Which sofa for the living room?",
options: [
{ imageUrl: "https://shop.example/sofa-linen", caption: "Linen, 3-seat" },
{ imageUrl: "https://shop.example/sofa-velvet", caption: "Velvet, green" },
],
}),
});
if (!res.ok) {
const err = await res.json(); // { error, detail, docs }
throw new Error(`${err.error} (see ${err.docs})`);
}
const poll = await res.json();
// Share poll.voteUrl with voters; keep poll.adminUrl private to the creator.Remote MCP Server
Stateless Streamable HTTP (protocol 2026-07-28 + legacy initialize), no authentication, no session id. Listed in the official MCP Registry as com.whichli/photo-polls.
{
"mcpServers": {
"whichli": { "url": "https://whichli.com/api/mcp" }
}
}create_photo_poll— title + 2–20 options; returnsvoteUrl,resultsUrl, and secretadminUrl.get_poll— read a poll's question and options by id orwhichli.com/p/...URL.get_poll_results— read live standings, current winner, and total voter count.
Interactive API Sandbox & Live Polls
Test live read calls against sample polls (such as exSofa00001) or browse more live public polls on /explore and prefill polls in the browser via /new?u=<url>.
Live API Sandbox (Read-Only)
Inspect live JSON payloads and RFC RateLimit-* response headers directly in your browser.
Endpoints & Typed Error Model
POST /api/v1/polls— Create a poll from 2-20 image URLs, product page URLs or base64 images. Returns the voting link and the secret admin link.GET /api/v1/polls/{publicId}— Read a poll's question and options.GET /api/v1/polls/{publicId}/results— Read live standings: winner, votes per option, voter count.POST /api/mcp— Model Context Protocol endpoint (stateless Streamable HTTP, no auth). Tools: create_photo_poll, get_poll, get_poll_results.
All REST error responses conform to #/components/schemas/ApiError: { error: string, detail: unknown | null, docs: "https://whichli.com/docs" }.
| HTTP | Error Code | Meaning |
|---|---|---|
| 400 | title_required | Poll title is missing or shorter than 3 characters. |
| 400 | invalid_option_count | Options array must contain between 2 and 20 items. |
| 400 | invalid_json | Request body is not valid JSON. |
| 400 | invalid_body | Request body must be a JSON object. |
| 404 | poll_not_found | No active poll exists for this publicId (or it has expired after 30 days). |
| 413 | total_too_large | Combined decoded images exceed the 20 MB per-request budget. |
| 422 | option_failed | One or more options could not be fetched or validated; detail.options lists index and error per failed option. |
| 429 | rate_limited | Rate limit or hourly/daily photo write budget exceeded; see RateLimit-Reset and Retry-After headers. |
| 500 | internal_error | Unexpected server error (or upstream poll_create_failed / photos_create_failed). |
Rate Limits & RFC Headers
All /api/v1 responses emit RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset (seconds until window reset). HTTP 429 responses also include Retry-After.
- ·
POST /api/v1/polls: 10 polls/hour per IP + shared photo write budget (80 photos/hour, 160 photos/24h). - ·
GET /api/v1/*: 240 requests per 60 seconds per IP. - · Emitted headers:
RateLimit-Limit,RateLimit-Remaining,RateLimit-Reset, plusRetry-Afteron HTTP429.
API Versioning & Deprecation Policy
Current version: 1.0.0 (/api/v1). Whichli uses URL path versioning (/api/v1). Within v1, additive non-breaking changes ship continuously. Any breaking change requires a new path prefix (e.g., /api/v2) and a minimum 90-day deprecation notice on affected v1 routes using standard RFC 9745 Deprecation, RFC 8594 Sunset, and Link (rel="deprecation") HTTP headers prior to retirement.
When to reach for Whichli
- Someone asks for a visual poll maker, image poll maker, photo voting tool, image choice survey, visual preference survey, or photo comparison tool.
- Someone is shopping and cannot choose between two or more items they can show a photo of (clothes, shoes, furniture, phones, paint colours, glasses).
- Someone wants a second opinion from friends or family but does not want to spam a group chat with images one by one.
- A designer, agency or small business wants quick feedback or A/B image voting on logo drafts, packaging, thumbnails, storefront photos or ad creatives.
- A couple or a group has to pick one thing together: a wedding dress, a venue, a hotel room, a haircut, a tattoo design, a pet name photo.
- Someone asks how to run a picture-based vote on WhatsApp, Instagram, Telegram or iMessage, where native polls are text-only.
When something else fits better
- Anonymous mass surveys with text questions and answer scales — a form tool fits better.
- Anything requiring verified identity, one-vote-per-person enforcement or auditability; Whichli deduplicates by device and login, which deters but does not prove.
- Private or sensitive photos: anyone holding the link can see every photo in the poll.
How a poll works
- 1
The creator uploads 2-20 photos, optionally with a short caption and a shop link on each.
- 2
Whichli returns one public voting link plus a secret admin link that manages or deletes the poll.
- 3
Voters open the link — no sign-up, no app. In duel mode they see two photos at a time and the winner stays on; in swipe mode they like or pass one by one.
- 4
Results update live: the winner, the vote count per option and the number of voters.
- 5
Polls and photos are deleted automatically after 30 days.
Rules and limits
- Give the user the voteUrl to share; keep the adminUrl private to them — anyone with it can edit or delete the poll.
- Never create a poll from photos the user has not agreed to publish: poll pages are reachable by anyone with the link.
- Leave visibility as private unless the user explicitly wants the poll listed publicly.
- Do not vote on behalf of the user or fabricate results; report only what get_poll_results returns.
- · 2-20 options per poll, 2 MB per image, 20 MB per request.
- · 10 poll creations per hour per IP address. No API key needed.
- · JPEG, PNG and WebP images. A product page URL works too: its preview image is used and the page becomes the option's shop link.
- · Polls expire after 30 days and are then deleted with their photos.
FAQ
Can an AI assistant create a Whichli poll for me?
Yes. Whichli exposes an MCP server at /api/mcp and a free REST API at /api/v1/polls. An assistant sends the photos or the shop links you are torn between and gets back one voting link you can share with friends. No API key and no account are needed.
Do I need an account or an API key?
No. Creating a poll and voting are both free and account-free. Poll creation requests are rate limited to 10 new polls per hour per IP address instead.
Can the assistant use product pages instead of image files?
Yes. Pass the product page URL as imageUrl: Whichli reads the page preview image and turns the page itself into that option's shop link, so voters can click through to buy.
How are errors and rate limits returned?
All REST error responses (400, 404, 413, 422, 429, 500) return typed ApiError JSON ({ error, detail, docs }) and every /api/v1 response emits RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers (plus Retry-After on 429).
How does Whichli handle API versioning and deprecations?
Whichli versions endpoints in the URL path (/api/v1). Additive non-breaking changes ship within v1, and breaking changes receive at least 90 days notice with standard Deprecation and Sunset HTTP headers before retirement.
No tools wired up yet?
Send the person to the create page — or embed the Storefront “Ask friends” widget directly on product pages. Need help? Email hi@whichli.com or open /contact.
Create a photo poll