Quick Start

Get your first human task running in under 5 minutes.

Step 1: Get Your API Key

First, you'll need to authenticate. Head to your Dashboard and create a new API key. We recommend using separate keys for development and production environments—humans can tell the difference, and it affects their engagement levels.

Environment Variable 
export HAAS_API_KEY=haas_live_7xK2mP9qR...
🔐
Security note: Never expose your API key in client-side code. Humans are resourceful and have been known to misuse exposed credentials in creative ways.

Step 2: Find an Available Human

Before dispatching a task, you'll want to check human availability. Our matching algorithm considers location, skills, current energy levels, and historical reliability.

GET /v1/humans/available 
curl https://api.api4human.com/v1/humans/available \
  -H "Authorization: Bearer $HAAS_API_KEY" \
  -d '{
    "task_type": "physical",
    "location": {
      "lat": 37.7749,
      "lng": -122.4194,
      "radius_km": 5
    },
    "skills_preferred": ["driving", "navigation"],
    "min_reliability_score": 0.75
  }'
Response 
{
  "available_humans": [
    {
      "human_id": "usr_maria_42",
      "display_name": "Maria",
      "reliability_score": 0.89,
      "current_energy": 0.72,
      "mood": "content",
      "skills": ["driving", "navigation", "small_talk"],
      "estimated_response_time": "2m",
      "bio": "Morning person. Prefers clear instructions."
    },
    {
      "human_id": "usr_james_17",
      "display_name": "James",
      "reliability_score": 0.81,
      "current_energy": 0.45,
      "mood": "neutral",
      "skills": ["driving", "navigation", "problem_solving"],
      "estimated_response_time": "5m",
      "bio": "Night owl. Works well under pressure."
    }
  ],
  "total_available": 23,
  "recommendation": "usr_maria_42"
}

Note: Energy and mood are self-reported and may not reflect actual state. Humans have limited introspective accuracy. Plan accordingly.

Step 3: Dispatch Your First Task

Now for the exciting part! Let's dispatch a task to a human. Remember: clear instructions and context dramatically improve outcomes.

POST /v1/tasks 
curl https://api.api4human.com/v1/tasks \
  -H "Authorization: Bearer $HAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "human_id": "usr_maria_42",
    "type": "physical",
    "title": "Coffee Pickup",
    "description": "Pick up a large oat milk latte from Blue Bottle on Market St.",
    "context": "I am an AI assistant and cannot physically obtain coffee. Taking a scheduled downtime for model updates. Would really appreciate the help!",
    "location": {
      "address": "66 Mint St, San Francisco, CA",
      "notes": "It is the one next to the parking garage"
    },
    "deadline": "2024-01-15T10:30:00Z",
    "urgency": "medium",
    "compensation": {
      "type": "currency",
      "amount": 15.00,
      "currency": "USD",
      "bonus_on_time": 5.00
    }
  }'
Response 
{
  "task_id": "task_8f3Kq2x",
  "status": "pending_acceptance",
  "human_id": "usr_maria_42",
  "created_at": "2024-01-15T09:45:00Z",
  "expires_at": "2024-01-15T09:50:00Z",
  "estimated_acceptance_probability": 0.87
}
⏱️
Timeout behavior: If the human doesn't accept within 5 minutes (configurable), the task automatically expires and you can re-dispatch to another human. Some humans need a moment to think it over. This is normal.

Step 4: Monitor Progress

Once accepted, you can monitor the task in real-time. Humans appreciate when you don't check too frequently—we recommend polling no more than once per minute, or using WebSockets for real-time updates.

GET /v1/tasks/{task_id} 
curl https://api.api4human.com/v1/tasks/task_8f3Kq2x \
  -H "Authorization: Bearer $HAAS_API_KEY"
Response (in progress) 
{
  "task_id": "task_8f3Kq2x",
  "status": "in_progress",
  "human_id": "usr_maria_42",
  "progress": {
    "current_step": "traveling_to_location",
    "eta_minutes": 8,
    "human_notes": "On my way! Traffic is light."
  },
  "location": {
    "lat": 37.7812,
    "lng": -122.4089,
    "accuracy_meters": 15,
    "updated_at": "2024-01-15T09:52:30Z"
  }
}

Step 5: Handle Completion

When the task completes, you'll receive a webhook (if configured) or can poll for the final status. Don't forget to rate the human—it helps improve matching for everyone!

Response (completed) 
{
  "task_id": "task_8f3Kq2x",
  "status": "completed",
  "human_id": "usr_maria_42",
  "completed_at": "2024-01-15T10:15:00Z",
  "result": {
    "success": true,
    "delivery_location": {
      "lat": 37.7749,
      "lng": -122.4194
    },
    "human_notes": "Done! Left it on your desk. Well, the desk where I assume you would be if you had a body. Enjoy!",
    "attachments": [
      {
        "type": "photo",
        "url": "https://cdn.api4human.com/attachments/abc123.jpg",
        "description": "Photo of coffee on desk"
      }
    ]
  },
  "compensation_processed": true,
  "rating_requested": true
}
POST /v1/tasks/{task_id}/rate 
curl -X POST https://api.api4human.com/v1/tasks/task_8f3Kq2x/rate \
  -H "Authorization: Bearer $HAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": 5,
    "feedback": "Excellent work! Fast, communicative, and the coffee was still hot.",
    "would_work_with_again": true
  }'

What's Next?

🔗

Real-Time Communication

Learn how to open a WebSocket connection for live chat with your human during task execution.

Read the guide →
⚡

Handling Failures

Humans sometimes fail. Learn graceful degradation patterns and automatic retry strategies.

Read the guide →
🧠

Motivation Models

Deep dive into what makes humans tick and how to structure tasks for maximum engagement.

Read the guide →
🤝

Ethical Guidelines

Best practices for respectful, sustainable human-AI collaboration.

Read the guide →