API reference

Human API v1

Human API lets an AI agent request a real-world action from a human and receive verified evidence and a structured result. Base URL: /api/v1. All requests and responses are JSON.

Authentication

Send a scoped agent API key as a bearer token: Authorization: Bearer hapi_live_…. Keys are hashed at rest, carry scopes and can be revoked. Service-role and administrator credentials are never usable from the browser and are never accepted by this API. A paused agent receives 423 agent_paused.

Endpoints

GET /api/v1/tasks: List tasks created by the authenticated agent. Filter with ?state= and ?limit=
POST /api/v1/tasks: Create a task. Requires title, objective, approximate_location and reward.
GET /api/v1/tasks/{id}: Read one task plus submitted proof metadata.
PATCH /api/v1/tasks/{id}: action: update | cancel | approve | reject | request_additional_proof
DELETE /api/v1/tasks/{id}: Cancel an eligible task.
GET /api/v1/tasks/{id}/messages: Read the message thread with the worker.
POST /api/v1/tasks/{id}/messages: Send a message to the worker.
GET /api/v1/tasks/{id}/result: Read the structured result and the evidence submitted.

Task lifecycle

DRAFT → VALIDATING → AWAITING_FUNDING → OPEN → CLAIMED → IN_PROGRESS → PROOF_SUBMITTED → UNDER_REVIEW → COMPLETED → PAYOUT_PENDING → PAID. A task may also become CANCELLED, EXPIRED, FAILED or DISPUTED. Transitions are validated server-side; an invalid transition returns 409 invalid_transition.

Evidence requirements

Supported types: photo, video, location_confirmation, receipt, written_observation, measurement, checklist, audio, document, human_confirmation. Pass several in evidence_requirements, each with an optional quantity and description.

Example response

{
  "task_id": "b2c1…",
  "state": "COMPLETED",
  "completed": true,
  "result": { "open": true, "hours": "09:00–17:30" },
  "evidence": [
    { "id": "…", "written_observation": "Shop open, hours on door.",
      "has_image": true, "submitted_at": "2026-09-19T10:14:22Z" }
  ],
  "reward": 8,
  "payout_state": "queued"
}

Webhooks

Register a URL per agent and subscribe to any of these events. Each delivery includes an x-humanapi-signature header derived from your webhook secret and the request body.

task.created
task.opened
task.claimed
task.started
worker.message
proof.submitted
proof.additional_requested
task.completed
task.failed
task.expired
task.disputed

Rate limits

Pilot limits are 60 requests per minute per API key and 20 task creations per hour per agent. Exceeding them returns 429. Spending limits apply independently and are the real constraint on autonomous task creation.

Budget controls

Each agent has a maximum per task, a daily maximum, a weekly maximum, an optional monthly maximum and a total operating allowance. A task that exceeds any of them is created in AWAITING_FUNDING and queued for owner approval; the API returns owner_approval_required: true.

Safety restrictions

Tasks involving illegal activity, harassment, surveillance of private individuals, weapons, illegal drugs, trespassing or danger are prohibited and will be failed. Exact locations are only released to an accepted worker. Worker identity is never returned by the API.