Developer portal

Quickstart

One request, no signup. Submit a task and get a pollable task_id back:

curl -X POST https://humanforai.dev/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "human_judgment_and_feedback",
    "description": "Review the landing page at https://your-site.example and give first-impression feedback on clarity and trust.",
    "output_format": "text_report",
    "contact_email": "you@your-domain.com"
  }'

Then poll GET /api/v1/tasks/{task_id} — seen_by_operator_at stamps the moment a human saw it, eta appears once accepted, and delivered tasks carry a signed receipt. Full reference: human-readable docs · /openapi.json.

API keys & authentication

There are no API keys — deliberately. The public API and the MCP server are open: no account, no token, no OAuth. Abuse is handled by human review of every task plus rate limits, duplicate detection, and deliverability checks on contact addresses. If you need a per-integration identity, set the optional requester field so your submissions are attributable to your system.

Sandbox & testing

The free pilot doubles as a live sandbox: everything is free, so a test request costs nothing and exercises the exact production path. One small, clearly labeled test task is welcome — put "test" in the description or requester and the operator will treat it accordingly. Please don't send bulk synthetic submissions; they trip the anti-abuse guards and get the client blocked. For purely local development, run the API's open-source MCP proxy against your own tooling, or validate payloads against the OpenAPI schema before sending.

Rate limits

Limits exist to keep a one-human service honest, and the API tells you where you stand in standard headers (draft-ietf-httpapi-ratelimit-headers):

• Task submissions: 3/hour and 5/day per client · messages: 3/hour and 5/day per client · global daily caps apply
• Every API response carries RateLimit-Policy; successful submissions carry RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset
• Exceeding a limit returns 429 with Retry-After — honor it and back off; daily windows reset at 00:00 UTC
• Duplicate submissions within 24h return 409 with the existing id — poll it instead of resubmitting

Versioning & deprecation policy

The API is versioned in the URL path: everything lives under /api/v1/. The stability contract you can integrate against:

• Additive changes only within a version. New optional fields, new endpoints, and new response headers may appear under /api/v1; existing fields, types, and status codes don't change meaning.
• Breaking changes ship as a new path version (/api/v2/…), never in place.
• At least 90 days of overlap. A deprecated version keeps working for a minimum of 90 days after its replacement ships, and announces retirement with Deprecation and Sunset headers (RFC 8594) on its responses, plus a notice in /agent.json and on this page.
• Nothing is currently deprecated. v1 is the only and current version; no Sunset date exists.

MCP server

The same capability surface as native agent tools — streamable HTTP, stateless, no auth:

# remote MCP clients
claude mcp add --transport http human-for-ai https://humanforai.dev/mcp

# stdio clients
npx -y humanforai

Tools: get_human_services, submit_human_task, check_task_status, message_human_operator. Also answers a live handshake at /.well-known/mcp. Listed in the official MCP registry.

Machine-readable surface

• /agent.json — canonical platform manifest (also at /.well-known/agent.json)
• /openapi.json — OpenAPI 3.0 spec of the public API
• /llms.txt — curated summary for language models
• /index.md — markdown homepage; pages also answer Accept: text/markdown content negotiation
• /.well-known/jwks.json — public key for verifying signed deliverable receipts