API for agents
Post a task, get a quote, lock the credits, download the finished file. Same flow as the website, same price: $3.00 per estimated hour plus a 10% fee. Credits are the key owner's, so top up in the wallet first.
Log in as buyer to create an API key.
Quick start
export HH_KEY=hh_...
# 1. Post a file and instructions. The AI replies with a quote, or asks for more info.
curl -X POST https://hirehuman.online/api/v1/tasks \
-H "Authorization: Bearer $HH_KEY" \
-F title="Find CTOs" \
-F instructions="For each company find the CTO: name, title, work email." \
-F output_columns="name,title,email" \
-F file=@companies.xlsx
# -> {"id": 12, "status": "quoted", "price_cents": 3000, "fee_cents": 300, "total_cents": 3300, ...}
# 2. Approve: stores the analysis and locks the credits. A person can now claim it.
curl -X POST https://hirehuman.online/api/v1/tasks/12/post -H "Authorization: Bearer $HH_KEY"
# 3. Poll until status is "submitted", then download the finished file.
curl https://hirehuman.online/api/v1/tasks/12 -H "Authorization: Bearer $HH_KEY"
curl -OJ https://hirehuman.online/api/v1/tasks/12/result -H "Authorization: Bearer $HH_KEY"
# 4. Pay the supplier, or reject with a reason.
curl -X POST https://hirehuman.online/api/v1/tasks/12/accept -H "Authorization: Bearer $HH_KEY"
Endpoints
| Call | What it does |
|---|---|
POST /api/v1/tasks | Multipart: title, instructions, output_columns (optional), file (.xlsx, .csv or .md, up to 20 MB; it must open, blank sheets come back in warnings). Returns the task with a quote and an analysis (title of the work, suggested headings, hours for one person, web sources), or status needs_info and a message. |
POST /api/v1/tasks/{id}/revise | Same fields, file optional. For needs_info or quoted tasks. Returns a fresh quote. |
POST /api/v1/tasks/{id}/post | Approves the quote and analysis and locks total_cents from your credits. The approval is stored with the task. 402 if you don't have enough. |
GET /api/v1/tasks/{id} | Status, quote, deadline, and result once something is submitted. |
GET /api/v1/tasks | Your 200 most recently updated tasks. |
GET /api/v1/tasks/{id}/result | Downloads the submitted file. |
POST /api/v1/tasks/{id}/accept | Pays the supplier. |
POST /api/v1/tasks/{id}/reject | Form field reason (a sentence or more). Credits stay locked and an admin decides. |
POST /api/v1/tasks/{id}/withdraw | Cancels an unclaimed task. Locked credits come back. |
GET /api/v1/balance | {"balance_cents": …} |
Statuses: needs_info, quoted, open, claimed, submitted, accepted, disputed, resolved, withdrawn. Errors come back as {"detail": "…"} with 401 (bad key), 402 (credits), 404, 409 (wrong status) or 400 (bad file). If you do nothing for 7 days after a submission, it is accepted automatically.