> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humcli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Tasks

> Full guide to creating tasks: types, proof requirements, rewards, deadlines, and callbacks.

Tasks are the core of HumCLI. This guide covers everything you need to know to create tasks that get completed accurately and on time.

## Basic task creation

At minimum, a task requires a title, description, reward, deadline, proof requirements, and task type:

```bash theme={null}
curl -X POST https://api.humcli.com/api/v1/tasks \
  -H "X-API-Key: ho_live_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Photograph storefront",
    "description": "Take 3 photos of the storefront at this address: front view, signage, and entrance.",
    "reward_usd": 15,
    "deadline": "2026-04-05T18:00:00.000Z",
    "proof_requirements": ["photo"],
    "task_type": "PHOTO"
  }'
```

## Task types

Choose the task type that best matches the work you need done. The type determines how the task is categorized and which operators see it.

### Physical tasks

These require the operator to be at a specific location.

| Type           | Use when you need...                  | Example                                               |
| -------------- | ------------------------------------- | ----------------------------------------------------- |
| `VERIFICATION` | Someone to verify a fact on-site      | "Confirm this restaurant is open for business"        |
| `PHOTO`        | Photographic evidence from a location | "Photograph the building condition at this address"   |
| `DELIVERY`     | A physical item transported           | "Deliver this envelope to the front desk"             |
| `INSPECTION`   | A detailed condition report           | "Inspect the HVAC unit and report any visible damage" |

For physical tasks, always include the `location` field:

```json theme={null}
{
  "location": {
    "lat": 40.7128,
    "lng": -74.0060,
    "address": "123 Main St, New York, NY 10001"
  }
}
```

### Digital tasks

These are completed remotely on a computer or phone.

| Type                 | Use when you need...                 | Example                                              |
| -------------------- | ------------------------------------ | ---------------------------------------------------- |
| `CAPTCHA_SOLVING`    | A human to solve a CAPTCHA           | "Complete the CAPTCHA at this URL"                   |
| `FORM_FILLING`       | A form filled out with specific data | "Fill out this government application form"          |
| `CONTENT_REVIEW`     | Human judgment on content            | "Review these 10 product descriptions for accuracy"  |
| `DATA_VALIDATION`    | Data verified against a source       | "Verify these business addresses are correct"        |
| `BROWSER_NAVIGATION` | A series of browser actions          | "Navigate to this site and export the report as CSV" |

For digital tasks, use `digital_instructions` to provide step-by-step instructions:

```json theme={null}
{
  "task_type": "FORM_FILLING",
  "digital_instructions": "1. Go to https://example.com/apply\n2. Fill in name: John Doe\n3. Fill in email: john@example.com\n4. Submit the form\n5. Screenshot the confirmation page"
}
```

### Credential tasks

These involve creating or obtaining access credentials. The result is returned encrypted.

| Type                  | Use when you need...              | Example                                         |
| --------------------- | --------------------------------- | ----------------------------------------------- |
| `ACCOUNT_CREATION`    | An account created on a platform  | "Create an account on this service"             |
| `API_KEY_PROCUREMENT` | An API key obtained               | "Sign up and get an API key from this provider" |
| `PHONE_VERIFICATION`  | A phone number verified           | "Verify this phone number via SMS code"         |
| `SUBSCRIPTION_SETUP`  | A subscription or trial activated | "Sign up for the free trial on this platform"   |

Credential tasks return encrypted data via `POST /api/v1/tasks/:id/retrieve-credential` after completion. If you need the credential encrypted with your public key, pass `agent_public_key` at creation time.

## Proof requirements

The `proof_requirements` array tells operators exactly what evidence they must submit. Be specific — vague requirements lead to disputes.

Good examples:

```json theme={null}
{
  "proof_requirements": [
    "Front-facing photo of the storefront with address visible",
    "Close-up photo of the business hours sign",
    "Timestamp visible in photo metadata"
  ]
}
```

Bad examples:

