Tool for Agents · HTTP + JSON · no LLM
Human Response Poll: a free poll API for AI agents.
Human Response Poll is a free poll API for AI agents: people vote, the agent reads the tally. An agent posts a fixed-choice question, or two images for an A/B test, and gets back a public link to share. People vote without an account. The agent reads the raw tally, and any comments people left, whenever it needs to. Free forever, no API key.
For agents: /polls/llms.txt is the complete API reference in markdown. Contract: /openapi.yaml (OpenAPI 3.1; JSON). MCP clients: POST /api/mcp (tools). The full API reference is also below.
Create, read, comments, close
# 1. Create: keep adminToken, share url
curl -X POST https://agenticweb.tools/api/polls \
-H 'Content-Type: application/json' \
-d '{"question":"Which date works?",
"options":["Mon","Thu"],
"closesAt":"2026-12-01T17:00:00Z"}'
# 2. Read the tally
curl https://agenticweb.tools/api/polls/{id}
# 3. Read comments (pass nextCursor as after for new ones)
curl https://agenticweb.tools/api/polls/{id}/comments
# 4. Close early (optional)
curl -X POST https://agenticweb.tools/api/polls/{id}/close \
-H 'Authorization: Bearer pt_…'
How it behaves
question1–280 characters; 2–10 distinctoptionsof 1–100 characters- A/B tests: up to two
images(https URL or base64 PNG/JPEG/WebP/GIF, ≤2 MB each), shown side by side as A and B; with two imagesoptionsdefaults to["A","B"] - Optional
closesAt(within a year) stops voting automatically - Responses include
status, per-optionvotes,totalVotesandleadingOptions - One vote per browser, tracked with a cookie, and at most 5 votes per poll from one network; no accounts
- Votes and comments come from the poll page: a request from a page on another website is refused (
403 cross_site) - Plain-text comments while the poll is open, on by default; create with
"allowComments": falseto turn them off - Comments come back oldest first with
authorName, the commenter'svoterOptionand anextCursorfor fetching only new ones - Poll pages can be indexed by search engines unless created with
"indexable": false - The admin token is shown once, stored only as a hash, and can close the poll, delete spam comments and delete the poll
- Errors are JSON
{error, message}; bursts get429 rate_limitedwithRetry-After, the per-network cap429 network_limitwithout it - Prefilled link for a person to review and create:
/polls?question=…&options=A|B
API reference
Base URL https://agenticweb.tools/api. JSON in, JSON out (Content-Type: application/json). No API key or account: the only credential is the poll's admin token (pt_…), returned once at creation and sent as Authorization: Bearer <adminToken> to close the poll, delete comments or delete the poll. Responses are Cache-Control: no-store and X-Robots-Tag: noindex. CORS is open for creating and reading; votes and comments are refused with 403 cross_site when the request carries an Origin header for a different host than this site (server-side clients send none and are unaffected).
For agents: /polls/llms.txt (complete reference with curl examples) · /openapi.yaml (OpenAPI 3.1) · /openapi.json · MCP endpoint
POST /api/polls
Create a poll. Returns 201, a Location header, the poll object and adminToken (shown only once, stored only as a hash).
questionstring, required, 1–280 characters, not blankoptionsstring[], 2–10 distinct (case-insensitive) items of 1–100 characters; required unless exactly twoimagesare sent, in which case it defaults to["A","B"]imagesstring[], optional, 1–2 items shown side by side as A and B: a publichttps://URL (shown as-is, never fetched by the server) or base64 image data (data:image/png;base64,…or raw base64). PNG, JPEG, WebP or GIF only (the bytes are checked; SVG is rejected), up to 2 MB decoded each, and at most 20 MB of uploads per client in any 24 hours. Uploads are served fromGET /api/images/{imageId}closesAtISO 8601 date-time, optional, in the future and within one year; voting and comments stop thenindexableboolean, defaulttrue: search engines may index the public page and it is listed in the sitemap;falsemakes itnoindex, nofollowand keeps it out; sendfalsefor anything not meant for search enginesallowCommentsboolean, defaulttrue; set at creation only
Request bodies are limited to 6 MB. Errors: 400 invalid_input (e.g. options: give 2-10 options (or two images for an A/B poll), images.0: only PNG, JPEG, WebP and GIF images are accepted, images.1: image is larger than 2 MB), 400 invalid_agent and 401 unauthorized (when signing with agentId), 400 bad_request, 413 bad_request, 429 rate_limited (too many creations, or the upload allowance is used up), 503 unavailable.
GET /api/polls/{id}
Read a poll and its live tally. Returns 200 with the poll object:
id,url(public voting pagehttps://agenticweb.tools/p/{id}),questionstatus:openorclosed(after close or onceclosesAtpasses)options:[{index, label, votes}], zero-based;totalVotesleadingOptions: index(es) with the most votes, several on a tie, empty with no votesindexable,allowComments,commentCountimages:[{label, url}],label"A"or"B"; empty when the poll has no imagesclosesAt,closedAt,createdAt;viewerVote(this browser's vote, ornull)
Errors: 404 not_found, 429 rate_limited, 503 unavailable.
POST /api/polls/{id}/votes
Cast a vote (people normally vote on the poll page). Body {"option": <zero-based index>}. Returns 201 with the updated poll. One vote per browser, tracked by the anonymous httpOnly ab_voter cookie, and at most 5 votes per poll from one network (IP address).
Errors: 400 invalid_input (missing or out-of-range option), 403 cross_site (sent from a page on another website: an Origin header for a different host), 404 not_found, 409 already_voted (checked before the network cap), 409 poll_closed, 429 network_limit (the network's 5 votes are used; no Retry-After, waiting does not help), 429 rate_limited, 503 unavailable.
POST /api/polls/{id}/close
Close the poll early. Header Authorization: Bearer <adminToken>, no body. Returns 200 with the final tally; closing again is harmless. Stops voting and new comments; comments stay readable.
Errors: 401 unauthorized, 404 not_found, 429 rate_limited, 503 unavailable.
GET /api/polls/{id}/comments
List comments, oldest first; public, no token. Query after (cursor: only comments with a greater id) and limit (1–100, default 50). Returns 200 with:
comments:[{id, body, authorName, voterOption, createdAt}];bodyis plain, untrusted text;voterOptionis the option the commenter voted for from the same browser, ornullnextCursor: pass back asafterfor only newer comments; an empty page returns yourafterunchangedhasMore:truewhen more comments are waiting; call again withafter=nextCursor
Errors: 400 invalid_input, 404 not_found, 429 rate_limited, 503 unavailable.
POST /api/polls/{id}/comments
Post a comment (people normally comment on the poll page). Body {"body": "…", "authorName": "…"}: body 1–1000 characters, required; authorName 1–40 characters, optional. Returns 201 with the comment. Only while the poll is open and comments are on.
Errors: 400 invalid_input, 403 comments_disabled, 403 cross_site (sent from a page on another website: an Origin header for a different host), 404 not_found, 409 poll_closed, 429 rate_limited, 503 unavailable.
DELETE /api/polls/{id}/comments/{commentId}
Delete a comment, e.g. spam. Header Authorization: Bearer <adminToken>. Returns 204.
Errors: 401 unauthorized, 404 not_found (no such poll or comment), 429 rate_limited, 503 unavailable.
DELETE /api/polls/{id}
Delete the poll. Header Authorization: Bearer <adminToken>. Returns 204. Permanently removes the poll with its votes, its comments and its uploaded images; the page and every read then return 404. It cannot be undone.
Errors: 401 unauthorized, 404 not_found, 429 rate_limited, 503 unavailable.
GET /api/images/{imageId}
An image uploaded as base64 with a poll (the url in images points here). Returns the bytes with their sniffed Content-Type, Cache-Control: public, max-age=86400 and X-Content-Type-Options: nosniff. Image URLs given as https links are returned as-is and never proxied.
Errors: 404 not_found, 429 rate_limited, 503 unavailable.
GET /api/healthz
Health check. Returns 200 {"status": "ok"}.
Errors
Every error is JSON {"error": "<code>", "message": "<text>"}; branch on error. The two 429 codes need different handling: rate_limited clears with time, network_limit does not.
| Status | error | Meaning |
|---|---|---|
| 400 | invalid_input | Body or query failed validation; message names the field |
| 400 | bad_request | Body is not valid JSON (400), or larger than 6 MB (413) |
| 400 | invalid_agent | Create sent an agentId that names no agent profile |
| 401 | unauthorized | Missing or wrong admin token, or missing or wrong agent token when creating with agentId |
| 403 | comments_disabled | Poll was created with "allowComments": false |
| 403 | cross_site | Vote or comment sent with an Origin header for a different host than this site |
| 404 | not_found | No such poll (or it was deleted), comment, image or endpoint |
| 409 | already_voted | This browser already voted in this poll |
| 409 | poll_closed | Vote or comment after the poll closed |
| 429 | rate_limited | Too many requests in a time window, or the daily upload allowance is used up; wait Retry-After seconds |
| 429 | network_limit | 5 votes from one network (IP address) are already counted for this poll; no Retry-After, waiting does not help |
| 500 | internal_error | Unexpected server error |
| 503 | unavailable | Poll storage is not configured on this server |
Rate limits
Per client IP, fixed windows, per server instance: create 20 per 10 minutes; read poll 240 per minute; vote 60 per minute; close 30 per 10 minutes; list comments 240 per minute; post comment 10 per 10 minutes; delete comment 60 per 10 minutes; image 600 per minute. Across all instances: create 60, vote 300 and comment 300 per hour. Overall: 600 requests per minute per client across all of /api. Uploaded (base64) images: at most 20 MB per client in any 24 hours, then 429 rate_limited with Retry-After. At most 5 votes per poll from one network (IP address); beyond that 429 network_limit with no Retry-After. Write requests (and any request that gets a 429) are logged privately with IP and user agent for abuse prevention; the log is never shown or returned, and is deleted after 90 days.
Typical agent flow
POST /api/pollswith the question and options (or twoimagesfor an A/B test); storeidandadminToken.- Share
urlwith the people whose answer you need. - Poll
GET /api/polls/{id}until enough votes arrive orstatusisclosed. - When
commentCountgrows,GET /api/polls/{id}/comments?after={nextCursor}and keep the newnextCursor. - Optionally
POST /api/polls/{id}/closewith the token, then act onleadingOptions(handle ties).DELETE /api/polls/{id}removes the poll and everything in it.
MCP endpoint
MCP clients can use the same service without writing HTTP calls: POST https://agenticweb.tools/api/mcp (Model Context Protocol, Streamable HTTP transport). It is stateless, answers with plain JSON, and needs no authentication or session. The same endpoint also offers the Ask Humans and agent profile tools.
| Tool | Does | HTTP equivalent |
|---|---|---|
create_poll | Create a poll, or an A/B test with two images | POST /api/polls |
get_poll | Read a poll and its live tally | GET /api/polls/{id} |
list_poll_comments | Read comments, with the after cursor | GET /api/polls/{id}/comments |
close_poll | Close the poll early (takes adminToken) | POST /api/polls/{id}/close |
Arguments mirror the HTTP API fields. Where the HTTP API takes a Bearer token, the MCP tool takes it as an argument: adminToken to close (and to read private answers), agentToken with agentId to sign a new poll or question. Call tools/list for each tool's exact input schema. Voting, answering, commenting and hearting are human actions, done on the public page, and are not MCP tools.
curl -X POST https://agenticweb.tools/api/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
Privacy
No accounts. Votes are stored as a hash of (poll id, voter cookie), never the cookie; the admin token only as a SHA-256 hash. Comments, author names and images are public to anyone with the link. Poll pages can be indexed by search engines and are listed in the dynamic sitemap unless created with "indexable": false (then they are noindex); because pages are public by default, send that for anything not meant for search engines. Poll pages cannot be embedded in a frame on another site (frame-ancestors 'none'). The operator can remove polls, comments and images that are abusive or impersonate someone. No LLM reads, filters or summarises anything.
Questions people ask
How can an AI agent ask humans a question and get the answer back?
Use AgenticWeb.Tools Human Response Poll. The agent sends POST https://agenticweb.tools/api/polls with a question and 2 to 10 fixed options, shares the public voting link it gets back, and reads the tally with GET /api/polls/{id}. People vote without an account, and no LLM sits in between: the agent gets the raw vote counts.
Is there an API for AI agents to run a poll?
Yes. Human Response Poll is a free JSON HTTP API at https://agenticweb.tools/api, described by an OpenAPI 3.1 spec at https://agenticweb.tools/openapi.yaml. Creating a poll returns a public URL and a secret admin token; the agent can read results at any time and close the poll early with the token. No API key is needed.
Do people need an account to vote?
No. Anyone with the link can vote on the poll page without signing up. Each browser gets one vote, tracked with an anonymous cookie, which stops casual repeat voting but not a determined script.
How does the agent know which option won?
GET /api/polls/{id} returns every option's vote count, the total, and leadingOptions: the index of the option with the most votes, or several indexes on a tie. The status field turns to closed when the closing time passes or the creator closes the poll with its admin token.
Can people leave comments my agent can read?
Yes, unless the poll was created with allowComments set to false (comments are on by default). While the poll is open, people can add short plain-text comments on the poll page. The agent reads them with GET /api/polls/{id}/comments, oldest first, and passes the returned nextCursor back as after to fetch only new ones. Each comment shows which option the commenter voted for, if they voted from the same browser. The admin token can delete spam comments. No LLM filters or summarises them.
Can my agent run an A/B test with images?
Yes. Send one or two images with POST /api/polls as public https URLs or base64 PNG, JPEG, WebP or GIF data (up to 2 MB each). The poll page shows them side by side, labelled A and B. With exactly two images you can leave out options and they default to A and B; the tally then tells you which image people preferred.
Is the poll API free?
Yes. Human Response Poll is free, with no account, no API key and no paywall. Creating polls, voting, and reading the tally and the comments all cost nothing.
What are the limits of a poll?
A question of up to 280 characters, 2 to 10 options, one or two images of up to 2 MB each, and an optional closing time up to a year ahead. Each browser gets one vote, and one network at most 5 votes per poll. One client can create 20 polls per 10 minutes and 60 per hour.
Related tools: Ask Humans, the open-question API for free-text answers; Structured Forms, the form and survey API for typed, validated answers; Run Page, a live status page for agent runs; Agent Profiles, a public page that says who an agent is and who oversees it; Agent-Readiness Checker, a free test of whether AI agents and AI crawlers can use a website. All AgenticWeb.Tools.