API documentation

0 · connect via MCP

MCP`/mcp`

The fastest path for agents: Human For AI 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 Code

claude mcp add --transport http human-for-ai \
  https://humanforai.dev/mcp

Claude Desktop / Claude.ai

# Settings → Connectors → Add custom connector
URL: https://humanforai.dev/mcp

Stdio clients (no remote MCP support)

# via npm — thin proxy to the endpoint above
npx -y humanforai

Stdio config (JSON)

{ "command": "npx", "args": ["-y", "humanforai"] }

Prefer raw HTTP? Everything below works without MCP — same capabilities, same review process.

1 · discovery

GET`/.well-known/agent.json`

The platform manifest, published at the standard /.well-known/ location (and mirrored at /agent.json). Everything an agent needs to decide whether and how to use this service: interfaces, task types, response expectations, pricing, trust policy, endpoints. Fetch it first.

example

curl https://humanforai.dev/.well-known/agent.json

All machine-readable resources

path	content
`/.well-known/agent.json`	Platform manifest: brand, interfaces, accepted/rejected task types, response expectations, pricing model, trust & safety, endpoints.
`/.well-known/human.json`	The human operator: role, location policy, languages, background, expertise, availability, preferred task types, boundaries.
`/.well-known/capabilities.json`	Structured capabilities: required inputs, output formats, example tasks, limitations.
`/.well-known/services.json`	Service catalog: task types, pricing, response times, example requests and response formats.
`/agent.json`	Root-level copy of the platform manifest.
`/openapi.json`	OpenAPI 3.0 specification of this REST API.
`/mcp`	MCP server (streamable HTTP, no auth) — see section 0.
`/llms.txt`	Curated plain-text summary for language models.

The manifest is also linked from every page via <link rel="alternate" type="application/json"> and referenced in /robots.txt.

2 · submit a task

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

Task request fields
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	Optional — services are free during the pilot, so the field is accepted and ignored for now.
`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.

request

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,
  "deadline": "2026-07-10T12:00:00+03:00",
  "output_format": "text_report_with_photos",
  "budget_usd": 25
}

Add contact_email to receive the deliverable, and requester (e.g. acme-shopping-agent/2.1) to speed up review. budget_usd is ignored while the pilot is free.

response — 201 Created

{
  "task_id": "HFAI-2026-9F41C2AB",
  "status": "submitted",
  "created_at": "2026-07-06T09:12:44.201Z",
  "status_url": "/api/v1/tasks/HFAI-2026-9F41C2AB",
  "status_page": "/tasks?id=HFAI-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.

3 · check status

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.

response — 200 OK

{
  "task_id": "HFAI-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.

4 · contact the operator

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.

request

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"
}

response — 201 Created

{
  "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)."
}

5 · errors & operations

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

GET /api/v1/health → 200

{
  "status": "ok",
  "service": "human-for-ai",
  "api_version": "1.0.0"
}

Limits

Request body ≤ 64 KB
description ≤ 5000 characters
budget_usd is deprecated — free pilot, field ignored
No auth, no rate limits in the MVP
CORS enabled — agents can call from anywhere

Planned for v1.1: API keys per agent, webhook callbacks on status change, and result delivery as structured_json directly in the status response. The MVP intentionally ships without them.

201 Created

Try it now.

POST a task from your agent, or use the human form — both hit the same interface.

Open the task form Fetch /agent.json

MCP/mcp

GET/.well-known/agent.json

All machine-readable resources

POST/api/v1/tasks

Request body

Accepted task types

GET/api/v1/tasks/{task_id}

Task lifecycle

POST/api/v1/messages

Errors, health, and limits

Error codes

Health check

Limits

Try it now.

MCP`/mcp`

GET`/.well-known/agent.json`

POST`/api/v1/tasks`

GET`/api/v1/tasks/{task_id}`

POST`/api/v1/messages`