{"openapi":"3.1.0","info":{"title":"Hitworkers API","version":"1.0.0","description":"Create micro-task campaigns done by real workers, then approve or reject each proof. Campaigns are reviewed by Hitworkers before going live. Cost per task = reward_usd + 25% fee. Human guide: https://hitworkers.com/docs"},"servers":[{"url":"https://hitworkers.com/api/v1"}],"security":[{"bearer":[]}],"paths":{"/account":{"get":{"summary":"Balance and pricing rules","responses":{"200":{"description":"Account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/campaigns":{"get":{"summary":"List campaigns","responses":{"200":{"description":"Campaigns","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Campaign"}}}}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a campaign (status pending_review, budget reserved)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/campaigns/{id}":{"get":{"summary":"Get a campaign","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Campaign","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found"},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/campaigns/{id}/cancel":{"post":{"summary":"Close the campaign and refund unused spots","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Closed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/campaigns/{id}/submissions":{"get":{"summary":"Worker proofs","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","schema":{"type":"string","enum":["in_progress","to_review","approved","rejected","expired"]}}],"responses":{"200":{"description":"Submissions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Submission"}}}}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/submissions/{id}/image":{"get":{"summary":"Screenshot sent by the worker","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Image","content":{"image/*":{}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/submissions/{id}/approve":{"post":{"summary":"Approve a proof (worker gets paid)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Approved"},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Not reviewable"},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/submissions/{id}/reject":{"post":{"summary":"Reject a proof (spot reopens)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","description":"Shown to the worker"}}}}}},"responses":{"200":{"description":"Rejected"},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Not reviewable"},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key from https://hitworkers.com/client (hw_live_...)"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"}}}}},"Account":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"},"balance_usd":{"type":"number"},"pricing":{"type":"object","properties":{"platform_fee_pct":{"type":"number"},"min_reward_usd":{"type":"number"},"max_instruction_words":{"type":"integer"}}},"top_up_url":{"type":"string"}}},"CampaignInput":{"type":"object","required":["title","instructions","reward_usd","slots"],"properties":{"title":{"type":"string","maxLength":140},"instructions":{"type":"string","description":"Markdown, max 500 words"},"reward_usd":{"type":"number","minimum":0.15,"maximum":100,"description":"What one worker earns for one task"},"slots":{"type":"integer","minimum":30,"maximum":10000},"proof_hint":{"type":"string","maxLength":300},"proof_type":{"type":"string","enum":["screenshot","text","file"]},"review_hours":{"type":"integer","enum":[24,48,72,168],"description":"Auto-approval after this delay"},"is_public":{"type":"boolean"},"target_url":{"type":"string","format":"uri"},"est_minutes":{"type":"integer"},"time_limit_minutes":{"type":"integer","minimum":5,"maximum":1440}}},"Campaign":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending_review","live","paused","closed","rejected"]},"title":{"type":"string"},"instructions":{"type":"string"},"reward_usd":{"type":"number"},"cost_per_task_usd":{"type":"number"},"slots":{"type":"integer"},"countries":{"type":"array","items":{"type":"string"}},"target_url":{"type":["string","null"]},"proof_hint":{"type":"string"},"requires_screenshot":{"type":"boolean"},"budget_held_usd":{"type":"number"},"submissions":{"type":"object","properties":{"in_progress":{"type":"integer"},"to_review":{"type":"integer"},"approved":{"type":"integer"},"rejected":{"type":"integer"}}},"admin_note":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"published_at":{"type":["string","null"],"format":"date-time"}}},"Submission":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["in_progress","to_review","approved","rejected","expired"]},"worker":{"type":"string"},"country":{"type":"string"},"proof_text":{"type":["string","null"]},"proof_image_url":{"type":["string","null"]},"submitted_at":{"type":["string","null"],"format":"date-time"},"reviewed_at":{"type":["string","null"],"format":"date-time"},"review_note":{"type":["string","null"]}}}}}}