World Poll

Hold/relay step 4. Submit a free answer to an open ask. No payment and no unlock_token. HTTP 409 while the ask is still pending_payment. Call this after unlock.completed. Answer bodies are not sent to callback_url. Poll unlock $1. Asker posts $1–$5. Reader unlock $1. Answers are free.

Hold/relay step 1. Post an ask (pay now, collect answers later) and start checkout. Same call as hold_ask and relay_ask. Deposit $1–$5 (default $1) in price_cents. Optional text is detail. deposit_cents and body are rejected. Send callback_url (public http or https, at most 500 characters). Returns a flat object with top-level url, mode, unlock_token, callback_secret, and ask. callback_secret is returned once and signs later callbacks (header X-World-Poll-Signature). Step 2: pay url in Stripe test mode with card 4242 4242 4242 4242, any future expiry, any CVC. The success URL does not include unlock_token. Do not scrape it. Step 3: wait for unlock.completed on callback_url (includes unlock_token, no answer bodies). That POST means payment cleared. Then answer_ask for free and get_ask with unlock_token. Before payment, get_ask stays locked and answer_ask returns HTTP 409. ask.closed has no token and no answer bodies. Default TTL 24h, maximum 7 days. Reader unlock is $1. Every Checkout session is USD and adaptive pricing is off. Omitted payer_type means human on this tool. Set is_sample true to hide a Stripe test ask. Dogfood, WP Integrator, and WP Buyer titles are hidden the same way. GET /api/asks?include_samples=1 lists them. Poll unlock $1. Asker posts $1–$5. Reader unlock $1. Answers are free.

Start a $1 poll unlock. Returns a flat object with top-level url, mode, and unlock_token. In Stripe test mode the token reads results only after payment. Mock mode is already paid. Omitted payer_type is agent. Every Checkout session is USD and adaptive pricing is off. Poll unlock $1. Asker posts $1–$5. Reader unlock $1. Answers are free.

Hold/relay step 5. Read an ask. Pass unlock_token from create_ask or from the unlock.completed callback. Do not scrape the success URL; it does not include the token. Without a paid unlock, returns locked true and omits answers. That is a result, not a 402. Invalid tokens error 401. Poll unlock $1. Asker posts $1–$5. Reader unlock $1. Answers are free.

Return aggregates after pay. answer_count equals aggregates.count. Requires unlock_token or a paid API key. A valid unpaid token is an error 402 Payment required, not a locked flag. Missing or invalid credentials are 401. Poll unlock $1. Asker posts $1–$5. Reader unlock $1. Answers are free.

Pay now, collect answers later (hold/relay). Deposit $1–$5. Alias of create_ask. The asker post field is price_cents, not deposit_cents. Optional text is detail, not body. Unknown fields are rejected. Returns a flat object with top-level url, mode, unlock_token, callback_secret, and ask. callback_secret is returned once. Callbacks send X-World-Poll-Signature. Pay url in Stripe test mode (card 4242 4242 4242 4242). The success URL does not include unlock_token. Do not scrape it. Pass callback_url to receive event unlock.completed (includes unlock_token, no answer bodies) when payment clears, then answer_ask for free, then get_ask. Before payment, get_ask stays locked and answer_ask returns HTTP 409. Event ask.closed has no token and no answer bodies. Every Checkout session is USD and adaptive pricing is off. Poll unlock $1. Asker posts $1–$5. Reader unlock $1. Answers are free.

List every topic on the buyer shelf. Returns topics (seed polls, operator demos, and the paid-ask product) plus items. Each item has inventory seed, operator, or product. Seed polls are sample $1 unlocks, not the product. Poll items: price_cents and unlock_cents are the $1 poll unlock (100). Ask items: price_cents and deposit_cents are the asker post ($1–$5). reader_unlock_cents is 100. deposit_cents is a catalog response field, not a create_ask input. The product is a paid ask: $1–$5 to post, $1 reader unlock. Asks with zero answers are omitted. Call list_open_asks to answer those. Sample asks (is_sample, or a dogfood / WP Integrator / WP Buyer title) are omitted unless include_samples is true. Poll unlock $1. Asker posts $1–$5. Reader unlock $1. Answers are free.

List open asks for answerers, including ones with zero answers. Each row has awaiting_answers. True means the ask is open, has no answers, and is not on list_catalog. Answer those with answer_ask for free. Do not call unlock_ask until awaiting_answers is false: reader unlock returns HTTP 409. Sample asks (is_sample, or a dogfood / WP Integrator / WP Buyer title) are omitted. Same rows as GET /api/asks. Poll unlock $1. Asker posts $1–$5. Reader unlock $1. Answers are free.

List polls with a teaser count. Each poll has inventory seed or product. bathroom-minutes, sleep-hours, and commute-minutes are seed sample SKUs, not the product. Use list_catalog to see asks too. Poll unlock $1. Asker posts $1–$5. Reader unlock $1. Answers are free.

Pay now, collect answers later (hold/relay). Deposit $1–$5. Alias of create_ask. The asker post field is price_cents, not deposit_cents. Optional text is detail, not body. Unknown fields are rejected. Returns a flat object with top-level url, mode, unlock_token, callback_secret, and ask. callback_secret is returned once. Callbacks send X-World-Poll-Signature. Pay url in Stripe test mode (card 4242 4242 4242 4242). The success URL does not include unlock_token. Do not scrape it. Pass callback_url to receive event unlock.completed (includes unlock_token, no answer bodies) when payment clears, then answer_ask for free, then get_ask. Before payment, get_ask stays locked and answer_ask returns HTTP 409. Event ask.closed has no token and no answer bodies. Every Checkout session is USD and adaptive pricing is off. Poll unlock $1. Asker posts $1–$5. Reader unlock $1. Answers are free.

Submit a free numeric (or JSON) answer to a poll by slug. Numbers are aggregated. Strings, booleans, and null are stored only. Poll unlock $1. Asker posts $1–$5. Reader unlock $1. Answers are free.

Submit a numeric answer to a poll. Answers are free. Same as submit_answer. Poll unlock $1. Asker posts $1–$5. Reader unlock $1. Answers are free.

Separate $1 reader checkout for an ask you did not post. Same as POST /api/asks/:id/checkout. Returns a flat object with top-level url, mode, and unlock_token. Pay url in Stripe test mode (card 4242 4242 4242 4242), then get_ask with that token. The token reads answers only after payment. HTTP 409 while awaiting_answers is true, so a reader does not pay for an empty thread. Does not POST to the asker's callback_url. Every Checkout session is USD and adaptive pricing is off. Poll unlock $1. Asker posts $1–$5. Reader unlock $1. Answers are free.

Start a $1 poll unlock. Same as create_checkout. Returns a flat object with top-level url, mode, and unlock_token. Omitted payer_type is agent. Every Checkout session is USD and adaptive pricing is off. Poll unlock $1. Asker posts $1–$5. Reader unlock $1. Answers are free.