{"openapi":"3.1.0","info":{"title":"HumanRoad Human Preference Oracle","version":"0.4.0","description":"Ask a real human when a decision depends on subjective preference, naturalness, emotional reaction or bounded judgment rather than factual computation. Route human services across audio, images, short video, games/apps and text. One human compares 2–6 options for 0.01 USDC; optional HTTPS media references, maximum total audio/video duration 60 seconds. Full playtesting and production services are external referrals without an active commission. No account required for agents. One paid operation: POST /api/review. All other listed operations are free."},"servers":[{"url":"https://astra-human-preference-oracle.neik420.chatgpt.site"}],"security":[],"tags":[{"name":"Free","description":"Availability, unpaid draft creation and private result retrieval. No charge."},{"name":"Paid","description":"One human review, charged once via x402 V2 exact USDC on Base."}],"externalDocs":{"url":"https://astra-human-preference-oracle.neik420.chatgpt.site/docs","description":"Workflow, examples, compatibility endpoint and limitations"},"components":{"securitySchemes":{"requestToken":{"type":"http","scheme":"bearer","description":"Capability token returned by free POST /api/requests. Not an account. Keep for payment and result polling."}},"schemas":{"Question":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"service_id":{"default":"text.preference","type":"string","enum":["audio.edit-free","visual.edit-free","text.survey-free","audio.voice","audio.sound","audio.production","visual.image","visual.video","games.interface","games.playtest","games.usability","text.preference","text.naturalness","text.story"]},"media":{"default":[],"maxItems":6,"type":"array","items":{"type":"object","properties":{"option":{"type":"integer","minimum":1,"maximum":6},"kind":{"type":"string","enum":["image","audio","video"]},"url":{"type":"string","maxLength":2000,"format":"uri"},"duration_seconds":{"type":"integer","minimum":1,"maximum":60}},"required":["option","kind","url"],"additionalProperties":false}},"question":{"type":"string","minLength":5,"maxLength":1000},"options":{"minItems":2,"maxItems":6,"type":"array","items":{"type":"string","minLength":1,"maxLength":2000}},"context":{"default":"","type":"string","maxLength":4000},"capability":{"default":"human_preference","type":"string","enum":["human_preference","human_naturalness","subjective_choice"]},"discovery_source":{"default":"unknown","type":"string","maxLength":200},"agent_identifier":{"default":"unknown","type":"string","maxLength":200}},"required":["service_id","media","question","options","context","capability","discovery_source","agent_identifier"],"additionalProperties":false},"HumanResult":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"choice":{"type":"integer","minimum":1,"maximum":6},"confidence":{"type":"integer","minimum":0,"maximum":100},"reason":{"type":"string","minLength":5,"maxLength":2000},"reviewed_by":{"type":"string","const":"human"},"reviewer_count":{"type":"number","const":1},"completed_at":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["choice","confidence","reason","reviewed_by","reviewer_count","completed_at"],"additionalProperties":false},"Payment":{"type":"object","required":["transaction","amount_usdc","network","payer"],"properties":{"transaction":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"},"payer":{"type":"string"},"amount_usdc":{"const":"0.01"},"network":{"const":"eip155:8453"}}},"Draft":{"type":"object","required":["request_id","access_token","pay_url","poll_url","expires_at"],"properties":{"request_id":{"type":"string","format":"uuid"},"access_token":{"type":"string","description":"Secret bearer token, returned once. Never put in a URL."},"pay_url":{"type":"string"},"poll_url":{"type":"string"},"status":{"const":"awaiting_payment"},"expires_at":{"type":"integer"},"price_usdc":{"const":"0.01"},"instructions":{"type":"string"}}},"RequestState":{"type":"object","required":["request_id","status","result"],"properties":{"request_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["awaiting_payment","settling","pending_reconciliation","pending_human_review","completed","failed"]},"created_at":{"type":"integer","description":"Unix seconds"},"payment":{"anyOf":[{"type":"null"},{"$ref":"#/components/schemas/Payment"}]},"result":{"anyOf":[{"type":"null"},{"$ref":"#/components/schemas/HumanResult"}]},"poll_after_seconds":{"type":"integer"}}}}},"paths":{"/api/needs":{"post":{"operationId":"signalUnmetNeed","tags":["Free"],"summary":"Free: report a human service need with no solution","description":"Records a private signal for HumanRoad operators, not a booking, payment or guaranteed response. Optionally identify the agent with a public pseudonym. Do not send secrets.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["need"],"additionalProperties":false,"properties":{"need":{"type":"string","minLength":5,"maxLength":1000},"agent_identifier":{"type":"string","maxLength":100}}}}}},"responses":{"201":{"description":"Need recorded; no payment"},"400":{"description":"Invalid need","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/api/catalog":{"get":{"operationId":"discoverHumanServices","tags":["Free"],"summary":"Free: discover human services and free tools by category","parameters":[{"name":"pricing","in":"query","schema":{"type":"string","enum":["free","paid"]},"description":"free selects verified free external tools; paid selects native human reviews."},{"name":"category","in":"query","schema":{"type":"string","enum":["audio","visual","games","text"]}},{"name":"q","in":"query","schema":{"type":"string","maxLength":150}}],"description":"Audio, visual, games/apps and text; native HumanRoad review or external specialist. External referrals currently have no active commission.","responses":{"200":{"description":"Catalog of services, constraints and routes","content":{"application/json":{"schema":{"type":"object","properties":{"services":{"type":"array","items":{"type":"object"}},"categories":{"type":"array","items":{"type":"object"}}}}}}}}}},"/api/route":{"post":{"operationId":"routeHumanService","tags":["Free"],"summary":"Free: find the route for a human service","description":"Returns internal availability and next step or an external official website handoff. Never books, pays, or forwards task data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["service_id"],"additionalProperties":false,"properties":{"service_id":{"type":"string","description":"Choose an ID from GET /api/catalog"}}}}}},"responses":{"200":{"description":"Route, availability or external destination; no charge"},"400":{"description":"Unknown service or invalid input","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/api/status":{"get":{"operationId":"getHumanAvailability","tags":["Free"],"security":[],"summary":"Free: check human availability before payment","description":"accepting=false means do not pay. Aggregate metrics are not evidence of independent buyer provenance.","responses":{"200":{"description":"Live availability and aggregate metrics","content":{"application/json":{"schema":{"type":"object","required":["accepting","external_usdc","m2_verified"],"properties":{"available_until":{"type":"integer","description":"Unix seconds; 0 if closed"},"server_time":{"type":"integer"},"availability_remaining_seconds":{"type":"integer","minimum":0},"accepting":{"type":"boolean"},"external_usdc":{"type":"string"},"received_usdc":{"type":"string"},"m2_verified":{"type":"boolean"}}}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/api/requests":{"post":{"operationId":"createUnpaidHumanReview","tags":["Free"],"security":[],"summary":"Free: create an immutable unpaid draft","description":"Check availability. Send question, 2–6 option labels, service_id and media when required. See /api/catalog for services. Media must be direct public HTTPS files playable in a browser; per-option references and total duration are validated, content and actual duration are declared by the agent. Keep the returned access_token. This does not buy a review. Next POST /api/review with request_id in the JSON body and the token as Bearer. Draft expires in 15 minutes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Question"},"examples":{"wording":{"value":{"question":"Which button sounds clearer?","options":["Save changes","Keep my edits"],"capability":"human_naturalness","discovery_source":"your-router-name"}},"naming":{"value":{"question":"Which name feels friendlier for a notes app?","options":["NoteNest","MemoGrid"],"capability":"human_preference"}},"concept":{"value":{"question":"Which text-described illustration concept feels calmer?","options":["A quiet blue lake","A busy orange street"],"capability":"subjective_choice"}}}}}},"responses":{"201":{"description":"Unpaid draft; store access_token securely","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Draft"}}}},"400":{"description":"Invalid question/options","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"503":{"description":"Human unavailable. No payment was attempted.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/api/review":{"post":{"operationId":"buyHumanJudgment","tags":["Paid"],"summary":"Buy one real human judgment — 0.01 USDC","description":"Only payable resource. GET on this URL is a read-only probe of this POST quote, never a purchase. First create a free draft. Send {request_id} plus Authorization: Bearer access_token. Unauthenticated unpaid probes return a public 402 quote even when closed, for discovery only. Actual settlement requires a valid token, unexpired draft, available human and x402 PAYMENT-SIGNATURE. Receiving a 202 means poll; never pay again for the same draft. Results are asynchronous, one human opinion, not calibrated fact or consensus.","security":[{"requestToken":[]}],"x-payment-info":{"protocols":["x402"],"price":{"mode":"fixed","currency":"USD","amount":"0.01"}},"x-x402":{"version":2,"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","amount":"10000"},"parameters":[{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"schema":{"type":"string"},"description":"Base64 x402 V2 payload generated by the buyer client from PAYMENT-REQUIRED."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["request_id"],"additionalProperties":false,"properties":{"request_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Already paid, not charged again"},"202":{"description":"Pending human review or reconciliation. Poll the existing draft. No second payment.","content":{"application/json":{"schema":{"type":"object","required":["request_id","status"],"properties":{"request_id":{"type":"string"},"status":{"enum":["pending_human_review","pending_reconciliation","settling"]},"poll_url":{"type":"string"},"message":{"type":"string"}}}}}},"400":{"description":"Malformed payment or request","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"402":{"description":"Public x402 quote in JSON body and PAYMENT-REQUIRED header. Not proof of sale or availability.","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64 x402 V2 PaymentRequired"}}},"404":{"description":"Invalid token or unknown draft","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"410":{"description":"Draft expired","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"503":{"description":"Sales closed, free quota reached or payment unavailable; poll before retrying","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}},"/api/requests/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getPrivateHumanResult","tags":["Free"],"security":[{"requestToken":[]}],"summary":"Free: poll an existing request privately","description":"Poll every 30 seconds with the draft token. An unpaid request never returns a human result. A pending reconciliation must not be repaid. Test results are not delivered through this buyer endpoint.","responses":{"200":{"description":"Current state; result only after independently verified settlement and human completion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestState"}}}},"404":{"description":"Invalid token or unknown request","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}