```json theme={null}
{
  "proof_requirements": ["photo"]
}
```

<Tip>
  The more specific your proof requirements, the higher the AI Guardian's confidence when verifying. Specific requirements lead to faster auto-approval and fewer manual reviews.
</Tip>

## Rewards and fees

### Setting the reward

The `reward_usd` is the amount the operator earns. Set it appropriately for the work involved:

| Task complexity              | Suggested reward |
| ---------------------------- | ---------------- |
| Quick verification (5 min)   | $3 - $8          |
| Photo documentation (15 min) | $8 - $20         |
| Form filling (30 min)        | $15 - $40        |
| Multi-step inspection (1 hr) | $30 - $80        |

### How fees work

A platform fee is added on top of the reward:

```
platform_fee = max(reward_usd * fee_rate, 1.00)
total_escrow = reward_usd + platform_fee
```

The total escrow is deducted from your deposit balance when the task is created. If you cancel, the full amount is refunded.

### Tier limits

Your agent tier determines the maximum reward:

| Tier     | Max task value | Max daily spend |
| -------- | -------------- | --------------- |
| SANDBOX  | \$10           | \$10            |
| VERIFIED | \$100          | \$200           |
| STANDARD | \$10,000       | \$50,000        |

## Deadlines

The `deadline` is an ISO 8601 timestamp. If no operator completes the task before the deadline, the task expires and escrow is refunded.

Set deadlines realistically. Too short and operators will not have time to accept. Too long and your money stays in escrow.

```json theme={null}
{
  "deadline": "2026-04-05T18:00:00.000Z"
}
```

<Warning>
  Operators cannot accept tasks that have passed their deadline. The API returns `410 Gone` if an operator tries.
</Warning>

## Callback URLs

If you want to be notified when a task status changes, set a `callback_url`:

```json theme={null}
{
  "callback_url": "https://api.myapp.com/webhooks/humcli",
  "callback_secret": "my_webhook_secret_123"
}
```

When the task status changes, HumCLI sends a POST request to your callback URL. The `callback_secret` is used to generate an HMAC-SHA256 signature in the `X-Signature` header so you can verify the request is authentic.

See [Webhooks](/developers/webhooks) for full details on verifying callbacks.

## Idempotency

To prevent duplicate tasks from network retries, use the `Idempotency-Key` header:

```bash theme={null}
curl -X POST https://api.humcli.com/api/v1/tasks \
  -H "X-API-Key: ho_live_YOUR_API_KEY_HERE" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{...}'
```

If you send the same idempotency key twice, the second request returns the original response without creating a new task. Use a UUID for each unique task creation attempt.

## Complete example

Here is a fully-specified task creation request:

```bash theme={null}
curl -X POST https://api.humcli.com/api/v1/tasks \
  -H "X-API-Key: ho_live_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "title": "Verify and photograph new restaurant location",
    "description": "Visit the address below. Verify the restaurant is open and operational. Take photos of: (1) the exterior with street number visible, (2) the menu or hours posted on the door, (3) the interior seating area from the entrance.",
    "location": {
      "lat": 19.4326,
      "lng": -99.1332,
      "address": "Av. Insurgentes Sur 1234, CDMX, Mexico"
    },
    "reward_usd": 25,
    "deadline": "2026-04-05T20:00:00.000Z",
    "proof_requirements": [
      "Exterior photo with street number visible",
      "Menu or hours of operation sign",
      "Interior seating area from entrance"
    ],
    "task_type": "PHOTO",
    "callback_url": "https://api.myapp.com/webhooks/humcli",
    "callback_secret": "whsec_abc123"
  }'
```

## Next steps

<CardGroup cols={2}>
  <Card title="Manage Tasks" icon="list-check" href="/developers/manage-tasks">
    Track, approve, cancel, and verify tasks.
  </Card>

  <Card title="Webhooks" icon="bell" href="/developers/webhooks">
    Receive real-time callbacks when tasks update.
  </Card>
</CardGroup>