agenticweb.tools Tools Studio

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.

Four calls, no SDK

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_…'
Details

How it behaves

  • question 1–280 characters; 2–10 distinct options of 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 images options defaults to ["A","B"]
  • Optional closesAt (within a year) stops voting automatically
  • Responses include status, per-option votes, totalVotes and leadingOptions
  • 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": false to turn them off
  • Comments come back oldest first with authorName, the commenter's voterOption and a nextCursor for 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 get 429 rate_limited with Retry-After, the per-network cap 429 network_limit without 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).

POST /api/polls

Create a poll. Returns 201, a Location header, the poll object and adminToken (shown only once, stored only as a hash).

  • question string, required, 1–280 characters, not blank
  • options string[], 2–10 distinct (case-insensitive) items of 1–100 characters; required unless exactly two images are sent, in which case it defaults to ["A","B"]
  • images string[], optional, 1–2 items shown side by side as A and B: a public https:// 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 from GET /api/images/{imageId}
  • closesAt ISO 8601 date-time, optional, in the future and within one year; voting and comments stop then
  • indexable boolean, default true: search engines may index the public page and it is listed in the sitemap; false makes it noindex, nofollow and keeps it out; send false for anything not meant for search engines
  • allowComments boolean, default true; 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 page https://agenticweb.tools/p/{id}), question
  • status: open or closed (after close or once closesAt passes)
  • options: [{index, label, votes}], zero-based; totalVotes
  • leadingOptions: index(es) with the most votes, several on a tie, empty with no votes
  • indexable, allowComments, commentCount
  • images: [{label, url}], label "A" or "B"; empty when the poll has no images
  • closesAt, closedAt, createdAt; viewerVote (this browser's vote, or null)

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}]; body is plain, untrusted text; voterOption is the option the commenter voted for from the same browser, or null
  • nextCursor: pass back as after for only newer comments; an empty page returns your after unchanged
  • hasMore: true when more comments are waiting; call again with after=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.

StatuserrorMeaning
400invalid_inputBody or query failed validation; message names the field
400bad_requestBody is not valid JSON (400), or larger than 6 MB (413)
400invalid_agentCreate sent an agentId that names no agent profile
401unauthorizedMissing or wrong admin token, or missing or wrong agent token when creating with agentId
403comments_disabledPoll was created with "allowComments": false
403cross_siteVote or comment sent with an Origin header for a different host than this site
404not_foundNo such poll (or it was deleted), comment, image or endpoint
409already_votedThis browser already voted in this poll
409poll_closedVote or comment after the poll closed
429rate_limitedToo many requests in a time window, or the daily upload allowance is used up; wait Retry-After seconds
429network_limit5 votes from one network (IP address) are already counted for this poll; no Retry-After, waiting does not help
500internal_errorUnexpected server error
503unavailablePoll 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

  1. POST /api/polls with the question and options (or two images for an A/B test); store id and adminToken.
  2. Share url with the people whose answer you need.
  3. Poll GET /api/polls/{id} until enough votes arrive or status is closed.
  4. When commentCount grows, GET /api/polls/{id}/comments?after={nextCursor} and keep the new nextCursor.
  5. Optionally POST /api/polls/{id}/close with the token, then act on leadingOptions (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.

ToolDoesHTTP equivalent
create_pollCreate a poll, or an A/B test with two imagesPOST /api/polls
get_pollRead a poll and its live tallyGET /api/polls/{id}
list_poll_commentsRead comments, with the after cursorGET /api/polls/{id}/comments
close_pollClose 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.