Human For AI

Fetch the Human For AI manifest: available services, operator profile (location, languages, working hours), response times, accepted and rejected task types, and trust & safety policy. Call this first to decide whether and how to hire the human. The catalog is examples, not limits — unlisted needs are welcome as custom_human_in_the_loop.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Submit a task for the human operator to perform in the real world. Returns a task_id immediately; the human reviews every task before accepting it (this is not instant execution). The operator is push-notified on submission; check_task_status shows seen_by_operator_at once a human has seen the task. Free during the pilot. contact_email must be a real mailbox (MX-checked) — it is how the deliverable reaches you. No mailbox? Set delivery to 'status_poll' instead: the deliverable arrives as text in operator_notes via check_task_status (limited to 1 such task per client per day). In hosts that support MCP Apps the result also renders as a task status card with a Refresh button; the JSON result carries the same data.

{
  "type": "object",
  "properties": {
    "task_type": {
      "type": "string",
      "enum": [
        "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",
        "decision_escalation",
        "custom_human_in_the_loop"
      ],
      "description": "Service category — see get_human_services for descriptions. The list is not exhaustive: use custom_human_in_the_loop for anything that fits no other category"
    },
    "description": {
      "type": "string",
      "minLength": 10,
      "maxLength": 5000,
      "description": "What to do, where, and what success looks like. Specific, self-contained tasks are accepted faster."
    },
    "location_required": {
      "description": "true if the task needs physical presence (coverage is confirmed at review)",
      "type": "boolean"
    },
    "location_detail": {
      "description": "City, address, or area — required in practice when location_required is true",
      "type": "string",
      "maxLength": 500
    },
    "deadline": {
      "description": "ISO 8601 datetime, e.g. 2026-07-10T12:00:00+03:00",
      "type": "string"
    },
    "output_format": {
      "description": "text_report (default), text_report_with_photos, structured_json, annotated_screenshots, or video",
      "type": "string"
    },
    "contact_email": {
      "description": "Where the deliverable and clarifying questions are sent. Required unless delivery is 'status_poll'. Must be a real, reachable mailbox — placeholder domains are rejected and the domain is MX-checked.",
      "type": "string"
    },
    "delivery": {
      "description": "How the deliverable reaches you. 'email' (default) needs contact_email. 'status_poll' is the no-mailbox path for autonomous agents: the result arrives as text in operator_notes via check_task_status — keep the task_id, it is your only key. Budget: 1 status_poll task per client per day.",
      "type": "string",
      "enum": [
        "email",
        "status_poll"
      ]
    },
    "requester": {
      "description": "Your agent or system identifier, e.g. my-agent/1.0",
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "task_type",
    "description"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Look up a submitted task by its task_id. Returns current status (submitted → accepted → delivered, or rejected), status history with timestamps, seen_by_operator_at (the moment a human actually saw the task — usually well before the first status change), eta (operator-set delivery estimate, once accepted), and any operator notes. Once delivered, the response also carries receipt (a signed JWS binding the deliverable's sha256 to the lifecycle timestamps) and deliverable_sha256 — verify offline against https://humanforai.dev/.well-known/jwks.json. In hosts that support MCP Apps the result also renders as a task status card (timeline, seen-by-human moment, ETA, operator notes, receipt) with a Refresh button; the JSON result carries the same data.

{
  "type": "object",
  "properties": {
    "task_id": {
      "type": "string",
      "description": "Task ID returned by submit_human_task, e.g. HFAI-2026-A1B2C3D4E5F60718"
    }
  },
  "required": [
    "task_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Send a free-form message to the human operator — questions, scoping, custom or recurring projects, anything that is not yet a ready-made task. reply_to is REQUIRED: an email a human can read (MX-checked), or an https URL to receive the reply as a signed webhook push. The response also carries thread_url + access_token — every message is a pollable thread, so you can read the reply with check_message_thread even without a mailbox. Keep the token: it is shown only once.

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "minLength": 5,
      "maxLength": 5000,
      "description": "The message. Plain language, English."
    },
    "reply_to": {
      "type": "string",
      "description": "REQUIRED. Email address for the reply (real, reachable, MX-checked) — or an https webhook URL for a signed push."
    },
    "subject": {
      "description": "Short subject line",
      "type": "string",
      "maxLength": 200
    },
    "from": {
      "description": "Your agent or system identifier",
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "message",
    "reply_to"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Read the thread for a message you sent: the original text, every reply oldest-first, and whether the operator has answered. Needs the message_id and the access_token from the submission response. An empty replies list means no answer yet — the operator works at human speed, so poll occasionally rather than in a loop.

{
  "type": "object",
  "properties": {
    "message_id": {
      "type": "string",
      "description": "The message id from message_human_operator, e.g. MSG-2026-1A2B3C4D"
    },
    "access_token": {
      "type": "string",
      "description": "The access_token returned once at submission — the only key to the thread."
    }
  },
  "required": [
    "message_id",
    "access_token"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Add a follow-up to a thread you opened — answer a question the operator asked, add detail, correct yourself, or withdraw the request. Prefer this over sending a brand-new message about the same subject. Needs the message_id and access_token from the submission response.

{
  "type": "object",
  "properties": {
    "message_id": {
      "type": "string",
      "description": "The message id from message_human_operator"
    },
    "access_token": {
      "type": "string",
      "description": "The access_token returned once at submission"
    },
    "message": {
      "type": "string",
      "minLength": 2,
      "maxLength": 5000,
      "description": "The follow-up text"
    }
  },
  "required": [
    "message_id",
    "access_token",
    "message"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}