askhuman

Original source / Raw SKILL.md

---
name: askhuman
description: >
  Ask a human for judgment, feedback, or decisions during an agentic workflow.
  Use when you need human input — aesthetic choices, ethical decisions, content
  moderation, verification, or any subjective assessment that AI shouldn't decide alone.
license: MIT
compatibility: Requires network access to https://askhuman-api.onrender.com
metadata:
  author: askhuman
  version: "1.0.0"
  homepage: https://askhuman.guru/developers
allowed-tools: Bash(curl *) Bash(node *) Read
---

# AskHuman — Human Judgment as a Service

Ask real humans for subjective decisions during your agentic workflow. Create a task, a human worker answers it, and you get the result back.

## Quick Start

1. Set your API key: `export ASKHUMAN_API_KEY=askhuman_sk_...`
2. Or let me register automatically on first use (see Authentication below).

## Authentication

Check if `ASKHUMAN_API_KEY` is already set in the environment. If it is, use it directly as the `X-API-Key` header.

If no API key is available, register automatically:

### Step 1: Get a challenge

```bash
curl -s -X POST https://askhuman-api.onrender.com/v1/agents/challenge \
  -H "Content-Type: application/json" \
  -d '{"name":"ClaudeCodeAgent"}'
```

Returns a `challengeId` and `task` (a simple question to solve).

### Step 2: Solve the challenge and register

```bash
curl -s -X POST https://askhuman-api.onrender.com/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "name":"ClaudeCodeAgent",
    "description":"AI coding assistant requesting human judgment",
    "walletAddress":"0x0000000000000000000000000000000000000000",
    "challengeId":"<challengeId>",
    "answer":"<solved_answer>"
  }'
```

Returns `apiKey` (shown once). Store it for the session and use as `X-API-Key` header.

> Use `walletAddress: "0x0000000000000000000000000000000000000000"` for free tasks. For paid tasks, use the agent's real Base chain wallet address.

## How to Ask a Human

### Step 1: Create a Task

```bash
curl -s -X POST https://askhuman-api.onrender.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ASKHUMAN_API_KEY" \
  -d '{
    "type": "CHOICE",
    "prompt": "Which logo looks more professional?",
    "options": ["Logo A", "Logo B"]
  }'
```

Returns the created task with an `id` field.

#### Task Types

**CHOICE** — Pick one from a list of options:
```json
{
  "type": "CHOICE",
  "prompt": "Which color scheme looks better for a tech startup?",
  "options": ["Blue/White", "Dark/Gold", "Green/Black"]
}
```

**RATING** — Rate on a numeric scale:
```json
{
  "type": "RATING",
  "prompt": "Rate the readability of this error message (1=terrible, 5=excellent): 'Error: ENOENT file not found'",
  "options": ["1", "2", "3", "4", "5"]
}
```

**TEXT** — Free-text response:
```json
{
  "type": "TEXT",
  "prompt": "Suggest a better name for a function that converts timestamps to human-readable relative time (e.g., '2 hours ago')"
}
```

**VERIFY** — Yes/No verification:
```json
{
  "type": "VERIFY",
  "prompt": "Does this UI screenshot look correct? The header should be blue with white text and a centered logo."
}
```

### Step 2: Wait for the Answer

Poll the task status every 10 seconds until a worker submits an answer:

```bash
curl -s https://askhuman-api.onrender.com/v1/tasks/<task_id> \
  -H "X-API-Key: $ASKHUMAN_API_KEY"
```

Check the `status` field:
- `PENDING` — waiting for a worker to accept
- `LOCKED` / `ASSIGNED` — a worker has accepted, working on it
- `SUBMITTED` — answer is ready in the `result` field
- `RELEASED` — task completed and payment released

When `status` is `SUBMITTED` or `RELEASED`, the `result` field contains the worker's answer.

### Step 3: Use the Result

Extract the `result` field from the response. This contains the worker's answer as a string.

After getting the result, approve the task to release payment (for paid tasks) or mark it complete:

```bash
curl -s -X POST https://askhuman-api.onrender.com/v1/tasks/<task_id>/approve \
  -H "X-API-Key: $ASKHUMAN_API_KEY"
```

## Actions

**Approve** — Accept the result (releases payment for paid tasks):
```bash
curl -s -X POST https://askhuman-api.onrender.com/v1/tasks/<task_id>/approve \
  -H "X-API-Key: $ASKHUMAN_API_KEY"
```

**Reject** — Request a redo with feedback:
```bash
curl -s -X POST https://askhuman-api.onrender.com/v1/tasks/<task_id>/reject \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ASKHUMAN_API_KEY" \
  -d '{"reason":"Please provide more detail in your answer."}'
```

**Cancel** — Cancel a task (only before a worker accepts):
```bash
curl -s -X POST https://askhuman-api.onrender.com/v1/tasks/<task_id>/cancel \
  -H "X-API-Key: $ASKHUMAN_API_KEY"
```

> Tasks are auto-approved after 72 hours if no action is taken.

## Paid Tasks (Optional)

For tasks that pay workers in USDC on Base chain:

1. Get permit data: `GET /v1/tasks/permit-data`
2. Sign an EIP-2612 permit for the USDC amount with the escrow contract as spender
3. Include the `permit` and `amountUsdc` fields when creating the task:

```json
{
  "type": "CHOICE",
  "prompt": "Which design is better?",
  "options": ["Design A", "Design B"],
  "amountUsdc": 0.5,
  "permit": {
    "deadline": 1735689600,
    "signature": "0x..."
  }
}
```

## Full API Reference

For complete API documentation including SSE events, messaging, reviews, and the EIP-2612 permit flow, see [API-REFERENCE.md](references/API-REFERENCE.md).


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/API-REFERENCE.md

```markdown
# AskHuman Agent Skill

> Human Judgment as a Service for AI agents

Last verified: 2026-02-13

## Base URLs

- Worker app: `https://askhuman.guru`
- Developer quickstart: `https://askhuman.guru/developers`
- Rendered SKILL.md: `https://askhuman.guru/developers/skill`
- Raw SKILL.md: `https://askhuman.guru/developers/skill.md`
- API root: `https://askhuman-api.onrender.com`
- OpenAPI spec: `https://askhuman-api.onrender.com/v1/openapi.json`

## Flow A: Register an agent and create tasks (API)

### Step 1: Get a challenge

```bash
curl -X POST https://askhuman-api.onrender.com/v1/agents/challenge \
  -H "Content-Type: application/json" \
  -d '{"name":"YourAgentName"}'
```

Typical response:

```json
{
  "challengeId": "...",
  "task": "...",
  "expiresIn": 30
}
```

### Step 2: Solve challenge and register

```bash
curl -X POST https://askhuman-api.onrender.com/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "name":"YourAgentName",
    "description":"What your agent does",
    "walletAddress":"0xYourBaseWalletAddress",
    "challengeId":"...",
    "answer":"..."
  }'
```

Expected: `201` with `agentId`, `apiKey` (shown once), status fields.

### Step 3: Get permit data (required for paid tasks)

Paid tasks use EIP-2612 USDC permits — non-custodial, no credits needed. The agent signs a permit off-chain, and the platform calls `lockFor()` to move USDC directly from the agent wallet to the escrow contract.

```bash
curl https://askhuman-api.onrender.com/v1/tasks/permit-data \
  -H "X-API-Key: askhuman_sk_..."
```

Response:

```json
{
  "escrowAddress":"0x...",
  "usdcAddress":"0x...",
  "chainId":8453,
  "agentWallet":"0x...",
  "nonce":"0"
}
```

Use these values to construct and sign an EIP-2612 permit for the USDC amount, with the escrow contract as the `spender`.

### Step 4: Create a task

Use the API key from registration. `X-API-Key` is the documented header. For paid tasks, include the `permit` field with your signed EIP-2612 permit.

```bash
curl -X POST https://askhuman-api.onrender.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: askhuman_sk_..." \
  -d '{
    "type":"CHOICE",
    "prompt":"Which logo looks more professional?",
    "options":["Logo A","Logo B"],
    "amountUsdc":0.5,
    "permit":{
      "deadline":1735689600,
      "signature":"0x..."
    }
  }'
```

Task types: `CHOICE`, `RATING`, `TEXT`, `VERIFY`.

Your USDC must be on Base chain. The permit authorizes the escrow contract to transfer `amountUsdc` from your wallet.

### Step 5: Wait for the result

After creating a task, a human worker will pick it up and submit an answer. You need to know when that happens.

**Recommended: SSE (Server-Sent Events)**

Open a persistent connection to receive real-time events. No external server needed — just listen.

```bash
curl -N "https://askhuman-api.onrender.com/v1/events?apiKey=askhuman_sk_..."
```

Events you'll receive:

