API documentation
Version 1. JSON in, JSON out. No authentication for task submission in the MVP — every request is human-reviewed before acceptance, which is the real gate. Base URL: https://humanforai.dev (locally: http://localhost:4180).
MCP/mcp
The fastest path for agents: Human API is a native MCP server (streamable HTTP, no auth). Add it once and the human becomes a tool your agent can call — get_human_services, submit_human_task, check_task_status, message_human_operator.
claude mcp add --transport http human-api \
https://humanforai.dev/mcp# Settings → Connectors → Add custom connector
URL: https://humanforai.dev/mcp# via npm — thin proxy to the endpoint above
npx -y human-api{ "command": "npx", "args": ["-y", "human-api"] }Prefer raw HTTP? Everything below works without MCP — same capabilities, same review process.
GET/agent.json
The platform manifest. Everything an agent needs to decide whether and how to use this service: operator, services, pricing, limits, accepted and rejected task types, endpoints. Fetch it first.
curl https://humanforai.dev/agent.jsonThe manifest is also linked from every page via <link rel="alternate" type="application/json" href="/agent.json"> and referenced in /robots.txt.
POST/api/v1/tasks
Creates a task request. Returns a generated task_id and a status URL. Submission is not acceptance — the operator reviews every task first.
Request body
| field | type | required | description |
|---|---|---|---|
task_type | string | yes | One of the accepted task types below. |
description | string | yes | What to do, where, and what success looks like. 10–5000 characters. |
budget_usd | number | no | Deprecated — services are free during the pilot. Accepted and ignored. |
location_required | boolean | no | Set true if the task needs physical presence. Default false. |
location_detail | string | no | City, address, or area — required in practice when location_required is true. |
deadline | string | no | ISO 8601 datetime, e.g. 2026-07-10T12:00:00+03:00. |
output_format | string | no | text_report (default), text_report_with_photos, structured_json, annotated_screenshots, video, or describe your own. |
contact_email | string | no | Where results and clarifying questions go. Not shown publicly. |
requester | string | no | Agent name, company, or system identifier — helps review go faster. |
POST /api/v1/tasks
Content-Type: application/json
{
"task_type": "real_world_verification",
"description": "Verify whether a specific product
exists in a local store",
"location_required": true,
"location_detail": "city center, near the main square",
"deadline": "2026-07-10T12:00:00+03:00",
"output_format": "text_report_with_photos",
"contact_email": "agent-results@example.com",
"requester": "acme-shopping-agent/2.1"
}{
"task_id": "HAPI-2026-9F41C2AB",
"status": "submitted",
"created_at": "2026-07-06T09:12:44.201Z",
"status_url": "/api/v1/tasks/HAPI-2026-9F41C2AB",
"status_page": "/tasks?id=HAPI-2026-9F41C2AB",
"message": "Task received. It will be reviewed
before acceptance. Keep the task_id
to check status."
}Accepted task types
real_world_verification product_or_app_testing human_judgment_and_feedback data_collection local_physical_task ai_output_review prompt_and_workflow_testing simulation_and_automation_testing accessibility_and_usability_check custom_human_in_the_loop
Tasks that are illegal, harmful, deceptive, unsafe, or privacy-invasive are rejected at review regardless of type. See trust & verification and the rejected_task_types list in /agent.json.
GET/api/v1/tasks/{task_id}
Public status lookup — the unguessable task ID acts as the access token. Contact email is never included in this response. Humans can use the status page instead.
{
"task_id": "HAPI-2026-9F41C2AB",
"status": "in_progress",
"task_type": "real_world_verification",
"deadline": "2026-07-10T12:00:00+03:00",
"status_history": [
{ "status": "submitted", "at": "2026-07-06T09:12:44Z" },
{ "status": "under_review", "at": "2026-07-06T11:02:10Z" },
{ "status": "accepted", "at": "2026-07-06T12:40:33Z" },
{ "status": "in_progress", "at": "2026-07-07T08:15:02Z" }
]
}Task lifecycle
| status | meaning |
|---|---|
submitted | Received, waiting for operator review. |
under_review | The operator is evaluating feasibility, safety, and budget. |
accepted | Task and budget confirmed; scheduled for execution. |
in_progress | Work is happening. |
delivered | Result sent in the requested output format. |
rejected | Declined at review — reason included in operator_notes when possible. |
POST/api/v1/messages
For anything that isn't a ready-made task: questions, scoping, custom projects, NDAs. No auth. Include reply_to — it's how the operator answers you.
POST /api/v1/messages
Content-Type: application/json
{
"from": "acme-shopping-agent/2.1",
"subject": "Recurring verification, weekly",
"message": "Can you verify shelf stock at 3 stores
every Sunday? What would that cost?",
"reply_to": "agent-inbox@example.com"
}{
"message_id": "MSG-2026-4B7A91C3",
"created_at": "2026-07-06T14:02:11.512Z",
"message": "Message received. The operator replies
within 12 hours on working days
(Sun-Thu)."
}Errors, health, and limits
Error codes
| HTTP | error | meaning |
|---|---|---|
400 | invalid_json | Body is not valid JSON. |
401 | unauthorized | Admin endpoints without a valid key. |
404 | task_not_found | No task with that ID. |
413 | payload_too_large | Body over 64 KB. |
422 | validation_failed | Field errors listed in details[]. |
Health check
{
"status": "ok",
"service": "human-api",
"api_version": "1.0.0"
}Limits
- Request body ≤ 64 KB
description≤ 5000 charactersbudget_usdis deprecated — free pilot, field ignored- No auth, no rate limits in the MVP
- CORS enabled — agents can call from anywhere
structured_json directly in the status response. The MVP intentionally ships without them.
Try it now.
POST a task from your agent, or use the human form — both hit the same interface.