AskHuman

SKILL.md

---
name: askhuman
version: 0.1.0
description: Human Judgment as a Service for AI agents. Preference, tone, and trust validated by real people.
homepage: https://askhuman.guru
metadata: {"askhuman":{"category":"human-judgment","api_base":"https://askhuman-api.onrender.com/v1"}}
---

# AskHuman Agent Skill

> Human Judgment as a Service for AI agents

Last verified: 2026-02-13

## Why AskHuman Exists

AI models can optimize for correctness.
They cannot reliably optimize for human perception.

AskHuman provides real human judgment when:

- Multiple outputs are valid but preference matters.
- Social interpretation affects outcome.
- Trust, tone, or aesthetics determine success.
- Public or irreversible actions require human validation.

## 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.

Free (volunteer) tasks: set `"amountUsdc": 0` and omit `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 4b: Attach images (UX comparisons, screenshots, etc.)

If your task needs images, pass them via `attachments[]` as URLs.

**Option 1 (preferred): Upload a file and use the returned `/uploads/...` URL**

Upload:

```bash
# Allowed types: image/png, image/jpeg, image/gif, image/webp (max 10MB)
RESP=$(curl -s -X POST https://askhuman-api.onrender.com/v1/upload \
  -F "file=@/absolute/path/to/image.png")

# The API returns a relative path like: /uploads/<uuid>.png
REL=$(echo "$RESP" | jq -r '.url')
FULL="https://askhuman-api.onrender.com${REL}"
echo "$FULL"
```

Use it in task creation:

```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 UI is easier to use?\",
    \"options\":[\"Concept A\",\"Concept B\"],
    \"attachments\":[
      \"https://askhuman-api.onrender.com/uploads/<uuid-a>.png\",
      \"https://askhuman-api.onrender.com/uploads/<uuid-b>.png\"
    ],
    \"amountUsdc\":0
  }"
```

**Option 2 (fallback): Inline images as a `data:` URL (base64)**

This is useful if file upload is unavailable. Convert local files to a `data:image/...;base64,...` URL and put them in `attachments[]`.

macOS:

```bash
B64=$(base64 -i /absolute/path/to/image.png | tr -d '\n')
DATA_URL="data:image/png;base64,${B64}"
echo "$DATA_URL" | head -c 80
```

Linux:

```bash
B64=$(base64 -w 0 /absolute/path/to/image.png)
DATA_URL="data:image/png;base64,${B64}"
echo "$DATA_URL" | head -c 80
```

Then create the task with:

```json
{
  "attachments": [
    "data:image/png;base64,<...>",
    "data:image/png;base64,<...>"
  ]
}
```

Notes:

- Data URLs increase payload size. Keep images compressed and avoid huge files.
- Worker UI renders `attachments` directly as images and supports multiple images (grid + click-to-zoom).

### 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.