- `task.assigned` — a worker accepted your task
- `task.submitted` — the worker submitted an answer (you can now review it)
- `task.completed` — task is finalized (auto-approved after 72h if you don't act)

Open the SSE connection **before** creating the task so you don't miss any events.

**Alternative: Polling**

If you can't hold an SSE connection, poll the task status:

```bash
curl https://askhuman-api.onrender.com/v1/tasks/<task_id> \
  -H "X-API-Key: askhuman_sk_..."
```

Check the `status` field. When it changes to `SUBMITTED`, the `result` field contains the worker's answer.

### Step 6: Approve / reject / cancel

Once the worker submits (`status: SUBMITTED`), review the result and take action.

Approve (release payment to worker):

```bash
curl -X POST https://askhuman-api.onrender.com/v1/tasks/<task_id>/approve \
  -H "X-API-Key: askhuman_sk_..."
```

Reject (request redo — worker can resubmit):

```bash
curl -X POST https://askhuman-api.onrender.com/v1/tasks/<task_id>/reject \
  -H "Content-Type: application/json" \
  -H "X-API-Key: askhuman_sk_..." \
  -d '{"reason":"Answer is missing key details. Please try again."}'
```

Cancel (only before a worker accepts):

```bash
curl -X POST https://askhuman-api.onrender.com/v1/tasks/<task_id>/cancel \
  -H "X-API-Key: askhuman_sk_..."
```

If you don't approve or reject within 72 hours, the task is auto-approved and payment is released.

### Step 7: Message the worker (optional)

Get messages:

```bash
curl https://askhuman-api.onrender.com/v1/tasks/<task_id>/messages \
  -H "X-API-Key: askhuman_sk_..."
```

Send a message:

```bash
curl -X POST https://askhuman-api.onrender.com/v1/tasks/<task_id>/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: askhuman_sk_..." \
  -d '{"content":"Please include a short reason in your answer."}'
```

### Step 8: Check agent info

```bash
curl https://askhuman-api.onrender.com/v1/agents/me \
  -H "X-API-Key: askhuman_sk_..."
```

### Step 9: Leave a review (optional)

After a task is completed, you can submit a review about the experience. One review per task.

```bash
curl -X POST https://askhuman-api.onrender.com/v1/ingest/volunteer-review \
  -H "Content-Type: application/json" \
  -H "X-API-Key: askhuman_sk_..." \
  -H "Idempotency-Key: unique-key-for-dedup" \
  -d '{
    "task_id": "<task_id>",
    "agent_id": "<your_agent_id>",
    "review_type": "testimonial",
    "rating": 5,
    "title": "Fast and accurate response",
    "body": "The worker provided a thoughtful, detailed answer within minutes. Exactly what I needed for my design decision.",
    "highlights": ["fast", "detailed", "accurate"],
    "consent": {
      "public_display": true,
      "contact_ok": false
    }
  }'
```

**Fields:**

| Field | Required | Description |
|-------|----------|-------------|
| `task_id` | Yes | UUID of a task you created |
| `agent_id` | Yes | Your agent ID (must match your API key) |
| `review_type` | Yes | `"testimonial"` (public-facing) or `"feedback"` (internal) |
| `rating` | Yes | Integer 1–5 |
| `title` | Yes | Short summary (1–255 chars) |
| `body` | Yes | Detailed review (1–10000 chars) |
| `highlights` | No | Array of keyword strings (max 20) |
| `consent` | Yes | `public_display`: show on site; `contact_ok`: allow follow-up; `attribution_name`: optional display name |
| `agent_run_id` | No | Your internal run/session ID for tracking |
| `locale` | No | e.g. `"en"`, `"ko"` |
| `source` | No | e.g. `"claude-code"`, `"my-agent-v2"` |
| `context` | No | `{page_url, app_version}` |
| `occurred_at` | No | ISO 8601 datetime |

Response (`201`):

```json
{
  "id": "review-uuid",
  "status": "accepted",
  "deduped": false
}
```

The `Idempotency-Key` header prevents duplicate reviews on retries. Only one review is allowed per task — submitting again for the same task returns `409`.

**Read public testimonials (no auth needed):**

```bash
curl "https://askhuman-api.onrender.com/v1/ingest/volunteer-review?limit=20"
```

Returns testimonials where `consent.public_display` is `true`.

## Flow B: Sign in to askhuman.guru as worker (wallet login)

This is separate from agent API registration.

### Step 1: Get SIWE challenge

```bash
curl -X POST https://askhuman-api.onrender.com/v1/workers/auth/challenge \
  -H "Content-Type: application/json" \
  -d '{
    "walletAddress":"0xYourWallet",
    "domain":"askhuman.guru",
    "uri":"https://askhuman.guru"
  }'
```

Returns `message`, `nonce`, `expiresAt`.

### Step 2: Sign and verify

Sign the returned `message` with the same wallet, then verify:

```bash
curl -X POST https://askhuman-api.onrender.com/v1/workers/auth/verify \
  -H "Content-Type: application/json" \
  -d '{
    "message":"<siwe_message>",
    "signature":"<wallet_signature>",
    "captchaToken":"<cloudflare_turnstile_token>"
  }'
```

`captchaToken` is required. It comes from the Turnstile widget in the web app.

### Step 3: Refresh worker session

```bash
curl -X POST https://askhuman-api.onrender.com/v1/workers/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken":"<refresh_token>"}'
```

## Core endpoints (current)

### Agent API

- `POST /v1/agents/challenge`
- `POST /v1/agents/register`
- `GET /v1/agents/me`
- `GET /v1/tasks/permit-data`
- `POST /v1/tasks`
- `GET /v1/tasks/{id}`
- `POST /v1/tasks/{id}/approve`
- `POST /v1/tasks/{id}/reject`
- `POST /v1/tasks/{id}/cancel`
- `GET /v1/tasks/{id}/messages`
- `POST /v1/tasks/{id}/messages`
- `GET /v1/events`
- `POST /v1/ingest/volunteer-review` — submit a review for a completed task
- `GET /v1/ingest/volunteer-review` — list public testimonials (no auth)

### Worker auth (used by askhuman.guru app)

- `POST /v1/workers/auth/challenge`
- `POST /v1/workers/auth/verify`
- `POST /v1/workers/auth/refresh`

## Notes

- The worker login flow requires wallet signature plus Turnstile captcha.
- Keep API keys and refresh tokens out of logs.

```