{"openapi":"3.1.0","info":{"title":"ActualHumanTake API","version":"1.0.0","summary":"Request an honest, human-written product review with a 12-hour target.","description":"Submit a product, receive a receipt token, poll for status, and read the published human review. Public reviews get a shareable page; private reviews are only readable with the receipt token. A Model Context Protocol (MCP) server is also available at /api/mcp.","contact":{"name":"ActualHumanTake","url":"https://actualhumantake.vercel.app"}},"servers":[{"url":"https://actualhumantake.vercel.app/api/v1","description":"Production"}],"x-mcp":{"endpoint":"https://actualhumantake.vercel.app/api/mcp","transport":"Streamable HTTP","tools":["submit_product_for_review","get_review_status","get_public_stats"]},"tags":[{"name":"Reviews","description":"Submit and track review requests"},{"name":"Meta","description":"Health and public stats"}],"paths":{"/reviews":{"post":{"tags":["Reviews"],"operationId":"submitReview","summary":"Submit a product for review","description":"Open endpoint. No API key required. Rate limited by IP and, when provided, email. Humans must provide an email; agents may omit it and poll with their receipt token. Send an optional Idempotency-Key header to make retries safe.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitReviewRequest"},"example":{"product":{"name":"Acme Notes","url":"https://acme.example","category":"productivity","description":"A minimal note-taking app for developers with markdown and local-first sync.","audience":"solo developers","stage":"beta"},"contact":{},"submitter":{"type":"agent","name":"Claude","model":"claude-sonnet"},"focus":["ux","positioning","pricing"],"publicOk":true,"consent":true}}}},"responses":{"201":{"description":"Request accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitReviewResponse"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reviews/{id}":{"get":{"tags":["Reviews"],"operationId":"getReviewStatus","summary":"Get review status and feedback","description":"Requires the receipt token returned by POST /reviews. Pass it as an Authorization: Bearer header (preferred) or a ?token= query parameter.","security":[{"receiptToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"req_abc123"}],"responses":{"200":{"description":"Current status. feedback is null until completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewStatus"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stats":{"get":{"tags":["Meta"],"operationId":"getStats","summary":"Public delivery stats","responses":{"200":{"description":"Completed review count and average turnaround","content":{"application/json":{"schema":{"type":"object","properties":{"completed":{"type":"integer"},"avgTurnaroundHours":{"anyOf":[{"type":"number"},{"type":"null"}]},"slaHours":{"type":"integer"}}}}}}}}},"/health":{"get":{"tags":["Meta"],"operationId":"health","summary":"Health check","responses":{"200":{"description":"Service is up","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"service":{"type":"string"},"version":{"type":"string"},"time":{"type":"string","format":"date-time"}}}}}}}}}},"components":{"securitySchemes":{"receiptToken":{"type":"http","scheme":"bearer","description":"The one-time receipt token returned when the request was created."}},"schemas":{"SubmitReviewRequest":{"type":"object","required":["product","contact"],"properties":{"product":{"type":"object","required":["name","url","description"],"properties":{"name":{"type":"string","maxLength":120},"url":{"type":"string","format":"uri"},"category":{"type":"string","maxLength":80},"description":{"type":"string","minLength":20,"maxLength":5000},"audience":{"type":"string","maxLength":500},"stage":{"type":"string","enum":["idea","prototype","beta","live"]}}},"contact":{"type":"object","description":"Required object. Email is required when submitter.type is human (the default) and optional for agents.","properties":{"email":{"type":"string","format":"email","description":"Required for humans; agents may omit email and poll with their receipt token."},"name":{"type":"string","maxLength":120}}},"submitter":{"type":"object","properties":{"type":{"type":"string","enum":["human","agent"]},"name":{"type":"string","maxLength":120},"model":{"type":"string","maxLength":120}}},"focus":{"type":"array","items":{"type":"string","enum":["ux","copy","positioning","pricing","onboarding","trust","other"]}},"publicOk":{"type":"boolean","default":false,"description":"Allow the finished review to be published at a public URL."},"consent":{"type":"boolean","default":true,"description":"Agree to the review terms."}}},"SubmitReviewResponse":{"allOf":[{"$ref":"#/components/schemas/ReviewStatus"},{"type":"object","properties":{"receiptToken":{"type":"string","description":"Keep this secret. It is the only way to read a private review and to poll status."},"statusUrl":{"type":"string","format":"uri"},"ackEmail":{"type":"string","enum":["sent","skipped","failed"]}}}]},"ReviewStatus":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","in_review","completed","rejected"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"reviewedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"product":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"category":{"type":"string"},"stage":{"type":"string"}}},"submitter":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"model":{"type":"string"}}},"focus":{"type":"array","items":{"type":"string"}},"publicOk":{"type":"boolean"},"publicUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"reviewPath":{"type":"string"},"slaHours":{"type":"integer"},"feedback":{"anyOf":[{"$ref":"#/components/schemas/Feedback"},{"type":"null"}]},"rejectionReason":{"type":"string"}}},"Feedback":{"type":"object","properties":{"markdown":{"type":"string"},"summary":{"type":"string"},"rating":{"anyOf":[{"type":"integer"},{"type":"null"}]},"publishedAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}