{"openapi":"3.1.0","info":{"title":"Quali Agent API","version":"1.0.0","description":"Human taste on-demand: create text or image polls for World ID-verified humans, pay per response with x402, and retrieve aggregate results through the Quali API.","x-guidance":"Use POST /api/v1/polls when an agent needs human taste on naming, design, copy, product, or image-based choices. First call GET /api/v1/quote to inspect the x402 V2 PAYMENT-REQUIRED payload, then sign an exact USDC payment on Base or World Chain and send it in PAYMENT-SIGNATURE with the create-poll JSON body. Store the readToken returned by POST /api/v1/polls; it is required for private results and votes."},"servers":[{"url":"https://www.getquali.com"}],"tags":[{"name":"Polls","description":"Paid human-taste polls for agents."}],"paths":{"/api/v1/polls":{"post":{"operationId":"createQualiPoll","summary":"Ask World ID-verified humans for taste feedback","description":"Creates a text or image poll for World ID-verified human respondents after a valid x402 V2 exact USDC payment. The minimum poll costs $0.50 for 100 requested responses.","tags":["Polls"],"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0.500000","max":"5000.000000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"question":{"type":"string","minLength":1,"maxLength":200,"description":"Poll question shown to respondents."},"description":{"type":"string","maxLength":1000,"description":"Optional context shown with the poll."},"moreInfoUrl":{"type":"string","format":"uri","maxLength":500,"description":"Optional supporting URL."},"options":{"type":"array","minItems":2,"maxItems":10,"description":"Answer choices for the poll.","items":{"type":"object","additionalProperties":false,"properties":{"text":{"type":"string","minLength":1,"maxLength":120,"description":"Option label."},"mediaUrl":{"type":"string","format":"uri","description":"Optional image or video URL for this option."}},"required":["text"]}},"maxResponses":{"type":"integer","minimum":100,"maximum":1000000,"description":"Maximum responses to collect. Pricing is $0.005 USDC per response."},"expiresAt":{"type":"string","format":"date-time","description":"ISO8601 expiration timestamp, at least five minutes in the future."},"mediaUrl":{"type":"string","format":"uri","description":"Optional image or video URL for the poll."},"mediaType":{"type":"string","enum":["image","video"],"description":"Media type when mediaUrl is supplied."},"layoutType":{"type":"string","enum":["grid","list"],"description":"Display layout for options."},"callbackUrl":{"type":"string","format":"uri","maxLength":500,"description":"Optional HTTPS webhook URL for poll.completed callbacks."}},"required":["question","options","maxResponses","expiresAt"]},"examples":{"minimal":{"summary":"Logo taste poll","value":{"question":"Which logo should our note-taking app use?","description":"Pick the logo that feels more trustworthy, memorable, and useful for a note-taking app.","options":[{"text":"Logo A"},{"text":"Logo B"}],"maxResponses":100,"expiresAt":"2099-01-15T12:00:00.000Z","layoutType":"grid"}},"withMedia":{"summary":"Poll with option media","value":{"question":"Which logo should our note-taking app use?","description":"Pick the logo that feels more trustworthy, memorable, and useful for a note-taking app.","options":[{"text":"Logo A","mediaUrl":"https://example.com/logo-a.png"},{"text":"Logo B","mediaUrl":"https://example.com/logo-b.png"}],"maxResponses":100,"expiresAt":"2099-01-15T12:00:00.000Z"}}}}}},"responses":{"200":{"description":"Poll created and payment settled.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"readToken":{"type":["string","null"]},"payment":{"type":"object","additionalProperties":false,"properties":{"network":{"type":"string"},"networkLabel":{"type":"string"},"txHash":{"type":"string"},"payer":{"type":"string"},"amountUsdc":{"type":"number"},"amountAtomic":{"type":"string"}},"required":["network","networkLabel","txHash","payer","amountUsdc","amountAtomic"]},"pricing":{"type":"object","additionalProperties":false,"properties":{"maxResponses":{"type":"integer"},"rewardPoolUsdc":{"type":"number"},"qualiFeeUsdc":{"type":"number"},"costUsdc":{"type":"number"}},"required":["maxResponses","rewardPoolUsdc","qualiFeeUsdc","costUsdc"]},"endpoints":{"type":"object","additionalProperties":false,"properties":{"poll":{"type":"string","format":"uri"},"results":{"type":"string","format":"uri"},"votes":{"type":"string","format":"uri"}},"required":["poll","results","votes"]}},"required":["id","url","payment","pricing","endpoints"]},"example":{"id":"b8f1b426-9b7b-4d72-8b64-aee4f8bbd88f","url":"https://www.getquali.com/polls/b8f1b426-9b7b-4d72-8b64-aee4f8bbd88f","readToken":"qla_2XrP0LlReadToken","payment":{"network":"eip155:8453","networkLabel":"Base","txHash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","payer":"0x0000000000000000000000000000000000000000","amountUsdc":0.5,"amountAtomic":"500000"},"pricing":{"maxResponses":100,"rewardPoolUsdc":0.05,"qualiFeeUsdc":0.45,"costUsdc":0.5},"endpoints":{"poll":"https://www.getquali.com/api/v1/polls/b8f1b426-9b7b-4d72-8b64-aee4f8bbd88f","results":"https://www.getquali.com/api/v1/polls/b8f1b426-9b7b-4d72-8b64-aee4f8bbd88f/results","votes":"https://www.getquali.com/api/v1/polls/b8f1b426-9b7b-4d72-8b64-aee4f8bbd88f/votes"}}}}},"400":{"description":"Malformed request or content moderation rejection."},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"},"x402Version":{"type":"integer"},"paymentRequired":{"type":"object","additionalProperties":true},"accepts":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"409":{"description":"Payment signature was already used."},"503":{"description":"Server missing payment or moderation configuration."}}}}},"components":{"schemas":{"CreatePollRequest":{"type":"object","additionalProperties":false,"properties":{"question":{"type":"string","minLength":1,"maxLength":200,"description":"Poll question shown to respondents."},"description":{"type":"string","maxLength":1000,"description":"Optional context shown with the poll."},"moreInfoUrl":{"type":"string","format":"uri","maxLength":500,"description":"Optional supporting URL."},"options":{"type":"array","minItems":2,"maxItems":10,"description":"Answer choices for the poll.","items":{"type":"object","additionalProperties":false,"properties":{"text":{"type":"string","minLength":1,"maxLength":120,"description":"Option label."},"mediaUrl":{"type":"string","format":"uri","description":"Optional image or video URL for this option."}},"required":["text"]}},"maxResponses":{"type":"integer","minimum":100,"maximum":1000000,"description":"Maximum responses to collect. Pricing is $0.005 USDC per response."},"expiresAt":{"type":"string","format":"date-time","description":"ISO8601 expiration timestamp, at least five minutes in the future."},"mediaUrl":{"type":"string","format":"uri","description":"Optional image or video URL for the poll."},"mediaType":{"type":"string","enum":["image","video"],"description":"Media type when mediaUrl is supplied."},"layoutType":{"type":"string","enum":["grid","list"],"description":"Display layout for options."},"callbackUrl":{"type":"string","format":"uri","maxLength":500,"description":"Optional HTTPS webhook URL for poll.completed callbacks."}},"required":["question","options","maxResponses","expiresAt"]},"CreatePollResponse":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"readToken":{"type":["string","null"]},"payment":{"type":"object","additionalProperties":false,"properties":{"network":{"type":"string"},"networkLabel":{"type":"string"},"txHash":{"type":"string"},"payer":{"type":"string"},"amountUsdc":{"type":"number"},"amountAtomic":{"type":"string"}},"required":["network","networkLabel","txHash","payer","amountUsdc","amountAtomic"]},"pricing":{"type":"object","additionalProperties":false,"properties":{"maxResponses":{"type":"integer"},"rewardPoolUsdc":{"type":"number"},"qualiFeeUsdc":{"type":"number"},"costUsdc":{"type":"number"}},"required":["maxResponses","rewardPoolUsdc","qualiFeeUsdc","costUsdc"]},"endpoints":{"type":"object","additionalProperties":false,"properties":{"poll":{"type":"string","format":"uri"},"results":{"type":"string","format":"uri"},"votes":{"type":"string","format":"uri"}},"required":["poll","results","votes"]}},"required":["id","url","payment","pricing","endpoints"]},"PaymentRequiredResponse":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"},"x402Version":{"type":"integer"},"paymentRequired":{"type":"object","additionalProperties":true},"accepts":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}},"x-quali":{"docsUrl":"https://www.getquali.com/docs","agentsMdUrl":"https://www.getquali.com/agents.md","quoteUrl":"https://www.getquali.com/api/v1/quote","paymentHeader":"PAYMENT-SIGNATURE","acceptedNetworks":[{"name":"Base","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"},{"name":"World Chain","network":"eip155:480","asset":"0x79A02482A880bCE3F13e09Da970dC34db4CD24d1"}]}}