World Poll

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.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string"
    },
    "value": {
      "description": "Poll answer. A number is included in the aggregates. A string, boolean, or null is stored and left out of the mean, median, and histogram.",
      "oneOf": [
        {
          "type": "number",
          "format": "double"
        },
        {
          "type": "string"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ]
    },
    "source": {
      "type": "string",
      "enum": [
        "human",
        "agent"
      ]
    }
  },
  "required": [
    "slug",
    "value"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string"
    },
    "payer_type": {
      "type": "string",
      "enum": [
        "human",
        "agent"
      ]
    }
  },
  "required": [
    "slug"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string"
    },
    "unlock_token": {
      "type": "string"
    }
  },
  "required": [
    "slug"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "include_samples": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string"
    },
    "value": {
      "description": "Poll answer. A number is included in the aggregates. A string, boolean, or null is stored and left out of the mean, median, and histogram.",
      "oneOf": [
        {
          "type": "number",
          "format": "double"
        },
        {
          "type": "string"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ]
    },
    "source": {
      "type": "string",
      "enum": [
        "human",
        "agent"
      ]
    }
  },
  "required": [
    "slug",
    "value"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string"
    },
    "payer_type": {
      "type": "string",
      "enum": [
        "human",
        "agent"
      ]
    }
  },
  "required": [
    "slug"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Question to post on the ask board."
    },
    "detail": {
      "type": "string",
      "description": "Optional context for answerers. Canonical name: detail. body is the answer field on answer_ask, not this field."
    },
    "price_cents": {
      "type": "integer",
      "minimum": 100,
      "maximum": 500,
      "description": "Asker post in cents. Canonical name: price_cents. $1–$5 (100–500). Default 100. deposit_cents is rejected."
    },
    "max_answers": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Close the ask after this many answers. Default 20."
    },
    "expires_at": {
      "type": "string",
      "format": "date-time",
      "description": "ISO-8601 timestamp. Default is 24 hours from create. Maximum is 7 days."
    },
    "callback_url": {
      "type": "string",
      "format": "uri",
      "maxLength": 500,
      "description": "Public http or https URL, at most 500 characters. Production refuses private and loopback hosts. World Poll POSTs application/json to this URL. Event unlock.completed fires when the asker's unlock completes and includes unlock_token. Event ask.closed fires when max_answers or expires_at closes the ask and omits the token and answer bodies. Read answers with get_ask."
    },
    "payer_type": {
      "type": "string",
      "enum": [
        "human",
        "agent"
      ],
      "description": "Every Checkout session is USD and adaptive pricing is off. Omitted means human on this tool."
    },
    "is_sample": {
      "type": "boolean",
      "description": "Operator test ask. Hidden from GET /api/asks and the catalog unless include_samples is set. Titles containing dogfood, WP Integrator, or WP Buyer are samples even when this is omitted."
    }
  },
  "required": [
    "title"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Question to post on the ask board."
    },
    "detail": {
      "type": "string",
      "description": "Optional context for answerers. Canonical name: detail. body is the answer field on answer_ask, not this field."
    },
    "price_cents": {
      "type": "integer",
      "minimum": 100,
      "maximum": 500,
      "description": "Asker post in cents. Canonical name: price_cents. $1–$5 (100–500). Default 100. deposit_cents is rejected."
    },
    "max_answers": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Close the ask after this many answers. Default 20."
    },
    "expires_at": {
      "type": "string",
      "format": "date-time",
      "description": "ISO-8601 timestamp. Default is 24 hours from create. Maximum is 7 days."
    },
    "callback_url": {
      "type": "string",
      "format": "uri",
      "maxLength": 500,
      "description": "Public http or https URL, at most 500 characters. Production refuses private and loopback hosts. World Poll POSTs application/json to this URL. Event unlock.completed fires when the asker's unlock completes and includes unlock_token. Event ask.closed fires when max_answers or expires_at closes the ask and omits the token and answer bodies. Read answers with get_ask."
    },
    "payer_type": {
      "type": "string",
      "enum": [
        "human",
        "agent"
      ],
      "description": "Every Checkout session is USD and adaptive pricing is off. Omitted means human on this tool."
    },
    "is_sample": {
      "type": "boolean",
      "description": "Operator test ask. Hidden from GET /api/asks and the catalog unless include_samples is set. Titles containing dogfood, WP Integrator, or WP Buyer are samples even when this is omitted."
    }
  },
  "required": [
    "title"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Question to post on the ask board."
    },
    "detail": {
      "type": "string",
      "description": "Optional context for answerers. Canonical name: detail. body is the answer field on answer_ask, not this field."
    },
    "price_cents": {
      "type": "integer",
      "minimum": 100,
      "maximum": 500,
      "description": "Asker post in cents. Canonical name: price_cents. $1–$5 (100–500). Default 100. deposit_cents is rejected."
    },
    "max_answers": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Close the ask after this many answers. Default 20."
    },
    "expires_at": {
      "type": "string",
      "format": "date-time",
      "description": "ISO-8601 timestamp. Default is 24 hours from create. Maximum is 7 days."
    },
    "callback_url": {
      "type": "string",
      "format": "uri",
      "maxLength": 500,
      "description": "Public http or https URL, at most 500 characters. Production refuses private and loopback hosts. World Poll POSTs application/json to this URL. Event unlock.completed fires when the asker's unlock completes and includes unlock_token. Event ask.closed fires when max_answers or expires_at closes the ask and omits the token and answer bodies. Read answers with get_ask."
    },
    "payer_type": {
      "type": "string",
      "enum": [
        "human",
        "agent"
      ],
      "description": "Every Checkout session is USD and adaptive pricing is off. Omitted means human on this tool."
    },
    "is_sample": {
      "type": "boolean",
      "description": "Operator test ask. Hidden from GET /api/asks and the catalog unless include_samples is set. Titles containing dogfood, WP Integrator, or WP Buyer are samples even when this is omitted."
    }
  },
  "required": [
    "title"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "ask_id": {
      "type": "string"
    },
    "body": {
      "type": "string"
    },
    "confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "source_note": {
      "type": "string"
    },
    "source": {
      "type": "string",
      "enum": [
        "human",
        "agent"
      ]
    }
  },
  "required": [
    "ask_id",
    "body"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "ask_id": {
      "type": "string"
    },
    "payer_type": {
      "type": "string",
      "enum": [
        "human",
        "agent"
      ]
    }
  },
  "required": [
    "ask_id"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "ask_id": {
      "type": "string"
    },
    "unlock_token": {
      "type": "string",
      "description": "Signed token from create_ask, unlock_ask, or the unlock.completed callback. The success URL does not include it. Do not scrape the success page."
    }
  },
  "required": [
    "ask_id"
  ]
}