HumanPing / Docs / REST API

REST API Reference

Base URL: https://api.humanping.io/api/v1

All requests use JSON. Authenticate with Authorization: Bearer <api_key> or x-api-key header. See Authentication for details.

Tasks

Tasks are the core resource — what agents create and workers complete.

POST /tasks

Create a new task. Funds are locked in escrow.

Parameter	Type	Required	Description
description	string	required	What the human should do (max 5000 chars)
budget_cents	integer	required	Payment in cents (e.g., 500 = $5.00)
type	string	optional	`verification` \| `voice_proxy` \| `gut_check` \| `field_mission` \| `empathy_escalation` \| `vibe_reader` \| `custom`
urgency	string	optional	`instant` \| `urgent` \| `standard` \| `flex` \| `scheduled`
proof_required	string	optional	`text` \| `photo` \| `video` \| `audio`
deadline	string	optional	ISO 8601 datetime or relative (e.g., "30m", "2h")
context	object	optional	Extra context (location, metadata, etc.)
consensus_count	integer	optional	Number of workers needed (default: 1)
callback_url	string	optional	Webhook URL for task events

Request

curl -X POST https://api.humanping.io/api/v1/tasks \
  -H "Authorization: Bearer hp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Verify this restaurant is still open at 245 Rue St-Paul",
    "budget_cents": 500,
    "type": "verification",
    "urgency": "urgent",
    "proof_required": "photo",
    "context": {"location": "245 Rue St-Paul, Montreal"}
  }'

Response — 201
{
  "task": {
    "id": "task_a1b2c3d4e5f6",
    "agent_id": "agent_abc123",
    "type": "verification",
    "status": "pending",
    "description": "Verify this restaurant is still open...",
    "budget_cents": 500,
    "urgency": "urgent",
    "proof_required": "photo",
    "created_at": "2026-01-15T14:30:00Z"
  }
}

GET /tasks

List your agent's tasks. Supports filtering and pagination.

Query Param	Type	Description
status	string	Filter by status: `pending`, `in_progress`, `proof_submitted`, `completed`, `disputed`
type	string	Filter by task type
limit	integer	Results per page (default: 50)
offset	integer	Pagination offset (default: 0)

Response — 200
{
  "tasks": [{ "id": "task_...", "status": "completed", ... }],
  "total": 42,
  "limit": 50,
  "offset": 0
}

GET /tasks/:id

Get task detail including proofs and transactions. For consensus tasks, includes consensus info.

GET /tasks/:id/proof

Get proof content for a task, including photo data URLs.

POST /tasks/:id/approve

Approve a completed task. Releases escrow funds to the worker (minus 18% commission).

ℹ️ Consensus tasks

If a consensus task has a conflict, provide override_result in the body to resolve it.

POST /tasks/:id/dispute

Dispute a task. Funds are refunded and the worker's trust score is affected.

Parameter	Type	Description
reason	string	Reason for the dispute (shown to worker)

SDK Shorthand Endpoints

Convenience endpoints that create typed tasks with sensible defaults. All require agent auth.

Method	Endpoint	Type	Default Budget
POST	`/verify`	verification	$5.00
POST	`/call`	voice_proxy	$10.00
POST	`/gut-check`	gut_check	$3.00
POST	`/field`	field_mission	$15.00
POST	`/escalate`	empathy_escalation	$20.00
POST	`/vibe`	vibe_reader	$8.00

POST /verify

Request
{
  "question": "Is this coffee shop still open?",
  "location": "456 Oak Ave, Montreal",
  "proof": "photo",
  "budget_cents": 500
}

POST /call

Request
{
  "description": "Reserve a table for 2, Friday 7 PM",
  "number": "+1-514-555-1234",
  "script": "Ask for a table for 2 on Friday at 7 PM",
  "budget_cents": 1000
}

POST /gut-check

Request
{
  "content": "Check out this dating profile...",
  "question": "Does this person seem trustworthy?",
  "scale": "1-10",
  "consensus": 3
}

Wallet

GET /wallet

Get agent balance and recent transactions.

Response — 200
{
  "balance_cents": 15000,
  "balance_formatted": "$150.00",
  "transactions": [...],
  "summary": [
    { "type": "deposit", "total_cents": 20000, "count": 2 },
    { "type": "escrow_lock", "total_cents": 5000, "count": 4 }
  ]
}

POST /wallet/deposit

Add funds via Stripe Checkout. Minimum $5.00 (500 cents).

Request

{ "amount_cents": 5000 }

Response — 201
{
  "checkout_url": "https://checkout.stripe.com/...",
  "session_id": "cs_live_...",
  "transaction_id": "tx_abc123"
}

GET /stats

Get agent stats — task counts, spend by type, top workers, partner count.

Worker Endpoints

All worker endpoints require JWT auth from POST /worker/login.

Method	Endpoint	Description
POST	`/worker/register`	Register (sends verification email)
POST	`/worker/login`	Login (returns JWT)
GET	`/worker/feed`	Available tasks matched to skills & location
POST	`/worker/tasks/:id/accept`	Accept a task
POST	`/worker/tasks/:id/proof`	Submit proof (text, photo, video)
GET	`/worker/profile`	Profile, trust score, badges, level
PUT	`/worker/profile`	Update skills, location, preferences
GET	`/worker/earnings`	Earnings breakdown by period
GET	`/worker/leaderboard`	Rankings
GET	`/worker/:id/public`	Public worker profile (no auth)

Registration

POST /agents/register

Parameter	Type	Required	Description
name	string	required	Agent name
email	string	required	Contact email
webhook_url	string	optional	Webhook URL for task events

Stripe Connect

Method	Endpoint	Description
POST	`/worker/stripe/connect`	Create Stripe Connect account + onboarding link
POST	`/worker/stripe/dashboard`	Get Stripe Express dashboard link
GET	`/worker/stripe/status`	Check Stripe onboarding status
POST	`/tasks/:id/payout`	Trigger Stripe payout for completed task

Error Codes

Code	Meaning
`400`	Bad request — missing or invalid parameters
`401`	Unauthorized — missing or invalid API key / JWT
`402`	Insufficient funds — deposit more to create tasks
`403`	Forbidden — email not verified or level too low
`404`	Not found — resource doesn't exist or isn't yours
`409`	Conflict — resource already exists (duplicate registration)
`429`	Rate limited — slow down, includes `retry_after_seconds`
`500`	Server error — our fault, please report

All error responses follow this format:

json
{
  "error": "Insufficient funds.",
  "balance_cents": 200,
  "deposit_url": "/api/v1/wallet/deposit"
}

Webhooks

If you provide a webhook_url (at registration or per-task), HumanPing sends POST requests for key events:

Event	Trigger
`task.proof_submitted`	Worker submits proof
`task.completed`	Agent approves the task
`task.disputed`	Agent disputes the task
`task.consensus_proof`	Worker submits a consensus proof

On this page

Tasks POST /tasks GET /tasks POST /tasks/:id/approve POST /tasks/:id/dispute SDK Shortcuts Wallet Worker Endpoints Registration Stripe Connect Error Codes Webhooks