# Hitworkers API Hitworkers connects you with real people (workers in 80+ countries) who complete simple online micro-tasks: views, searches, comments, posts, shares, sign-ups, tests, data checks. With this API (REST or MCP) you can do **everything you can do in your client space**: launch custom campaigns, launch from our templates, follow them, answer our team, add spots, review each proof, manage your workers and upload files, from your own code or from an AI agent such as Claude Code. ## How it works 1. **Create a client account** at https://hitworkers.com/client and **top up your balance by card** (Stripe, USD, minimum $20). 2. **Create an API key** in your client space. It is shown once: store it safely. 3. **Pick what to launch** with `GET /catalog`: a custom campaign, a preloaded template (instructions to adapt) or a simple template (just your URLs / content, fixed packs). 4. **Check the price** with `POST /quote`, then **create the campaign** with `POST /campaigns`. Its full budget is reserved on your balance. 5. **Our team reviews every campaign** before it goes live, within a few hours (some templates go live right away: `live_now: true`). We may ask a question (`questions_from_hitworkers` → action `answer`), suggest a higher price (`suggested_reward_usd` → action `accept_price`) or reject it (`admin_note`, full budget refunded). 6. **Workers do the task** and send a proof (text, screenshots, files or named fields). 7. **You review each proof**: approve, reject (spot reopened or refunded), ask for a fix (redo), or report. Proofs not reviewed in time are approved automatically. 8. **Stop** when you have enough: unused budget returns to your balance. ## Pricing - Custom campaign: you choose `reward_usd` (what one worker earns, minimum $0.15). Cost per task = `reward_usd` + 10% fee (+ $0.03 per extra screenshot). Budget = cost per task × `slots`. - Simple templates have their own packs and prices (see `GET /catalog`). - Audience `best_workers`: +$0.30 per worker. - You only pay approved proofs: rejected proofs are refunded (or the spot reopens), unused spots come back when the campaign stops. - `POST /quote` returns the exact total before you commit. ## Authentication, limits, errors Send your key in the `Authorization` header of every request: ``` Authorization: Bearer hw_live_xxxxxxxxxxxxxxxx ``` Base URL: `https://hitworkers.com/api/v1`. Requests and responses are JSON. Rate limit: 120 requests per minute (REST and MCP together). Errors look like `{ "error": { "message": "...", "need_usd": 12.5 } }` with an HTTP status: 400 invalid input, 401 bad key, 402 balance too low (`need_usd`, `top_up_url`), 403 not allowed for this campaign, 404 not found, 409 wrong state, 429 too many requests. **Idempotency.** Send an `Idempotency-Key: ` header on any POST / PATCH (MCP: the `idempotency_key` argument): if the request is replayed (timeout, network error), you get the first response back (header `Idempotent-Replayed: true`) and nothing is created or charged twice. Keys are kept 24 h. The same key with a different body returns 422. Errors you can fix (402 balance, 409 state, 429, 5xx) are not kept: retry with the same key once fixed. ## Endpoints | Method | Path | What it does | |---|---|---| | GET | /account | Balance, verified email, pricing | | GET | /account/statement?limit=100 | Last balance movements | | GET | /catalog | Templates, simple templates, audiences, prices, minimums | | POST | /quote | Price of a campaign (same body as POST /campaigns), nothing created | | POST | /campaigns | Create a campaign (or a draft with `draft: true`) | | GET | /campaigns?status=live | List your campaigns (`draft`, `pending_review`, `live`, `paused`, `closed`) | | GET | /campaigns/{id} | One campaign | | PATCH | /campaigns/{id} | Edit a draft (launch it) or a campaign still pending review | | POST | /campaigns/{id}/actions | pause, resume, stop, add_slots, accept_price, relaunch, answer, resurface, note, pace, open_all, delete | | POST | /campaigns/{id}/cancel | Same as action `stop` | | GET | /campaigns/{id}/submissions?status=to_review | Worker proofs | | POST | /campaigns/{id}/approve-all | Approve every proof waiting for review | | POST | /submissions/{id}/review | approve, reject, redo or report a proof | | POST | /submissions/{id}/approve · /reject | Shortcuts of /review | | POST | /submissions/{id}/reply | Answer a worker's question | | GET | /submissions/{id}/image?i=0 | A screenshot / file sent by the worker | | GET | /workers | Workers who already worked for you (anonymous) | | PATCH | /workers/{id} | Favorite or block a worker | | POST | /files | Upload a file (3 MB, base64) → `href` | | POST | /files/upload-token · /files/complete | Upload a big file (video, 200 MB) | | POST | /images | Upload an image for the instructions → `[img:id]` | ### GET /catalog Everything you can launch, with prices and minimums: - `templates`: preloaded campaigns (code, title, instructions, proof, suggested price). Send `template: ""` with your own title / instructions. **Replace every item of `must_replace`** (`[YOUR PRODUCT]`, example links…) or the launch is refused. - `simple_templates`: Google SEO Boost, YouTube Boost, social, X Boost, publishing on X / LinkedIn / YouTube / Instagram / Facebook… You only send your URLs or content: Hitworkers builds the instructions, proofs and price. Each item lists its `input` fields, `packs`, `durations_min`, `extras`. - `audiences`, `pricing`, `forum_service`. ### POST /campaigns — custom campaign | Field | Type | Description | |---|---|---| | title | string | Short task name shown to workers (max 140 characters) | | instructions | string | Numbered steps, Markdown, **max 3000 characters**. `||text||` = shown only to workers who took a spot. `{column}` = per-worker data. `[img:id]` = image from POST /images | | reward_usd | number | What one worker earns (min 0.15, max 100) | | slots | integer | Number of workers / tasks (10 to 10000) | | proof_type | string | `screenshot` (default), `text`, `file` (photo, audio, PDF), `fields`, or several: `screenshot,text` | | proof_count | integer | Screenshots / files required (1 to 3; each extra one adds $0.03 per task) | | proof_fields | string[] | With `fields`: labels to fill, e.g. `["Username", "Post URL"]`. `~Label` = optional, `☑ Label` = checkbox, `Label [A|B]` = choice | | proof_hint | string | What the worker must send | | template | string | Preloaded template code (see /catalog) | | audience | string | `all` (default), `best_workers` (+$0.30/worker: most reliable workers first, then everyone), `favorites` (your starred workers; slots = their number), `workers` (+ `worker_ids`) | | worker_ids | string[] | With audience `workers`: ids from GET /workers | | countries | string[] | ISO codes, e.g. `["US","GB"]` (empty = all countries) | | target_url | string | Link the worker must open | | est_minutes | integer | Estimated time shown to workers | | time_limit_minutes | integer | Time to send the proof after taking a spot (5 to 1440, default 60) | | review_hours | integer | 24 or 48 (default): proofs not reviewed in time are approved automatically | | max_per_worker | integer | Tasks per worker (default 1, 0 = unlimited) | | new_workers_only | boolean | Exclude workers who already did one of your campaigns | | is_public | boolean | Listed to other clients, private parts masked (default true) | | pace | object | How fast workers receive the tasks (default: all at once). `{ "days": 7 }` spreads them over 7 days; `{ "per_hour": 2 }` = 2 tasks per hour. Options: `hours: [9, 21]` (active hours), `tz: "America/New_York"` (their time zone, default Europe/Paris), `weekend: false` (no tasks on Saturday and Sunday), `start_at`. Spots not taken in quiet hours are caught up later (at most 2× the pace in one hour) | | start_at | string | Scheduled start (ISO 8601, within 90 days) | | csv | string | Different data per worker: CSV, first line = column names, then one line per worker | | columns + rows | array | Same as csv in JSON: rows = arrays (order of columns) or objects | | random_rows / rows_per_worker | | Random order; several rows per worker (needs random_rows) | | long_text | boolean | Rows are articles `[title, Markdown text, cover?]`, one per worker | | variants | array | 2 or 3 versions of the instructions, spots split equally: `[{ instructions, proof_hint?, proof_type?, proof_count?, proof_fields?, csv?/columns?/rows?, data_from? }]`. Per-version data goes inside each version; `data_from` = index (from 0) of an earlier version whose rows are reused | | draft | boolean | `true` = save as draft, nothing charged | ```bash curl -X POST https://hitworkers.com/api/v1/campaigns \ -H "Authorization: Bearer $HITWORKERS_KEY" -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "title": "Test our signup page and report what breaks", "instructions": "1. Open ||https://yourapp.com/signup||.\n2. Create an account with a real email.\n3. Screenshot the last screen you reached.", "reward_usd": 0.30, "slots": 50, "proof_type": "screenshot,text", "proof_hint": "What broke, if anything", "countries": ["US", "GB", "CA"], "pace": { "days": 5, "hours": [9, 21], "tz": "America/New_York" } }' ``` Response `201`: the campaign object. `402`: balance too low (`need_usd`). ### POST /campaigns — from a simple template ```json { "simple_template": "google", "simple": { "entries": [{ "url": "https://yoursite.com/page", "keywords": "best running shoes, running shoes 2026" }], "pages": 2, "pack": 100, "days": 5 } } ``` ```json { "simple_template": "x-publish", "simple": { "items": [{ "text": "Our new feature is live 🚀" }, { "text": "Thread 2/2", "image": "" }], "pack": 30 } } ``` The fields of `simple` are listed for each template in `GET /catalog` (`input`). The price is fixed by the pack (see `packs`) or computed for a custom quantity. ### POST /campaigns — managed forum backlinks ```json { "forum": { "forums": 30, "src": "lib", "lang": "EN", "links": [{ "url": "https://yoursite.com", "anchor": "best CRM for startups" }] } } ``` ### The campaign object ```json { "id": "uuid", "status": "draft | pending_review | live | paused | closed | rejected", "title": "...", "instructions": "...", "reward_usd": 0.15, "cost_per_task_usd": 0.1650, "slots": 100, "countries": [], "target_url": null, "proof_hint": "...", "proof_type": "screenshot", "proof_count": 1, "review_hours": 48, "template": null, "audience": "all", "max_per_worker": 1, "pace": { "per_hour": 2, "hours": [9, 21], "tz": "America/New_York", "weekend": true }, "start_at": null, "worker_note": null, "questions_from_hitworkers": null, "suggested_reward_usd": null, "budget_held_usd": 16.50, "submissions": { "in_progress": 3, "to_review": 12, "approved": 40, "rejected": 2 }, "admin_note": null, "created_at": "2026-11-22T10:00:00.000Z", "published_at": "2026-11-22T12:00:00.000Z", "csv_url": "https://hitworkers.com/api/client/orders/uuid/export" } ``` `csv_url`: full CSV of the proofs (download it with your API key). ### POST /campaigns/{id}/actions | action | Extra fields | What it does | |---|---|---| | pause / resume | | Workers can't take it while paused | | pace | `pace` (same object as on creation) | New pace, applied from the next hour | | open_all | | Open every remaining spot now (no pace) | | stop (or cancel) | | Closes it: pending proofs approved, unused budget refunded (`refunded_usd`) | | add_slots | `n` (1-1000) | More spots, budget reserved | | accept_price | | Pay the difference of the price suggested by our team: the campaign goes live | | relaunch | | Rejected with a suggested price: relaunch at that price | | answer | `text` | Answer the question of our team (`questions_from_hitworkers`) | | resurface | | Move it back to the top of the workers' list | | note | `text` | Short note shown on top of the task; workers must confirm it before sending. Empty text removes it. Notes with links, contacts or extra work are checked by our team first (`note_state: pending`) | | delete | | Delete a draft, or hide a finished campaign | ### GET /campaigns/{id}/submissions?status=to_review `status`: `in_progress`, `to_review`, `approved`, `rejected`, `expired` (default: all except expired). `limit` (max 500), `offset`. ```json { "data": [ { "id": "uuid", "status": "to_review", "worker_id": "uuid", "worker": "Worker #a1b2", "country": "IN", "proof_text": "my_username", "proof_fields": { "Post URL": "https://…" }, "proof_file_urls": ["https://hitworkers.com/api/v1/submissions/uuid/image", "https://hitworkers.com/api/v1/submissions/uuid/image?i=1"], "data": [{ "url": "https://…" }], "followed_note": true, "messages": [{ "from": "worker", "text": "…", "at": "…" }], "submitted_at": "2026-11-22T12:30:00.000Z", "reviewed_at": null, "review_note": null } ] } ``` Workers are anonymous (never their name or email). Google SEO Boost / YouTube Boost proofs are checked and approved automatically: their details are not shown. ### POST /submissions/{id}/review | decision | Fields | Effect | |---|---|---| | approve | `feedback`? | Worker paid; feedback shown to them | | reject | `reason`, `comment`?, `reopen_spot`? | `reopen_spot: true` (default) = another worker takes the spot; `false` = you are refunded | | redo | `reason`, `comment`? | The worker fixes and resends within 48 h | | report | `feedback`? | Flags the worker to our team (decision unchanged) | Suggested reasons: "Proof missing or unreadable", "Link doesn't open or the account is private", "Instructions not followed", "Wrong country", "Duplicate submission", "Edited or fake proof", "Advertiser's note not followed" (only for proofs sent after your note). Reddit campaigns can't be rejected (approved automatically). ### Workers `GET /workers` lists the workers who already worked for you: `id`, anonymous `label`, country, approved / rejected counts, `approval_rate_pct`, `favorite`, `blocked`. `PATCH /workers/{id}` with `{ "favorite": true }` or `{ "blocked": true }`. Use their ids with `audience: "workers"`, or star them and use `audience: "favorites"`. ### Files and images - `POST /files` `{ "name": "photo.png", "content_type": "image/png", "data_base64": "…" }` (3 MB max) → `{ "id", "href" }`. Use `href` in your per-worker data or in publishing templates (`items[].image`, `items[].file`). - Bigger files (video, up to 200 MB): `POST /files/upload-token` `{ name, content_type, size }` → `{ pathname, token }`; upload with the `@vercel/blob` SDK: `put(pathname, file, { access: "public", token, contentType })`; then `POST /files/complete` `{ url, name }` → `{ id, href }`. - `POST /images` `{ "content_type": "image/png", "data_base64": "…" }` (2 MB) → `{ "markdown": "[img:id]" }` to paste in the instructions. ## MCP (Claude Code and other AI agents) Hitworkers is also an MCP server: an agent can use everything above as tools. Endpoint: `https://hitworkers.com/api/mcp` (Streamable HTTP), same API key. ```bash claude mcp add --transport http hitworkers https://hitworkers.com/api/mcp --header "Authorization: Bearer hw_live_xxxxxxxxxxxxxxxx" ``` Then ask in plain words, for example: "Launch Google SEO Boost on my pricing page with the keyword 'crm for startups', 100 searches over 5 days" or "Review the proofs of my last campaign and reject the ones without a screenshot of the comment". Tools: `get_account`, `get_statement`, `get_catalog`, `quote_campaign`, `create_campaign`, `update_campaign`, `list_campaigns`, `get_campaign`, `campaign_action`, `list_submissions`, `get_proof_file` (screenshots returned as images), `review_submission`, `approve_all`, `reply_to_worker`, `list_workers`, `set_worker`, `upload_file`, `upload_image`. Same rules as the REST API and the client space. ## Typical loop for an AI agent 1. `GET /catalog` and `GET /account`. 2. `POST /quote`, then `POST /campaigns` (with an `Idempotency-Key`). 3. Poll `GET /campaigns/{id}`: `live`, `rejected` (`admin_note`), a question (`questions_from_hitworkers` → action `answer`) or a new price (`suggested_reward_usd` → action `accept_price`). 4. Every few hours: `GET /campaigns/{id}/submissions?status=to_review`, check each proof against the instructions (download the files with the key), then `POST /submissions/{id}/review` with a clear reason. Workers often forget the same thing? Add a `note`. 5. When you have enough results: action `stop` to get unused budget back. ## Good instructions - Number the steps. One action per step. Write in English. - Say exactly what the proof must show, and what gets rejected. - No illegal, adult, gambling, misleading or account-selling tasks: they are rejected at review. Machine-readable spec: https://hitworkers.com/openapi.json · This page as Markdown: https://hitworkers.com/docs.md ## Guides - [Human Micro-Task Benchmark 2026: Approval Rates, Speed & Countries](https://hitworkers.com/human-microtask-benchmark-2026): Original 2026 data from 14,549 reviewed micro-tasks: 93% approval, 10.1-minute median, 85 countries, approval rates by task type. Free to cite. (French: https://hitworkers.com/fr/human-microtask-benchmark-2026) - [How Much Does CTR Manipulation Cost in 2026? Real Human Prices](https://hitworkers.com/ctr-manipulation-cost): What real human clicks, searches, views, sign-ups and survey responses cost in 2026, with a calculator table. From $0.165 per task, pay approved only. (French: https://hitworkers.com/fr/ctr-manipulation-cost) - [Human-in-the-Loop Task API for AI Agents (REST + MCP)](https://hitworkers.com/human-in-the-loop-api): Let AI agents hire real people: REST API and MCP server to create human tasks, get proofs and review them. Works with Claude Code. From $0.165 a task. (French: https://hitworkers.com/fr/human-in-the-loop-api) - [White-Label Micro-Task Services for SEO Agencies](https://hitworkers.com/white-label-seo-microtasks): Resell human CTR tests, YouTube views, forum and publishing tasks under your agency brand. API + MCP, CSV reports, per-proof review, no minimums. (French: https://hitworkers.com/fr/white-label-seo-microtasks) - [Get Survey Responses Fast From Real Respondents](https://hitworkers.com/get-survey-responses-fast): Get survey responses in hours from real people in 85 countries. Completion-code proof, country targeting, from $0.165 a response. Pay approved only. (French: https://hitworkers.com/fr/get-survey-responses-fast) - [Social Media Content Seeding With Real People](https://hitworkers.com/social-media-content-seeding): Seed your content on X, LinkedIn, Facebook and Instagram with real people posting from their own accounts. Proof per post, from $0.20 per share, no bots. (French: https://hitworkers.com/fr/social-media-content-seeding) - [X (Twitter) Promotion With Real Accounts and Proof](https://hitworkers.com/x-twitter-promotion): Promote your X posts with real people: reposts, replies, quotes and likes from real accounts, with proof. No bots, no guarantees, from $0.165 a task. (French: https://hitworkers.com/fr/x-twitter-promotion) - [Increase YouTube Watch Time: Retention Testing With Real Viewers](https://hitworkers.com/youtube-watch-time-retention): Test YouTube audience retention with real viewers: 2, 5 or 10-minute watches from search, plus written feedback on where they lost interest. From $0.20. (French: https://hitworkers.com/fr/youtube-watch-time-retention)