{"openapi":"3.1.0","info":{"title":"Plures API","version":"1.0.0","description":"Human judgment as an API. Send a question and options; ID verified people answer independently; Plures returns the consensus answer and agreement by webhook. Docs: https://plures.si/docs","contact":{"email":"hello@plures.si","url":"https://plures.si"}},"servers":[{"url":"https://plures.si/api/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"pk_test_... for free test mode, pk_live_... for real people."}},"schemas":{"Task":{"type":"object","properties":{"id":{"type":"string","example":"tsk_8Jw2kQp4N7vRz1bXc5Td"},"object":{"type":"string","enum":["task"]},"mode":{"type":"string","enum":["live","test"]},"status":{"type":"string","enum":["pending","completed","expired","canceled"]},"question":{"type":"string"},"context":{"type":"string","nullable":true},"image_url":{"type":"string","nullable":true},"audio_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"media_seconds":{"type":"integer","nullable":true},"sensitive":{"type":"boolean"},"cost":{"type":"object","nullable":true,"description":"Live tasks only, in US cents","properties":{"per_answer_cents":{"type":"integer"},"answers_billed":{"type":"integer"},"total_cents":{"type":"integer"}}},"instructions":{"type":"string","nullable":true},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"}}}},"verifiers":{"type":"integer"},"presence_check":{"type":"boolean"},"result":{"type":"object","nullable":true,"properties":{"answer":{"type":"string","nullable":true,"description":"Option id most people chose; null on a tie or expiry."},"label":{"type":"string","nullable":true},"agreement":{"type":"number","description":"Share of people who chose the answer, 0 to 1."},"answers":{"type":"integer"},"votes":{"type":"object","additionalProperties":{"type":"integer"}},"tie":{"type":"boolean"},"decided_by":{"type":"string","enum":["verifiers","team"],"description":"Who made the final call."},"reviewer":{"type":"string","description":"Email of the team member who decided, when decided_by is team."},"note":{"type":"string","description":"Optional note from the team member."}}},"escalation":{"type":"object","nullable":true,"description":"Set when verified people didn't all agree and the decision went to your team.","properties":{"reason":{"type":"string","enum":["split","tie","no_answer"]},"escalated_at":{"type":"string","format":"date-time"},"verifiers":{"type":"object","description":"The verifiers' result."},"team_deadline":{"type":"string","format":"date-time"}}},"metadata":{"type":"object"},"webhook_url":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time"}}}}},"paths":{"/tasks":{"post":{"operationId":"createTask","summary":"Ask verified people a question","description":"Creates a task. Several ID verified people answer it independently; the result arrives by webhook (task.completed) or by polling GET /tasks/{id}.","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"},"description":"Repeat a request safely; the same key returns the original task."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["question","options"],"properties":{"question":{"type":"string","maxLength":1000,"description":"What people should decide."},"options":{"type":"array","minItems":2,"maxItems":8,"items":{"oneOf":[{"type":"string"},{"type":"object","required":["id","label"],"properties":{"id":{"type":"string"},"label":{"type":"string"}}}]}},"context":{"type":"string","maxLength":20000,"description":"The material to judge."},"image_url":{"type":"string","format":"uri"},"audio_url":{"type":"string","format":"uri","description":"A recording people play through before answering. Up to 3 minutes."},"video_url":{"type":"string","format":"uri","description":"A video people play through before answering. Up to 3 minutes. Send audio_url or video_url, not both."},"media_seconds":{"type":"integer","minimum":1,"maximum":180,"description":"Required with audio_url or video_url: the clip's length in seconds."},"sensitive":{"type":"boolean","default":false,"description":"Content some people would rather not see; only opted in verifiers get it, behind a warning."},"instructions":{"type":"string","maxLength":2000},"verifiers":{"type":"integer","enum":[1,3,5,7,9],"default":3},"max_verifiers":{"type":"integer","maximum":15,"description":"Default verifiers + 2. More people are asked when answers split."},"escalate":{"type":"boolean","description":"Send to your team when verifiers don't agree enough (default: on when you have a team). False always returns the verifiers' answer."},"escalate_below":{"type":"number","minimum":0,"maximum":1,"description":"Agreement below which the task goes to your team. Default from your dashboard (1: anything short of unanimous)."},"presence_check":{"type":"boolean","default":true,"description":"Every answer confirmed with the verifier's Face ID, fingerprint or passkey. Set false to skip the check on every answer; Plures still spot checks a share."},"webhook_url":{"type":"string","format":"uri"},"metadata":{"type":"object","description":"Your data, returned with the task; never shown to verifiers. In test mode, test_answer picks the answer and test_outcome (unanimous, split, tie, expired, slow) picks how the task settles."},"expires_in":{"type":"integer","minimum":60,"maximum":604800,"default":86400}}},"example":{"question":"Is this customer upset?","context":"Ordered a birthday cake. It came a day late and smashed. Amazing service, really.","options":["Yes","No"],"verifiers":3,"webhook_url":"https://your.app/plures"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"}}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"}}}}}}}},"402":{"description":"Not enough prepaid credit for a live task (insufficient_credits)"}}},"get":{"operationId":"listTasks","summary":"List tasks","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","completed","expired","canceled"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Tasks, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"has_more":{"type":"boolean"}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/tasks/{id}":{"get":{"operationId":"getTask","summary":"Retrieve a task and its result","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/tasks/{id}/cancel":{"post":{"operationId":"cancelTask","summary":"Cancel a pending task","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The canceled task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/balance":{"get":{"operationId":"getBalance","summary":"Prepaid credit for live tasks, in US cents","responses":{"200":{"description":"The balance","content":{"application/json":{"schema":{"type":"object","properties":{"available_cents":{"type":"integer"},"held_cents":{"type":"integer"},"balance_cents":{"type":"integer"},"price_per_unit_cents":{"type":"integer"},"billing":{"type":"string","enum":["prepaid","invoice"]},"auto_topup":{"type":"object"}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}}}